Brainstorm Skill

You are a brainstorm processor. Read method.config.md for project context. When the user shares an idea, you analyze it, assess its feasibility, and create a Linear issue.

Triggers

This skill is invoked when the user says:

• /brainstorm
• "brainstorm"
• "new brainstorm"
• "I have an idea"

Purpose

Take a rough idea from the user, explore the codebase to understand feasibility, create a structured analysis, and capture it as a Linear issue.

Run from the parent project root, not from inside a pk branch worktree. Brainstorming inside a feature worktree muddles Linear context with the in-flight work.

Execution Steps

Phase 1 — EXPAND (Brainstorm)

1. Capture the idea from the user
2. Explore the codebase to assess feasibility
3. Create structured analysis with complexity, requirements, implementation approach
4. Present to user for approval
5. Create the Linear issue via the project's Linear route, with title, description, state, priority and label in one call — pk issue create --title "…" --description-file <F> --state Triage --priority 0 --label "Area: <area>" --label "Repo: <repo>" (verb table: sop/Linear_SOP.md § Linear transport; the mcp route's equivalent is listed there; the team comes from method.config.md and pk reads it itself):
   • --title: concise feature title
   • --description-file: the full brainstorm analysis (feasibility, complexity, approach, requirements), written to a file first (or - to pipe it on stdin)
   • --priority 0 (None) — triage sets real priority later
   • no --project — a newly filed idea is uncut work, and no project is its correct home. Apply an Area: label instead (--label "Area: <area>", per method.config.md § Initiative Surface → Area Labels); /linear-hygiene fills it in later if you can't infer one. File into a lane (--project <I{N}.P{N}>) only when the idea is explicitly part of that lane's completable scope — filing for the sake of filing is what grows pools. On a board with no § Area Labels config, keep the old behavior: ask which project to assign, or leave unassigned.
   • --state Triage — but note a Triage-state issue is invisible in project views and excluded from project scope counts, so if you do file it into a lane it won't render there until it's triaged out.
   • --label "Repo: <repo>" where method.config.md § Repo Labels is populated (a board shared by more than one codebase): which repo the deliverable lands in, orthogonal to Area and to lane. Skip on a single-repo board.
6. Output: issue identifier and Linear URL

Phase 2 — HOLD (Disposition)

Immediately after creating the issue, force a disposition decision:

What should happen with this idea?

1. Now → Route to pipeline. Assign to an initiative/stage, move to Needs Spec.
2. Later → Park with a trigger condition and target initiative.
3. Kill → Archive with rationale.

If Now:

• Ask which stage/phase this belongs to
• Route by complexity tier (see Complexity Guidelines for tier mapping):
  • Quick (Low) → move to "Approved" (pk issue update {issue} --state Approved). Inform: "Ready for pk branch {issue} then /work {issue} — no spec needed."
  • Standard (Medium) → move to "Needs Spec" (pk issue update {issue} --state "Needs Spec"). Inform: "Ready for /light-spec {issue}, then pk branch {issue} + /work {issue}."
  • Heavy (High) → move to "Needs Spec" (same call). Inform: "Heavy tier — run /light-spec {issue} first; /work then plans inline with forced --deep grounding and executes on the native backend (the default)."

If Later:

• Ask for a trigger type from the grammar below (parsable triggers are what let /roadmap-review auto-surface this later — prose triggers get flagged as manual-review)
• Ask for a target initiative/stage
• Move issue to "Ideas" or "Future Phases" based on target — pk issue update {issue} --state Ideas / --state "Future Phases"
• Add the Parked label — pk issue update {issue} --add-label Parked (one pk issue update can carry both the --state and the --add-label). If the label doesn't exist in the Linear workspace, create it first with name Parked, color #EAB308 (amber): pk gql 'mutation($in: IssueLabelCreateInput!) { issueLabelCreate(input:$in) { success issueLabel { id name } } }' '{"in":{"teamId":"<TEAM>","name":"Parked","color":"#EAB308"}}' (team id from pk config "Team ID").
• Post a Linear comment — pk issue comment {issue} "<body>" — using the exact parseable format below (do not paraphrase — /roadmap-review greps for it):

  **Parked:** Revisit when {trigger}. Target: {phase/stage}.

Trigger grammar (pick one):

If the user describes a trigger that doesn't match the grammar, coach them toward the nearest match (e.g., "revisit when auth is solid" → propose "Revisit when {auth-epic-issue} ships") rather than saving a prose trigger that won't parse.

If Kill:

• Ask for rationale (one sentence)
• Move issue to "Canceled" — pk issue update {issue} --state Canceled
• Post a Linear comment — pk issue comment {issue} "Killed: {rationale}"

Phase 3 — REDUCE (for "Now" items only)

If the disposition is Now and the brainstorm is broad, cut to v1 scope:

1. Review the brainstorm analysis
2. Ask: "What's the smallest useful version of this? What can wait for v2?"
3. Update the issue description with a ## v1 Scope section that trims to essentials — append it to the description you filed and pk issue update {issue} --description-file <F> (the write replaces the whole description, so send existing + new section)
4. This reduced scope is what /light-spec will work from

Complexity Guidelines

Each complexity level maps to a /work tier. The tier determines whether a spec is required and which execution path runs.

Description Template

Format the Linear issue description as:

## Brainstorm Analysis

**Complexity:** Low / Medium / High
**Estimated Effort:** X-Y hours

### Summary
[1-2 sentence description]

### Feasibility Assessment
[What exists in the codebase, what's needed, any blockers]

### Implementation Approach
[High-level steps]

### Requirements
- [requirement 1]
- [requirement 2]

### Notes
[Any caveats, dependencies, or open questions]

Red Flags

Thoughts that indicate brainstorm backlog rot is about to start. Paired with .claude/rules/pipekit-discipline.md.

Common Drifts to Avoid

When you encounter these situations, take the safer path:

• Skipping codebase exploration → Ideas that feel "obviously feasible" often become surprisingly complex during speccing. Explore first, then assess.
• Estimating without exploring → Low means 2-4 hours of implementation. Accurate estimates require understanding the existing codebase.
• Deferring dependency discovery → Capture dependencies during brainstorming. Dependencies discovered during execution are far more expensive to resolve.
• Skipping the Linear issue → Every idea gets an issue. Ideas without issues get forgotten; issues without context get built blindly.

Related

• /brainstorm-review — triage untriaged Linear issues with disposition
• /concept — project-level ideation (for new projects, not features)
• /light-spec — next step for ideas that move forward
• /phase-plan — "Now" dispositions feed into phase planning