design

Design Discussion (S Phase)

Plans are 1000+ lines and map roughly 1:1 to code. Reviewing a plan is nearly as much work as reviewing the code. This design discussion surfaces wrong assumptions, bad pattern choices, and misunderstood requirements in a ~200-line document — before the agent writes 2000 lines of code.

If individual file paths were provided, read them all fully.

If no parameters provided, respond with:

"I'll help create a design discussion for your task. Point me to the thoughts folder for your work item (e.g., thoughts/001-auth-endpoint/), or provide your task description and research findings."

Then wait for the user's input.

Then spawn focused research agents to fill gaps:

• Use codebase-pattern-finder to locate the specific patterns referenced in the research. Instruct it to document what exists — not evaluate or recommend.
• Use codebase-analyzer on any component that will be directly modified. Instruct it to explain the implementation — not suggest design choices.

Wait for agents to complete.

If gaps exist, spawn additional research or ask the user before continuing.

Design Discussion: [Feature/Task Name]

Task Summary (5 lines max)

[What we're building and why, from the task definition]

Current State (15 lines max)

[How the relevant parts of the system work today. Be specific — file paths, key functions, data flows. This comes from the research.]

Desired End State (15 lines max)

[What the system should look like after implementation. Be concrete enough that someone could verify it.]

Patterns to Follow

[Existing patterns in the codebase that this work should mirror. Include file:line references.]

• Pattern: [name] — found in path/to/file.ext:L42 [Brief description of the pattern]

Patterns to AVOID

[Bad patterns, deprecated approaches, or legacy code that should NOT be followed.]

• Anti-pattern: [name] — exists in path/to/old_file.ext:L99 [Why this should not be used]

Design Decisions

Resolved by Architecture

[ONLY decisions that are logically forced by the task definition, existing architecture, or codebase constraints. These are not opinions — they are facts.]

1. [Decision]: [Choice] — forced by [architectural constraint or existing pattern]

Open Questions for Human

[Everything else. All trade-offs, preference-based choices, and design directions go here. The human decides.]

1. [Question]: [Context for why this matters]
   • Option A: [description + tradeoff]
   • Option B: [description + tradeoff] Present facts about each option. Do NOT express a preference.

Key Risks & Edge Cases (10 lines max)

[Things that could go wrong or need special attention]

• [Risk]: [mitigation approach]

Out of Scope

[What we're explicitly NOT doing]

</template>

<critical>
The "Resolved by Architecture" section must ONLY contain decisions forced by constraints — not the agent's preferences. If there's any room for choice, it belongs in "Open Questions for Human."