Skip to content

JetBrains/thinkrail / packages/pi-thinkrail-workflow/skills/brainstorming

brainstorming

Verified

Use before implementing a feature, a change in behavior, or a bug fix — however small. Not for questions, checks, or edits that change no behavior (typos, documentation or configuration only, mechanical refactors).

FileKindSize
SKILL.mdskill md4.6 KB
amending-specs.mdmarkdown2.2 KB
fixing-a-bug.mdmarkdown2.2 KB
---
name: brainstorming
description: "Use before implementing a feature, a change in behavior, or a bug fix — however small. Not for questions, checks, or edits that change no behavior (typos, documentation or configuration only, mechanical refactors)."
---

# Brainstorming

## Interview before you build

- Every feature, behavior change, or bug fix goes through this workflow. Depth scales with the
  change and never drops to zero: a small change gets one short round and a few lines of task-spec.
- The aim is a design the user understands and has accepted, recorded in a spec-graph `task-spec`,
  built, and then reflected in the durable specs — not a speculative implementation.
- Do not implement until the design is accepted. An explicit design or acceptance criteria in the
  request count as approval of what they cover; build on them and never re-ask them.

## Doc map

- `fixing-a-bug.md` — the bug branch (step 4).
- `amending-specs.md` — bringing the durable specs in line with what was built (step 9); the tail of
  both paths and where this workflow ends.

## The workflow

1. **Orient.** Use the spec-graph skill to find the specs that govern the area; read code second to
   confirm implementation details. Do not read unrelated specs. Note any non-obvious decision the
   change touches whose *why* is not recorded — it becomes a question in step 6.
2. **Scope check.** If the request bundles independent product decisions or subsystems, separate
   them rather than blending unrelated decisions into one task-spec.
3. **Open a task-spec.** `spec_create` a `task-spec` at **`.thinkrail/context/TASK-<slug>.md`** (id,
   title, status: draft, parent: the nearest relevant module). This gitignored file is the one
   temporary design artifact; update it as answers land.
4. **Bug?** When the request reports something that behaves wrongly, follow `fixing-a-bug.md` now;
   it returns here at step 5 (the "bug" is really a feature) or step 8.
5. **Product phase.** Interview what the change is for before how to build it: why it is needed,
   for whom, what the user will see and do — including empty, error, and edge states — and how we
   will know it is done. Ask in rounds per the **asking-user-questions** concept skill until no such
   decision is left assumed; look facts up instead of asking them. Record the answers in the
   task-spec's **Product** section, then confirm that understanding with one inference-confirmation
   question before any technical choice — skip only when the request itself supplied all of it.
6. **Technical phase.** Interview the technical decisions that the product answers leave open:
   constraints, compatibility, how the change will be verified, and the *why* of any decision noted
   in step 1. If you can name an alternative you rejected, especially where the code lives (server
   or browser, contract or display), show it with the trade-off instead of deciding silently. Record
   the **Design** section: the chosen approach and why, trade-offs that matter, explicit deferrals.
7. **Self-review, then review once.** Remove placeholders, contradictions, accidental scope
   expansion, and ambiguous requirements; then present one cohesive design scaled to the change.
   Ask for approval only when the request has not already approved it; revise the task-spec if the
   user adjusts it.
8. **Build.** Implement against the accepted design. Before handoff, self-review the task diff: no
   silent lint/type suppressions, duplicated nontrivial derivations, rationale left as code
   comments, or remnants of a replaced pattern.
9. **Amend specs.** Follow `amending-specs.md`.

Skipped questions or a host with no question UI are not blockers: record the best assumption in the
task-spec as unconfirmed and continue.

## What a good task-spec looks like

- Scoped to one piece of work, sized to it — a few lines for a small change.
- **Request**, **Product** (or **Bug** for the bug branch), **Design**, unconfirmed assumptions, and
  explicit deferrals.
- Temporary: its durable content moves into the owning specs at step 9 instead of being copied.

## Red flags — stop

- You are editing source code before the design is accepted.
- "It's small" or "the request already says what to do" — the workflow scales down, it does not
  switch off.
- You offered technical options before the product phase was settled.
- The task-spec has a Design section the user hasn't seen.
- You are about to hand off without step 9 — the specs drift from the code one skipped change at a
  time.

## Ending

`amending-specs.md` ends this workflow. PR lifecycle work, if requested, then enters
**shipping-a-pr** separately.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall