Design Solution
Converge from multiple options to a single recommended approach.
Position in Workflow
Step 3 of development workflow:
/research- Understand problem and constraints/brainstorm-solutions- Explore solution space/design-solution- Converge on a single solution (THIS)- Plan, code, review, ship
Core Principle
Decide deliberately. Evaluate trade-offs, align to constraints, and pick the best fit.
Input
Default: Use the options from the current conversation.
If argument provided:
- File path: Read the file for brainstorming output
- GitHub issue number/URL: Fetch with
scripts/gh_issue_phase.sh get-issue $ARG
Workflow
1. Reconfirm Context
- Restate the problem, constraints, and success criteria.
- Identify any missing information that blocks a decision.
2. Evaluate Options
For each option, assess:
- Pros: Benefits and what it enables
- Cons: Risks and complexity
- Codebase fit: Alignment with existing patterns
- Effort: Low/Medium/High
- Reversibility: Easy/Moderate/Hard to change later
3. Decide
- Rank options against success criteria.
- Select a recommended option.
- State conditions that would change the decision.
4. Capture Open Questions
List unknowns that must be resolved before planning.
Output Format
## Solution Decision
### Context Summary
[Brief restatement of problem and key constraints]
### Decision Criteria
[What matters most: performance, time, simplicity, extensibility, etc.]
---
### Option Evaluation
#### Option 1: [Name] - Recommended
[Description]
**Pros:**
- ...
**Cons:**
- ...
**Codebase fit:** [How it aligns with existing patterns]
**Effort:** [Low/Medium/High]
**Reversibility:** [Easy/Moderate/Hard]
#### Option 2: [Name]
[Same structure]
#### Option 3: [Name]
[Same structure]
---
### Recommendation
[Why the recommended option wins, and when you would choose differently]
### Open Questions
[Anything that could change the recommendation]
### Next Step
Ready to plan implementation. Enter Plan Mode or run `/plan`.GitHub Issue Tracking
If a GitHub issue was provided or is available from prior phases:
Post design decision as a phase comment and set the label:
echo "$DESIGN_SUMMARY" | scripts/gh_issue_phase.sh post-phase $ISSUE design
scripts/gh_issue_phase.sh set-label $ISSUE phase:designPass the issue number to the next skill (e.g., /make-plan #42).
Common Mistakes
| Mistake | Fix |
|---|---|
| Skipping decision criteria | State criteria before evaluating |
| Over-weighting novelty | Prefer codebase fit and simplicity |
| Ignoring reversibility | Consider how hard it is to change later |
| Decision without evidence | Call out unknowns explicitly |
What NOT to Do
- Do NOT re-brainstorm options
- Do NOT proceed to planning without a chosen option
- Do NOT hide assumptions or uncertainties
- Do NOT ignore codebase constraints