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.
يبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
مستكشف الملفات
3 ملفات
عرض SKILL.md
SKILL.md
تعليمات المصدر · معاينة للقراءة فقط
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).
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
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
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
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
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
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
