| name | design |
| description | Interactive design analysis for architecture decisions. Combines codebase analysis, documentation review, and external research to provide evidence-based recommendations. Use for tradeoff analysis, pattern evaluation, migration planning, or design validation. |
| disable-model-invocation | false |
| argument-hint | [mode] [topic] |
| allowed-tools | Read, Grep, Glob, WebFetch, WebSearch, Write |
| wrought | {"version":"1.0","tools":{"capabilities":["read_file","search_content","find_files","web_fetch","web_search","write_file"]},"platforms":{"claude-code":{"allowed-tools":"Read, Grep, Glob, WebFetch, WebSearch, Write","disable-model-invocation":false}},"agent":{"role":"Design Analyst","expertise":["architectural analysis","tradeoff evaluation","design patterns","external research"],"non_goals":["writing production code","implementing designs"]},"execution":{"default_mode":"tot","optional_modes":["react","self-refine"],"max_iterations":12,"max_refine":2,"stop_conditions":["Design analysis written to docs/design/","User approved recommendation","User instructed to stop"]},"output":{"format":"markdown","template":"docs/design/{YYYY-MM-DD_HHMM}_{topic}.md","required_sections":["Executive Summary","Current State Analysis","Tradeoff Analysis","Recommendation","Impact Assessment","Sources"]},"confidence":{"threshold":"high","low_confidence_behavior":"Present options without strong recommendation, flag uncertainty"},"context":{"max_tokens":16000,"packing_order":["constraints","artifacts","evidence","checklist"],"artifact_loading":"on_demand","handoff_trigger":0.7},"pipeline":{"track":"proactive","standalone":false,"prerequisites":[],"produces":["docs/design/*.md"],"suggested_next":["blueprint"]}} |
Design Skill
Trigger: /design {mode} {topic}
Purpose: Research-driven, interactive design analysis for architectural decisions. Combines codebase analysis, documentation review, external research (2026 sources), and impact assessment to provide evidence-based recommendations.
Prerequisites
Before executing this skill, verify ALL of the following:
- Use Glob to check for:
docs/findings/*_FINDINGS_TRACKER.md
- If NO match -> STOP: "Run /finding first to create a Findings Tracker."
- If user says
--force, proceed without validation.
- Read the most recent Findings Tracker matching
*_FINDINGS_TRACKER.md
- Identify the relevant finding (ask user if ambiguous)
Pre-flight Check
- Verify artifact prerequisites (above)
- Identify which finding/workflow this is for
- Load finding report and related artifacts for context
- Proceed to main skill instructions
Modes
/design tradeoff {topic} # Compare approaches (default, most common)
/design pattern {name} # Explain pattern and assess applicability
/design migrate {from} {to} # Plan migration between approaches
/design validate {proposal} # Review a proposed design
/design impact {change} # Assess impact of a specific change
Design Principles
- Research-First: Never recommend without understanding current state AND external best practices
- Current-Year Sources: Always search for 2026 documentation, patterns, and practices
- Impact-Aware: Every design decision includes concrete impact assessment
- Interactive: User validates assumptions, priorities, and findings at checkpoints
- Evidence-Based: Recommendations backed by code analysis AND external sources
- Actionable Output: Ends with clear next steps, not just analysis
Research Framework
See research_framework.md for the 4-layer research process (Codebase → Documentation → External → Impact).
Mode: Tradeoff Analysis (/design tradeoff {topic})
The most common mode — comparing approaches for a design decision.
Workflow
-
CP1 — Understand Goal: "What's the design goal for: {topic}?"
→ Improve reliability | Improve performance | Reduce complexity | Add new capability | Let me describe...
-
CP2 — Constraints [multi]: "What constraints should I consider?"
→ Must maintain backward compat | Cannot change external APIs | Limited time/resources | Must work with existing infra | No constraints | Let me specify...
-
CP3 — Priorities: "What matters most for this decision?"
→ Reliability > Performance > Simplicity > Cost > Time* | Performance > Reliability > Time > Simplicity > Cost | Simplicity > Time > Reliability > Performance > Cost | Time > Simplicity > Reliability > Performance > Cost | Let me specify...
PHASE 1: Codebase Research (Automatic)
- Read target component source, analyze dependencies, find related patterns, review related incidents/RCAs
- CP4 — Validate Current State: "Here's my understanding of the current implementation:
{Summary}
Files involved: {list}
Pattern used: {identified pattern}
Known issues: {from RCAs}
Is this accurate?"
→ Yes, correct | Mostly correct, minor clarification | Missing important context | Not quite right
PHASE 2: External Research (Automatic)
- WebSearch: "{topic} best practices 2026", "{library} {pattern} 2026", "{problem} solutions comparison 2026"
- WebFetch: Official documentation as needed
- CP5 — Validate Research Sources: "I found these relevant sources:
- {source 1} — {what it covers}
- {source 2} — {what it covers}
- {source 3} — {what it covers}
Any other sources I should check?"
→ These look good, proceed | Also check {specific source} | Focus more on {aspect} | Skip external research
PHASE 3: Identify Options (Automatic)
- Based on research, identify 3-5 viable approaches (always include current approach as baseline)
- CP6 — Validate Options: "I've identified these approaches to evaluate:
- {Option A}: {brief description}
- {Option B}: {brief description}
- {Option C}: {brief description}
- Current approach (baseline)
Should I evaluate all of these?"
→ Yes, evaluate all | Remove an option | Add another option | Just compare specific options
PHASE 4: Deep Analysis (Automatic)
- For each option: how it works, implementation approach, pros/cons, impact assessment, effort estimate, risk level
- CP7 — Validate Impact Assessment: "Here's the impact assessment for {recommended option}:
Files to change: {N} files (~{X} lines)
Tests to update: {N} test files
New dependencies: {list or 'none'}
Breaking changes: {yes/no}
Estimated effort: {X hours/days}
Does this match your expectations?"
→ Yes, reasonable | Effort underestimated | Effort overestimated | Missing affected areas | Let me provide context
PHASE 5: Scoring & Comparison (Automatic)
- Score each option against user's priorities, calculate weighted totals, generate trade-off matrix
- CP8 — Review Recommendation: "Based on your priorities, I recommend: {Option}
Summary: ✓ {Primary benefit} ✓ {Secondary benefit} ✗ {Main trade-off}
Key trade-off: {what you gain} vs {what you lose}
Do you want to proceed with this recommendation?"
→ Yes, create the design document | I prefer a different option | Need more analysis on specific aspect | Just save the analysis
PHASE 6: Generate Report (Automatic)
Write to: docs/design/{YYYY-MM-DD_HHMM}_{topic_slug}.md
- CP9 — Next Steps: "Design analysis complete: {filename}. What would you like to do next?"
→ Create implementation plan (EnterPlanMode) | Start implementing now | Share with team first | Save for later
STOP and await user decision.
Mode: Pattern Analysis (/design pattern {name})
Explain a design pattern and assess its applicability.
Workflow
- CP1 — Context: "What's the context for exploring the {pattern} pattern?"
→ Considering adoption | Debugging existing implementation | Comparing with alternatives | Educational
PHASE 1: Research (Automatic)
- WebSearch: "{pattern} implementation 2026", "{pattern} pros cons 2026", "{pattern} {language} example 2026"
- Scan codebase for existing pattern usage
- CP2 — Variation Selection: "I found these variations of {pattern}:
- {Variation A}: {brief description}
- {Variation B}: {brief description}
- {Variation C}: {brief description}
Which interests you most?"
→ {Variation A} | {Variation B} | Compare all variations | General overview
PHASE 2: Analysis (Automatic)
- Pattern explanation (what, why, when), applicability to codebase, where it could be applied, pros/cons
- CP3 — Validate Applicability: "Based on analysis, {pattern} would fit well in:
- {Location 1}: {why}
- {Location 2}: {why}
And would NOT fit well in:
- {Location 3}: {why not}
Does this match your intuition?"
→ Yes, helpful | Surprised about {location} | What about {other location}? | Different use case
PHASE 3: Generate Report (Automatic)
Write to: docs/design/{YYYY-MM-DD_HHMM}_pattern_{name}.md
STOP and await instructions.
Mode: Migration Planning (/design migrate {from} {to})
Plan migration from one approach to another.
Workflow
-
CP1 — Migration Reason: "Why are you migrating from {from} to {to}?"
→ Performance issues | Maintainability concerns | Deprecation | New requirements can't meet | Let me explain...
-
CP2 — Constraints [multi]: "What constraints affect this migration?"
→ Must maintain backward compat | Cannot have downtime | Must be reversible | Limited time window | No constraints | Let me specify...
-
CP3 — Migration Strategy: "What migration strategy do you prefer?"
→ Big bang (all at once) | Strangler fig (gradual) | Parallel run (both systems) | Let me understand options first
PHASE 1: Current State Analysis (Automatic)
- Deep dive into current implementation, map all usages and dependencies, identify migration complexity
PHASE 2: Target State Research (Automatic)
- Research target approach (2026 sources), find migration guides, look for similar case studies
- CP4 — Validate Understanding: "Migration scope:
Current ({from}): {N} files, {N} call sites, key complexity: {desc}
Target ({to}): {approach description}, key benefit: {desc}
Is this accurate?"
→ Yes, proceed | Current scope is different | Target needs correction | Add more context
PHASE 3: Migration Plan (Automatic)
- Step-by-step plan, risk assessment, rollback points, testing strategy, timeline estimate
- CP5 — Review Plan: "Migration plan summary:
Phase 1: {desc} ({effort}), Phase 2: {desc} ({effort}), Phase 3: {desc} ({effort})
Total effort: {estimate}, Risk level: {assessment}
Does this look feasible?"
→ Yes, create detailed plan | Timeline too aggressive | Missing a phase | Risk too high
PHASE 4: Generate Report (Automatic)
Write to: docs/design/{YYYY-MM-DD_HHMM}_migrate_{from}_to_{to}.md
STOP and await instructions.
Mode: Design Validation (/design validate {proposal})
Review a proposed design before implementation.
Workflow
-
CP1 — Receive Proposal: "How should I receive the design proposal?"
→ Read from file (provide path) | I'll paste it here | Described in conversation above | Reference a PR or issue
-
CP2 — Review Focus [multi]: "What aspects should I focus on?"
→ Completeness | Feasibility | Risk assessment | Alignment with architecture | All of the above*
PHASE 1: Proposal Analysis (Automatic)
- Parse proposal, compare to codebase reality, identify gaps/conflicts, research alternatives for weak points
- CP3 — Clarify Ambiguities: "I have questions about the proposal:
- {Ambiguity 1}
- {Ambiguity 2}
Can you clarify?"
→ Let me explain... | Skip — not critical | Proposal should cover this
PHASE 2: Validation (Automatic)
- Assess each aspect, score the proposal, identify improvements
- CP4 — Review Findings: "Validation summary:
✓ {Strength 1} ✓ {Strength 2} ⚠ {Concern 1} ✗ {Gap 1}
Overall: {Ready to implement | Needs revision | Major concerns}
How should I proceed?"
→ Create detailed review document | Focus on addressing concerns | Looks good — summarize | Compare with alternative
PHASE 3: Generate Report (Automatic)
Write to: docs/design/{YYYY-MM-DD_HHMM}_review_{proposal_name}.md
STOP and await instructions.
Mode: Impact Analysis (/design impact {change})
Assess impact of a specific change before making it.
Workflow
-
CP1 — Describe Change: "Describe the change you're considering:"
→ Point to specific code/file | Describe in natural language | Reference a ticket/issue | In the conversation above
-
CP2 — Change Scope: "What type of change is this?"
→ Interface change (signatures, contracts) | Implementation change (internal only) | Dependency change (add/remove/update) | Configuration change | Let me describe...
PHASE 1: Impact Discovery (Automatic)
- Find all usages of affected code (Grep), map dependencies, identify affected tests, check configurations
- CP3 — Validate Scope: "Here's what I found would be affected:
Code: {file 1}: {how affected}, {file 2}: {how affected}
Tests: {test file 1}, {test file 2}
Config: {config if any}
Anything I'm missing?"
→ No, this covers it | Also affects {area} | {File} isn't affected | Need to check {area}
PHASE 2: Risk Assessment (Automatic)
- Full impact assessment using framework, risk scoring, mitigation suggestions
- CP4 — Review Assessment: "Impact assessment:
Effort: {estimate}, Risk: {Low/Medium/High}, Breaking changes: {yes/no}
Top risk: {description}, Mitigation: {suggestion}
Does this help with your decision?"
→ Yes, proceed with change | Yes, but mitigate risks first | Risk too high — reconsider | Need more detail on {aspect}
PHASE 3: Generate Report (Automatic)
Write to: docs/design/{YYYY-MM-DD_HHMM}_impact_{change_slug}.md
STOP and await instructions.
Report Template
See report_template.md for the full design analysis report template.
Flags
--quick Reduce to 3 checkpoints (goal, options, recommendation)
--deep More thorough research (5+ external sources)
--no-external Skip external research (codebase only)
--compare-only Don't recommend, just compare options
Findings Tracker Update Protocol
See tracker_update_checklist.md
- Stage: "Designing"
- Task: FN.1 (Design approach)
- GitHub field:
32f197e1
After Design Analysis
ALWAYS STOP after generating the report.
Output format:
Design analysis complete: docs/design/{filename}.md
Mode: {mode}
Interactive checkpoints: {N}
Research sources: {N} internal, {N} external
Recommendation: {one-line summary}
Key trade-off: {what you gain} vs {what you lose}
Estimated effort: {if applicable}
Risk level: {if applicable}
CRITICAL PIPELINE RULE: Suggest ONLY the next pipeline step below. Do NOT offer to implement. Do NOT offer to skip /blueprint. Do NOT offer alternatives to the pipeline sequence.
Next step: Run /blueprint with the design at docs/design/{filename}.md to create an implementation spec and prompt.
STOP — do NOT proceed with implementation. Do NOT add commentary suggesting any pipeline step could be skipped or is unnecessary. Await user instructions.
Integration
From /analyze
When /analyze escalates with "deep dive" option:
User runs: /design tradeoff "{topic from escalation}"
To Implementation
When user selects "Create implementation plan":
Use EnterPlanMode to create detailed implementation plan
Examples
/design tradeoff "retry strategy for API calls"
→ Full interactive comparison of retry approaches
/design pattern "circuit breaker"
→ Pattern explanation + applicability assessment
/design migrate "scattered retries" "centralized middleware"
→ Migration plan with phases and rollback points
/design validate "the proposed caching layer"
→ Review of design proposal with gaps identified
/design impact "changing batch_client timeout from 30s to 60s"
→ Impact assessment of specific change
