design-solution
npx machina-cli add skill kasperjunge/agent-resources/design-solution --openclawDesign 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:design
Pass 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
Source
git clone https://github.com/kasperjunge/agent-resources/blob/main/skills/development/workflow/design-solution/SKILL.mdView on GitHub Overview
Design Solution helps teams pick one recommended approach from multiple options by evaluating trade-offs, constraints, and success criteria. It situates the decision within Step 3 of the development workflow and produces a structured decision artifact before planning and coding.
How This Skill Works
The process restates context, constraints, and success criteria, then evaluates each option for pros, cons, codebase fit, effort, and reversibility. Options are ranked against decision criteria, a recommended option is selected, and open questions are captured to inform the next planning phase.
When to Use It
- You have several credible approaches to a problem and need to pick one
- You must analyze trade-offs between performance, simplicity, and risk before planning
- Constraints and success criteria must be formalized prior to design
- You need to document the rationale for stakeholders or future maintenance
- You want to preserve reversibility and clarity if later changes are needed
Quick Start
- Step 1: Reconfirm context, constraints, and success criteria
- Step 2: Evaluate options with pros, cons, codebase fit, effort, and reversibility
- Step 3: Decide on a recommended option and document open questions in the Solution Decision
Best Practices
- Reconfirm context, constraints, and success criteria before evaluating options
- Evaluate each option with pros, cons, codebase fit, effort, and reversibility
- Rank options against decision criteria and explicitly select a recommended option
- Capture open questions to resolve before planning
- Maintain a consistent Solution Decision output format for handovers
Example Use Cases
- Choosing between caching strategies (LRU vs LFU) for a high-traffic service and selecting a single approach
- Deciding between blue/green and canary deployment strategies after assessing risk and complexity
- Selecting a data model approach (normalized vs denormalized) based on read/write patterns
- Picking between ORM and raw SQL for a new data access layer after evaluating codebase fit
- Resolving UI approach (modal vs inline expansion) under usability and performance constraints
