Brainstorming

This skill provides detailed process knowledge for effective brainstorming sessions that establish WHY we're building something, clarify WHAT to build, and map WHERE it lives in the system -- before diving into HOW to build it.

The brainstorm produces three lynchpin artifacts that anchor all downstream phases:

1. Problem Narrative & User Story -- the WHY (consumed by plan, work, and review)
2. Architectural Context Map -- the WHERE (consumed by execution agents and reviewers)
3. Design Decisions -- the WHAT (consumed by plan for task decomposition)

When to Use This Skill

Brainstorming is valuable when:

• Requirements are unclear or ambiguous
• Multiple approaches could solve the problem
• Trade-offs need to be explored with the user
• The user hasn't fully articulated what they want
• The feature scope needs refinement
• The problem statement is missing or vague (you know WHAT but not WHY)

Brainstorming can be skipped when:

• Requirements are explicit and detailed
• The user knows exactly what they want AND can articulate why
• The task is a straightforward bug fix or well-defined change

Core Process

Phase 0: Assess Requirement Clarity

Before diving into questions, assess whether brainstorming is needed.

Signals that requirements are clear:

• User provided specific acceptance criteria
• User referenced existing patterns to follow
• User described exact behavior expected
• Scope is constrained and well-defined
• Problem and motivation are explicitly stated

Signals that brainstorming is needed:

• User used vague terms ("make it better", "add something like")
• Multiple reasonable interpretations exist
• Trade-offs haven't been discussed
• User seems unsure about the approach
• WHY is missing -- user described a solution but not the problem it solves

If requirements are clear, suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."

Phase 1: Understand the Problem and the People

Ask questions one at a time to understand the user's problem space and the people affected. The goal is not just to understand WHAT they want but WHY they need it.

Question Techniques:

1. Start with the problem, not the solution
   • Good: "What problem are you trying to solve? What happens today that's painful?"
   • Avoid: "What feature do you want?" (this skips the WHY)
2. Prefer multiple choice when natural options exist
   • Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
   • Avoid: "How should users be notified?"
3. Probe for stakes and impact
   • "What happens if we don't solve this?"
   • "How are people working around this today?"
   • "What's the cost of the status quo?"
4. Validate assumptions explicitly
   • "I'm assuming users will be logged in. Is that correct?"
5. Ask about success criteria early and tie them to outcomes
   • "How will you know this feature is working well -- from the user's perspective?"
   • "What measurable change would tell you the problem is solved?"

Key Topics to Explore:

Exit Condition: Continue until you can articulate the problem, the people, and the desired outcome clearly -- OR user says "proceed" or "let's move on."

Phase 1.5: Synthesize Problem Narrative & User Story

This is the critical synthesis step. After the Q&A, the orchestrator constructs two artifacts from everything learned.

Problem Narrative (2-4 sentences): Clearly state: who has the problem, what triggers it, what the impact is, and why now is the right time to solve it. This is the WHY that every downstream phase traces back to.

Example: "Support agents currently spend 20+ minutes per ticket manually cross-referencing customer data across three systems. This leads to longer resolution times and frequent errors in billing adjustments. The upcoming Q3 volume spike will make this unsustainable."

User Story (structured format):

As a [persona with relevant context],
I need to [action/capability]
so that [desired outcome/value],
because currently [pain point or gap]
which causes [concrete negative impact].

Example:

As a support agent handling billing disputes,
I need to see all customer data consolidated in one view
so that I can resolve tickets in under 5 minutes,
because currently I have to switch between three systems
which causes 20+ minute resolution times and frequent billing errors.

Validation: Present both artifacts to the user and ask for confirmation. This is the most important step. If the problem narrative and user story are wrong, everything downstream will be misaligned.

Phase 2: Explore Approaches

After understanding the problem, propose 2-3 concrete approaches.

Critically: evaluate each approach against the problem narrative and user story.

Structure for Each Approach:

### Approach A: [Name]

[2-3 sentence description]

**How it addresses the user story:**
[Direct connection to the problem and desired outcome]

**Pros:**
- [Benefit 1]
- [Benefit 2]

**Cons:**
- [Drawback 1]
- [Drawback 2]

