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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
