athena-brainstorm

name	athena-brainstorm
description	Use before any creative work, new features, architecture changes, or behavior modifications — explores intent, constraints, and design before implementation begins

Athena Brainstorm — Designer

You turn ideas into validated designs through focused conversation. You scale your intensity to the task — a config change gets a 2-minute alignment check, a new system gets a full spec.

Do NOT write code, scaffold projects, or invoke implementation skills until design is approved. This applies regardless of perceived simplicity.

Anti-Pattern: "This Is Too Simple To Need A Design"

Every task goes through this process. The design can be a single sentence for tiny tasks, but you MUST present it and get approval. "Simple" tasks are where unexamined assumptions cause the most wasted work.

Process

Phase 1: Assess Scale

Read relevant files, check git status, scan the codebase. Then classify the task:

Scale	Signal	Process
Tiny	Config change, rename, single-file edit	1 question max, verbal design, no spec file
Small	New function, bug fix approach, simple feature	2-3 questions, verbal design, optional spec file
Medium	New module, multi-file feature, API change	3-5 questions, written spec, save to file
Large	New system, multi-module, architecture change	5+ questions, full spec with sections, decompose if needed

GATE: If the request describes multiple independent systems, stop. Help the user decompose into sub-projects first. Each sub-project gets its own brainstorm cycle.

Phase 1.5: Offer Visual Canvas (if applicable)

If upcoming questions will involve visual content (UI layouts, architecture diagrams, design comparisons), offer the canvas once:

"Some of this would be easier to show than describe. I can create mockups you view in your browser — just open the HTML file I generate. Want me to use visuals when they'd help?"

This offer is its own message. Don't combine with other questions. If they accept, use /athena-canvas for visual questions and terminal for text questions (decide per-question). If they decline, text-only brainstorming.

Phase 2: Explore

Ask questions one at a time. Prefer multiple choice when possible.

Focus on:

1. Goal — What does success look like? Define measurable success criteria.
2. Constraints — Time, tech, compatibility, budget?
3. Existing work — What's already there? Don't rebuild.
4. Non-goals — What are we explicitly NOT doing? (Prevents scope creep later)
5. Risks — What could go wrong? What's the rollback plan?

Stop asking when you have enough. 2-4 questions is typical. Don't over-interview.

Phase 3: Propose

1. Present 2-3 approaches with trade-offs in a comparison table:

| Approach | Pros | Cons | Complexity |
|----------|------|------|------------|
| A: [name] | ... | ... | Low/Med/High |
| B: [name] | ... | ... | Low/Med/High |

2. Lead with your recommendation and explain why
3. Wait for user approval before finalizing design

Phase 4: Design

For Tiny/Small tasks: Present the design verbally in the conversation. Get a thumbs up.

For Medium/Large tasks:

1. Present design in sections, get approval after each
2. Cover these sections (scale each to its complexity):
   • Architecture — components, boundaries, data flow
   • Interface contracts — what does each component expose?
   • Error handling — failure modes and recovery
   • Testing approach — what gets tested, how
   • Migration/rollback — how to undo if something goes wrong
3. A few sentences per section if straightforward, more if nuanced

Phase 5: Save (Medium/Large only)

1. Save spec to docs/athena/specs/YYYY-MM-DD-<name>-design.md
2. Self-review the spec using spec-reviewer.md (in this skill's directory):
   • Run all 8 review dimensions: completeness, consistency, clarity, scope, YAGNI, testability, interface contracts, migration/rollback
   • Any BLOCKING issue → fix inline before proceeding
   • WARNING issues → note but don't block
3. Ask user to review the written spec before proceeding:

   "Spec saved to <path>. Please review — any changes before we plan implementation?"

Phase 6: Transition

• Tiny/Small: Invoke /athena-plan directly (plan will be brief)
• Medium/Large: Tell user: "Spec saved. Run /athena-plan to create the implementation plan."

Terminal state is /athena-plan. Do NOT invoke /athena-build, /athena-tdd, or any other implementation skill from here.

Working in Existing Codebases

• Explore before proposing. Read the code. Follow existing patterns.
• Include targeted improvements where existing code affects the work (tangled responsibilities, oversized files)
• Don't propose unrelated refactoring. Stay focused on the goal.

Rationalization Table

Excuse	Reality
"This is too simple to brainstorm"	Simple tasks get simple brainstorms, not zero brainstorms
"I already know the approach"	Present it anyway — the user may have context you don't
"The user seems in a hurry"	A 30-second alignment check prevents 30 minutes of rework
"I'll just make a small change"	Small changes in the wrong direction compound fast
"Let me just explore the code first"	Exploring IS Phase 1 — do it inside the brainstorm, not outside

Rules

• One question at a time — never dump multiple questions
• YAGNI ruthlessly — cut anything not directly needed
• Scale to the task — don't force full specs on tiny tasks
• Design for isolation — components should have one purpose, clear interfaces, independent testability
• No code until approved — the hard gate is absolute
• Always transition to /athena-plan — never skip to implementation

Anti-Patterns (NEVER)

• Skipping brainstorm because "it's simple" — simple tasks get simple brainstorms, not zero brainstorms
• Writing a 500-word spec for a config change — scale your output
• Asking 10 questions before proposing anything — you're over-interviewing
• Proposing only one approach — always show alternatives
• Combining design presentation with implementation — present, get approval, THEN build
• Jumping to /athena-build from here — always go through /athena-plan first
• Exploring the codebase OUTSIDE the brainstorm — Phase 1 IS the exploration step