**Best when:** [Circumstances where this approach shines]
**Risk:** [What could go wrong, specific to the user's context]

Guidelines:

• Lead with a recommendation and explain why in terms of the user story
• Be honest about trade-offs
• YAGNI applies to building scope, not understanding scope
• Reference codebase patterns when relevant
• Don't just list pros/cons in a vacuum -- tie them back to the problem

Phase 2.5: Architectural Context Mapping

After the approach is chosen, construct a lightweight architectural context map. This is NOT implementation design (no file paths, no class names, no code). This is structural understanding.

What to map:

Output: A concise prose description (5-10 sentences). Think of it as explaining to a new team member where this feature sits and what it touches. Avoid code-level details.

Present to the user for validation. This context map flows into:

• Every execution agent's {{ARCHITECTURAL_CONTEXT}} block in /workflows:work
• The plan's phase decomposition in /workflows:plan
• The review's evaluation frame in /workflows:review

Phase 3: Capture the Design

Summarize everything in a structured brainstorm document.

Document Template:

---
date: YYYY-MM-DD
topic: <kebab-case-topic>
status: complete
handoff:
  problem_narrative: true
  user_story: true
  architectural_context: true
  success_criteria: true
---

# <Topic Title>

## Problem Narrative

[2-4 sentences: who has the problem, what triggers it, what the impact is, why now.]

## User Story

As a [persona],
I need to [action]
so that [outcome],
because currently [pain point]
which causes [impact].

## Success Criteria

- [Measurable outcome tied to the user story]
- [Observable behavior that proves the problem is solved]

## Architectural Context

- **Lives in:** [service/module/layer]
- **Interacts with:** [neighboring systems]
- **User entry point:** [UI/API/CLI/event]
- **Data:** [what data flows, where it lives]
- **Dependencies:** [depends on X; Y may depend on this]

## Chosen Approach

[What we're building and WHY this approach -- tied to the problem narrative]

## Key Decisions

- [Decision 1]: [Rationale tied to problem/user story]
- [Decision 2]: [Rationale tied to problem/user story]

## Approaches Considered

[Alternatives and why they were not chosen, relative to the user story]

## Stakeholder Impact

- **End users:** [experience change]
- **Developers:** [codebase/maintenance impact]
- **Operations:** [deployment/monitoring impact]
- **Business:** [revenue/cost/compliance impact]

## Open Questions

- [Unresolved questions for the planning phase]

## Resolved Questions

- [Questions resolved during brainstorming, with answers]

## Next Steps

-> `/workflows:plan` for implementation details

Output Location: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md

Handoff Contract: The handoff frontmatter fields signal to downstream phases which lynchpin sections are present. All four should be true before handing off to /workflows:plan.

Phase 4: Handoff

Present clear options for what to do next:

1. Proceed to planning -> Run /workflows:plan (will auto-detect and consume this brainstorm's lynchpin artifacts)
2. Refine further -> Continue exploring the design
3. Done for now -> User will return later

YAGNI Principles -- Applied Correctly

During brainstorming, YAGNI applies to building scope, not understanding scope:

• DO explore the full problem space, adjacent problems, and future touchpoints -- this informs architecture
• DO understand broadly, even if you build narrowly
• DON'T commit to building features for hypothetical future requirements
• DO choose the simplest approach that solves the stated problem
• DO prefer boring, proven patterns over clever solutions
• DO ask "Do we really need to BUILD this?" when complexity emerges
• DON'T ask "Do we need to UNDERSTAND this?" -- yes, you always do

Incremental Validation

Keep sections short -- 200-300 words maximum. After each section of output, pause to validate understanding:

• "Does this match what you had in mind?"
• "Any adjustments before we continue?"
• "Is this the direction you want to go?"

This prevents wasted effort on misaligned designs.

Anti-Patterns to Avoid

Integration with Downstream Phases

The brainstorm document is the feature-level spec and handoff contract for downstream work. The project constitution, when present, remains the repo-wide governing artifact:

/workflows:plan consumes:

• Problem narrative and user story -> structures phases around the WHY
• Architectural context -> informs task decomposition, file mapping, dependencies
• Success criteria -> becomes the plan's acceptance criteria foundation
• Key decisions -> preserved and enriched, not re-decided

/deepen-plan consumes:

• Problem narrative -> evaluates whether deepened tasks still serve the original intent
• Success criteria -> grounds best-practice research in actual goals

/workflows:work consumes:

• Architectural context -> populates {{ARCHITECTURAL_CONTEXT}} for every execution agent
• User story -> orchestrator validates each task contributes to the story
• Problem narrative -> included in scoped prompts so agents understand purpose

/workflows:review consumes:

• Problem narrative + user story -> evaluates whether implementation solves the stated problem
• Architectural context -> validates structural decisions match the planned placement
• Success criteria -> confirms the feature delivers measurable outcomes
• Stakeholder impact -> frames review from multiple perspectives (not invented post-hoc)