JetBrains/thinkrail / packages/pi-thinkrail-workflow/skills/brainstorming
brainstorming
VerifiedUse 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
- 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.
- Scope check. If the request bundles independent product decisions or subsystems, separate them rather than blending unrelated decisions into one task-spec.
- Open a task-spec.
spec_createatask-specat.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. - Bug? When the request reports something that behaves wrongly, follow
fixing-a-bug.mdnow; it returns here at step 5 (the "bug" is really a feature) or step 8. - 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.
- 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.
- 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.
- 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.
- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 463k | Updated | Claude CodeCodex | Verified | Install |
| 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: 195k | Updated | Claude CodeCodex | Verified | Install |
| 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: 195k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 195k | Updated | Claude CodeCodex | Verified | Install |