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.
Instrucciones de origen · Vista previa de solo lectura
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.
{"version":"1.0","tools":{"capabilities":["read_file","search_content","find_files","web_fetch","web_search","write_file","delegate","run_command"]},"platforms":{"claude-code":{"allowed-tools":"Read, Grep, Glob, WebFetch, WebSearch, Write, Agent, Bash","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...
Irreversibility gate (human-confirmed): "Is this decision irreversible AND public?" (SemVer-permanent surface / relicensing / trademark class / public launch copy) — default yes when unsure. If yes, set the irreversible+public tag: PHASE 5.5 (Adversarial Omission Sweep) fires, and the Layer-0 human spine (CST-005) + the Layer-3 cross-lab hedge at CP8 become mandatory-on-fire. The human owns this call — a model self-assessing the trigger shares the blind spot it hedges.
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
PHASE 5.5: Adversarial Omission Sweep (fires only on the CP1 irreversible+public tag; silent-skip otherwise)
Only when CP1's irreversibility gate is yes. On the ~99% of reversible designs this silently skips — no spawn, no output, no report section.
Spawn the decorrelation-critic agent (model: opus) once per lens — missing-option, strongest-counter-case, irreversibility-stress, completeness — in a single message (mirror the forge-review parallel-spawn pattern), each reading .claude/agents/decorrelation-critic.md with the option matrix + the draft CP8 recommendation and its one assigned lens.
Collect the critics' independent tiered objections (MUST-ADDRESS / SHOULD-CONSIDER / NOTE) and surface them into CP8 as objections to confront — never a consensus vote, never approve/reject, never a score.
Honest caveat (state in-line): this catches skipped omissions only; a same-lab Opus panel does NOT decorrelate shared blind spots — that residual is owned by the Layer-0 human spine (CST-005) and the Layer-3 cross-lab hedge (below).
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
On the irreversible+public tag, CP8 also runs the decorrelation ladder's outer layers:
Layer 2 (optional, owner/ZDR-free only): one supervised main-loop /model fable pass over the option matrix — generate-only, never a grader (see CST-004); return with /model opus. Honest caveat: it narrows but does not close the gap to Layer 3 (still same-lab-adjacent, not cross-lab). Skip under ZDR and for any non-owner run.
Layer 3 (cross-lab hedge — MANDATORY-on-fire for relicensing / trademark / SemVer-permanent triggers): run the recorded blind-second-opinion ladder over {the full option matrix — WITHOUT the CP8 draft recommendation} (blind mode: the overseer must not anchor on the presented answer), asking only: "what consideration category did we miss?" — an omission-hunt, not a re-score or a vote. This is the only rung class that decorrelates shared blind spots. Rung 1 — via Bash, feed the bundle to codex exec - over stdin (single-shot, -s read-only --ephemeral --ignore-user-config --ignore-rules, -c model_reasoning_effort="high"); the un-allowlisted permission prompt IS the rule-10 human pre-send gate — never allowlist it. Rung 2 — manually paste the same bundle into a different lab's current frontier model (e.g. gpt-5.6-sol as of 2026-08 — the identity is data, record what you used verbatim). Rung 3 — waived, with the reason recorded.
CP8 records ran-or-waived — and the full status: emit wrought route design --overseer-row --overseer-model {openai|manual}/{model-id} --mode blind --status {ran|waived|absent|failed} --artifact-ref sha256:{bundle hash} --session {N} (hash via shasum -a 256 over the bundle) and paste the row into the design doc + the tracker's ### Routing Ledger. The human owner (Layer 0 / CST-005) — not any LLM layer — makes the go/no-go call.
PHASE 6: Generate Report (Automatic)
Write to: docs/design/{YYYY-MM-DD_HHMM}_{topic_slug}.md
PHASE 6.5: Promote durable constraints (Automatic)
If the design rejected an approach for a durable reason ("don't re-propose X because Y"), promote it to the ## Active Constraints (in force) section in CLAUDE.md so a future session does not re-litigate it. Create the section if absent (a wrought init/upgrade project already has it); append under ### Durable invariants:
This is text-persistence, not compliance (see CONVENTIONS.md). Skip if the design surfaced no durable negative constraint.
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: If this project has frontend files (check Glob for package.json, *.tsx, *.vue, *.svelte), recommend running /ux-design first to generate a Design Brief that will inform the blueprint. Otherwise, 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
