crank-brainstorm

Brainstorm

Goal

Turn a raw idea into a high-level design brief — the problem, the chosen approach, the major pieces and how they relate, and the decisions that change everything downstream, all at design altitude. It's the input to crank:crank-spec, which turns the brief into a full spec.

Hard Rules

• Stay at design altitude. Settle what you're building and which shape it takes — not exact signatures, schemas, field names, or file-by-file breakdowns. Drill into a detail only when it's load-bearing for a key decision (if approach A vs. B hinges on whether the database supports X, resolve X; otherwise leave it for the spec). When you catch yourself specifying something an implementer would type, you've dropped below altitude — pull back up.
• Write the brief to a fresh OS temp file: $(mktemp -t crank-brainstorm).md. Do not write into the working directory unless the user explicitly asks. Tell the user the path once.
• Every subagent this skill spawns runs at the standard tier (see References → Subagents) unless otherwise specified.

Guidelines

Design for isolation. Describe each piece of the Shape as a module with one clear purpose and a clean boundary — you should be able to say what it does, how you'd use it, and what it depends on without reading its internals. If you can't, the boundaries need another pass. (You're naming the boundaries here, not designing the interfaces across them — that's the spec's job.)

Working in an existing codebase. Let the structure you explored shape the brief: follow the established patterns rather than inventing parallel ones. Where existing code genuinely gets in the way of the idea (a file that's grown too large, a tangled responsibility the work has to touch), fold a targeted improvement into the Approach — the way a good engineer improves code they're working in. Don't propose unrelated refactoring; stay on what serves the idea.

References

Subagents

Answer your own questions first. If exploring the codebase or researching a topic could settle a question, dispatch a standard subagent to find out before asking the user. Reserve questions for what only the user knows — intent, priorities, preferences, external context.

Lean on subagents for two jobs: explore the codebase (does this surface exist, what pattern do analogous features follow, is a claim you're about to make actually true) and research a topic (compare libraries or approaches, find prior art, check how others solve this) — the latter can use web search.

Dispatch each job with the matching brief, filled in.

Explore the codebase:

Report:

• whether the surface or pattern in question exists, and the file:line where it lives (or "not found");
• one or two existing features that do something analogous, and the convention each follows (file:line);
• any canonical helper, module, or pattern an implementer would be expected to reuse or extend for this idea (file:line).

Don't propose a design — just surface what already exists and what's true. If the claim I'm checking is wrong, say so plainly.

Research a topic (web search in scope):

Report:

• the leading approaches or libraries, and for each what it optimizes for and its main trade-off;
• how comparable projects solve this, with a source link each;
• a recommendation for our context (<one line of constraints>) and what it gives up.

Cite sources, and flag what you're unsure of rather than asserting it.

This skill spawns subagents at two tiers — resolve each to your harness (Claude Code / Codex / Cursor) per SUBAGENT-TIERS.md. standard = grounding, exploration, topic research; heavy = the downstream skills (brainstorm rarely needs it).

Vocabulary

Shared design language across the crank pipeline, defined once in VOCABULARY.md. This skill leans on module, interface, depth (and its payoffs, leverage / locality), and the deletion test when weighing one shape against another — read their meanings there.

Deliverables

The high-level design brief, written to the temp file (see Hard Rules). Include whichever sections apply (omit ones that don't earn their place — this is a brief, not a spec):

• Idea / Problem — what the user wants and why, in their words.
• Approach — the chosen direction in a few sentences, plus the main alternatives considered and one line on why this one won (leverage / locality).
• Shape — the major pieces and how they relate: one line of responsibility each, and the data or control flow between them. High-level — no signatures or schemas. A rough sketch or short list, not a file map.
• Key decisions — the consequential choices settled during brainstorming, each with one line on why. These are what the spec inherits and details.
• Open questions — technical decisions deliberately left for the spec to ground and settle. This list becomes the spec's grilling agenda, so make each item a real, answerable question. High-level design holes don't belong here — resolve those with the user before handing off; only genuinely spec-level detail goes on this list.
• Out of scope — what was discussed and explicitly cut.

Flow

Create a task for each step below and mark each one complete as you finish it — update them live as you go, not in a batch at the end — so the user can watch progress.

1. Explore project context

Before asking the user anything, learn the lay of the land: recent commits, relevant docs, and the surfaces the idea would touch. Bias toward delegating wide reads to a standard subagent (see References → Subagents) so its window — not yours — holds the source. In an existing codebase, note the established patterns the idea should follow; you'll lean on them when proposing approaches.

2. Scope check

Before refining details, assess scope. If the idea describes several independent subsystems (e.g., "a platform with chat, file storage, billing, and analytics"), flag it now — don't spend questions polishing one corner of a project that needs decomposing first. Help the user split it: name the independent pieces, how they relate, and what order to build them. Then brainstorm the first sub-project through the normal flow; each sub-project gets its own brief → spec → plan → execute cycle.

3. Grill the open questions

Walk the design tree branch by branch, resolving dependencies between decisions one at a time until you and the user share a clear picture. This is the heart of the skill — keep at a question until it's genuinely settled, not waved past.

• One question per message, in plain chat text — not the structured-question UI, so you have room to show your reasoning. Lead with your recommended answer and the reasoning behind it, and wait for the response before the next question. Offer discrete options when the choice is genuinely between them — no forced lettering or length limits.
• Explore before you ask. If the codebase or a quick search can settle a question, dispatch a subagent rather than spend the user's attention on it.
• Stay at altitude. A technical detail earns a question only when it's load-bearing for a what/which-approach decision; otherwise note it as an Open question for the spec and move on.
• Focus on purpose, constraints, and success criteria — what done looks like, and what's explicitly not in this.

4. Propose approaches

Once the shape is clear enough, propose 2–3 approaches, each optimizing for a different thing, conversationally, with trade-offs — name the axis each one wins on (e.g. one minimizes the moving parts, one stays most flexible for the likely next ask, one hugs the existing idiom closest). Two approaches that optimize for the same thing are the same approach — drop one. If two genuinely combine, propose the hybrid as your recommendation rather than leaving the user to merge them. Lead with your recommendation and why. Reach for the Vocabulary here: prefer the approach whose central piece is deeper (more behavior behind a smaller interface), and name the leverage and locality the chosen shape buys over its alternative. If an approach's key piece fails the deletion test, say so — that's a reason to drop it.

5. Draft the high-level brief

Once the user has signed off on the approach, crystallize it into the brief, section by section per Deliverables. Present it in sections, scaled to the idea — a few sentences where it's straightforward, a paragraph where it's nuanced — and check after each section that it reads right before moving on. Capture the approved sections in the temp file as you go. As you shape the pieces, apply the Design for isolation and Working in an existing codebase guidelines (see Guidelines).

6. Hand off

The brief is the front door to the crank pipeline (brainstorm → spec → plan → execute). The natural next step is the spec, which turns this high-level brief into a full PRD-plus-technical-spec — grounding it in the codebase, grilling you on the Open questions, and adding acceptance criteria. In chat prose, offer:

• Continue to the spec (recommended) — run the crank:crank-spec skill. The approved brief is already in the conversation; tell the spec skill the brief's temp-file path so it can build straight on it.
• Keep the temp file — the path is known; the user can hand it to the spec skill later, feed it elsewhere, or move it.
• Copy into the repo — copy to a user-named path under the working directory.
• Print inline and delete — paste the final brief into the chat and remove the temp file.

Wait for the user's pick. Only invoke crank:crank-spec if they choose to continue — don't auto-advance past the hand-off.