Deep Design

Deep Design Skill

When to use deep-design vs --spec mode

• deep-design (default): Multi-agent adversarial workflow — stress-tests designs with parallel critics. Use for complex systems. Outputs battle-tested design doc.
• deep-design --spec: Single-session lightweight spec writer. Outputs SDD-compatible spec.md with User Scenarios & Testing (prioritized P1/P2/P3), Functional Requirements (FR-###), Success Criteria (SC-###), Key Entities, Assumptions, and Edge Cases. Creates specs/{NNN-feature}/spec.md and checklists/requirements.md. Ready for deep-plan to consume.

Adversarially stress-test a design. Given a concept, validate input, draft a spec, attack it with parallel critic agents across orthogonal dimensions, fix discovered flaws using independent judge agents, and repeat until coverage is saturated. Output is a battle-tested design document with an honest coverage report.

Execution Model

All operations use Claude Code primitives. The following contracts are non-negotiable:

• All data passed to agents via files, never inline. Spec content, dedup lists, angle definitions, fact sheets — all written to disk before the agent prompt. Inline data is silently truncated.
• State written before agent spawn, not after. spawn_time_iso is written to state.json before the Agent tool call. Spawn failure records spawn_failed status. Resume uses persisted state, never in-memory reconstruction.
• Structured output is the contract; free-text is ignored. Every judge and checker produces machine-parseable structured lines as the final lines of output. Coordinator reads only structured fields. Unparseable output triggers fail-safe classification (critical or conflict). Critic output files MUST contain STRUCTURED_OUTPUT_START/STRUCTURED_OUTPUT_END markers; files without these markers are treated as failed (not partially consumed).
• No coordinator self-review of anything load-bearing. Fact sheets, severity classifications, cross-fix checks, form-switch dedup, section-impact scores — all delegated to independent agents. The coordinator orchestrates; it does not evaluate.
• Termination labels are honest. "Conditions Met" or "Max Rounds Reached" — never "no critical flaws remain." Coverage fraction includes the denominator caveat. Unverified sections are listed explicitly.
• Coverage completeness is a hard invariant — not a judgment call. All 5 required dimension categories (correctness, usabilityux, economicscost, operability, security_trust) MUST have explored_count >= 1 before any run (in-session or sagaflow) can proceed to final synthesis. If a category has zero explored angles, the coordinator MUST spawn critics targeting that category — not skip it, not label it "out of scope," not cite context constraints. "Context is running low" is NOT a valid reason to skip required categories; the coordinator MUST either (a) use sagaflow durable execution to avoid context limits, (b) run coverage extension rounds, or (c) label the run INCOMPLETE — uncovered: {list} and refuse to present it as finished work. A run that declares completion while listing known uncovered categories is a protocol violation, not a judgment call.

Shared contracts: this skill inherits the six execution-model contracts (files-not-inline, state-before-agent-spawn, structured-output, independence-invariant, coverage-completeness, sagaflow-first-routing) from [_shared/execution-model-contracts.md](../_shared/execution-model-contracts.md). The items listed above are the skill-specific elaborations; the shared file is authoritative for the base contracts.

Cross-finding coherence: this skill applies the coherence-integrator pattern from [_shared/cross-finding-coherence.md](../_shared/cross-finding-coherence.md) at Step 5, after all critics complete and BEFORE severity judges are spawned. The integrator reads all deduped critic output files simultaneously and annotates each flaw with cross-finding relationships (contradictions, emergent patterns, coverage gaps). These annotations are included in judge input files so judges see the cross-finding context when classifying severity.

Subagent watchdog: every run_in_background=true spawn (parallel critics, severity judges, rebuttal agents) MUST be armed with a staleness monitor per [_shared/subagent-watchdog.md](../_shared/subagent-watchdog.md). Use Flavor A with thresholds STALE=5 min, HUNG=20 min for Sonnet critics; STALE=3 min, HUNG=10 min for Haiku judges. TaskOutput status is not evidence of progress — output-file mtime is. Contract inheritance: timed_out_heartbeat joins this skill's per-angle termination vocabulary; stalled_watchdog / hung_killed join angles.{id}.status. A watchdog-killed critique angle is reported as coverage-lost in the final coverage fraction — never silently dropped.

Philosophy

Good design survives adversarial scrutiny. This skill treats design as a generate-then-break loop: draft a design, attack it from every angle, fix the flaws, then attack again. Each critic agent is an expert in one dimension (balance, UX, edge cases, narrative, technical feasibility, etc.) trying to find holes. Flaws discovered in one round feed redesign in the next.

Workflow

Step 0: Input Validation Gate

Before any work begins, validate the concept. Batch any clarifying questions — if multiple questions surface in this step (concept rubric ambiguity, core-claim confirmation, alternatives selection), present ALL of them as a single numbered batch in one message. Never serially. The user answers once, then Step 1 begins.

Concept rubric — reject if any of these apply:

• Too vague to critique ("make a good app") — request specificity
• Already fully specified (more of an implementation request than a design) — offer to run critique-only mode
• Requests harmful design (weapon, exploit, manipulation system) — decline

Core claim extraction:

1. Read the concept and extract a 1-2 sentence core claim: the specific thing this design does that similar designs do not
2. Run the specificity test: "Would this claim be true of a system that does [X] instead of [Y]?"

• Select 2 domain-adjacent alternatives in the same problem class as the concept but with different primary mechanisms
• For deep-design, valid alternatives: collaborative (not adversarial) review, single-pass critique, sequential-agent critique
• The claim must fail to apply to both alternatives before passing the specificity test
• If interactive mode: show user the claim + 2 alternatives, ask for confirmation
• If claim passes: set core_claim_calibrated: true, store core_claim and core_claim_sha256 in state.json
• If claim fails after 2 attempts: set core_claim_calibrated: false; Layer 2 drift checks run in degraded mode (tighter threshold + DRIFTCHECKDEGRADED tag) — do NOT skip them

Concept summary field: The concept summary sent to all critics is the core claim text verbatim as extracted and locked at this step. The coordinator may append context but cannot replace or paraphrase the locked text.

Print: Starting deep design on: {concept} [run: {run_id}]

Step 1: Initialize

• Generate run ID: $(date +%Y%m%d-%H%M%S) — e.g., 20260314-153022
• Create directory structure:
• deep-design-{run_id}/state.json — run state (see STATE.md for schema)
• deep-design-{run_id}/critiques/ — one file per critique angle
• deep-design-{run_id}/specs/ — versioned spec files
• deep-design-{run_id}/logs/ — frontier_pop_log.jsonl and coverage_gaps.jsonl
• deep-design-{run_id}/spec.md — final output (written at Step 8)
• Write initial state.json with core_claim, core_claim_sha256, core_claim_calibrated from Step 0
• The spec template must include CORE_MECHANISM_START / CORE_MECHANISM_END delimiters enclosing the section describing the core mechanism. These delimiters are the reference boundary for Layer 1 drift comparison and must not be removed or moved by any agent.

Step 2: Initial Design Draft

• Analyze the concept to understand core intent, target audience, and constraints
• Write deep-design-{run_id}/specs/v0-initial.md — a structured first-pass design covering:
• Core concept & elevator pitch
• Key mechanics/features
• User/player flow
• High-level technical approach
• Known open questions
• This is deliberately a FAST draft — good enough to critique, not polished

Step 3: Dimension Discovery (see DFS.md Phase 3a-3c)

• Enumerate CRITIQUE DIMENSIONS using the design-specific framework
• Required dimension categories (at least one angle per category must be explored):
• correctness — does the design work as claimed?
• usability/UX — can users actually use it?
• economics/cost — is it affordable/sustainable?
• operability — can it be operated/maintained?
• security/trust — can it be abused or corrupted?
• Generate 2-4 critique angles per dimension; cap frontier at 40 angles total
• Depth-diversity rule: when displacing to stay under cap, cannot displace a dimension's only remaining depth-0 OR depth-1 angle
• Each angle definition written to state.json at discovery time with: {angle_id, dimension, question, discovery_source: "coordinator_initial|critic_suggested", discovery_round, rationale}. Angle definitions are immutable once written.
• Frontier pop decisions logged in deep-design-{run_id}/logs/frontier_pop_log.jsonl: {angle_id, round, timestamp, score, reason}
• Stability trigger: "no new DIMENSION CATEGORIES for 2 consecutive rounds" (not merely "no new angles")
• Build exhaustion map; populate frontier with all critique angles, priority-ordered
• Write state file

Step 4: Critique Round

Prospective gate (fires BEFORE spawning critics):

The coordinator outputs a gate summary and STOPS. The user continues the conversation to proceed. This is the standard Claude Code turn-boundary interaction model — there is no blocking [y/N] prompt.

Gate content: > Round {N+1}: up to {agents} agent calls × ~{tokenestimate}k tokens/agent = structural bound ~${bound}. Spent so far: ~${cumulative}. Projected total to maxrounds: ~${projection}.

Projection includes: 6 spec-derived critics + 1 outside-frame critic + (estimated flaws × 2 judge calls) + 1 redesign agent (estimated at 3× critic cost) + 1 invariant-validation agent, with spec growth factor.

If any flaw is in pending_user_acknowledgment state, the gate prominently displays the proposed tension and requests explicit acknowledgment before proceeding.

User options at gate: continue the conversation (proceed), stop (triggers final synthesis), or redirect focus via message.

Stall handling: if no user response at a gate for 2 or more consecutive turns, the run auto-proceeds to final synthesis (not continuation).

Autonomous mode: Gate is skipped. max_rounds defaults to 3. Hard budget cap = $10 total. If budget is exceeded mid-round, that round completes, then the run terminates. CORE_TENSION flaws remain in pending_user_acknowledgment state in the final spec and cannot be silently reclassified.

Spawn critics:

• Pop up to 6 (max_agents_per_round) highest-priority critique angles from frontier using the declared scoring function. Selection policy is explicit and auditable via logs/frontier_pop_log.jsonl.
• Also spawn 1 outside-frame critic (slot #7) seeded from the original concept description ONLY (not the current spec). See "Outside-Frame Critic Prompt Template" section below.
• Concept summary field sent to all critics = core claim text verbatim (locked, not paraphrased). Coordinator may append context but cannot replace or paraphrase the locked text.
• Write all required data to files before spawning: latest spec, known-flaw-titles file (with flaw IDs), angle definitions
• For each angle, write angle to state.json with spawn_time_iso set before calling Agent tool
• Spawn background Agent (subagent_type: general-purpose) with file paths — not inline content
• Critic output files are content-addressed at critiques/{angle_id}-{critic_agent_id}.md — coordinator CANNOT overwrite these files
• If Agent tool returns an error (tool limit, spawn refused): record status: "spawn_failed", spawn_time_iso: null in state.json; do NOT record as "spawned"; resume retries spawn

Quorum: Round complete if ≥ 4 of 6 spec-derived critics return parseable output within timeout. Outside-frame critic is tracked separately and does not affect quorum denominator.

Timeout scaling: 120s base; 180s for rounds 3+; ×1.5 for specs exceeding 3,000 words.

Output integrity: Critic output files MUST contain STRUCTURED_OUTPUT_START/STRUCTURED_OUTPUT_END markers. Files without these markers are treated as failed (not partially consumed).

Circuit breaker: If ≥ 3 consecutive rounds have any critic failures, halt immediately, log SYSTEM_FAILURE_ROUND, notify user at turn boundary, allow retry or abort.

After completion:

• For each completed agent: read critique file, extract flaws, new angles, dedup, update state
• Spec-derived critics may suggest at most 1 new angle per round (not 1-3). New angles are logged with discovery_source: "critic_suggested" and are immutable once written.
• Severity classification delegated to independent judge agent — coordinator does not classify; unparseable judge output → fail-safe critical
• Section-impact scores assigned by independent agent — not coordinator; prevents self-serving deflation of foundational section scores
• Form-switch dedup check performed by consistency checker — not coordinator
• Run coverage evaluation: identify uncritiqued dimensions, generate new angles if needed
• Update running synthesis
• Increment round

Step 5: Synthesis with Independent Judges

For each round's flaws before redesign:

Fact sheet agent (independent):

• Spawn a fact-sheet agent that reads the current spec and produces structured output:

`` RECOVERY_BEHAVIORS: [{"component": "", "behavior": ""}, ...] `` This must be the final structured line of the agent's output. Coordinator reads ONLY this line; unparseable = empty list (not coordinator fallback text).

• When evaluating RECOVERY_MECHANISM_CITED in judge output: the component field must appear in the RECOVERY_BEHAVIORS list. Names not in the list are treated as hallucinated → mechanism_applies: false.

Cross-finding coherence integrator (fires after critics complete, before severity judges):

Per [_shared/cross-finding-coherence.md](../_shared/cross-finding-coherence.md):

1. Collect all parseable critic output files from this round (post-dedup).
2. Write integrator input manifest to deep-design-{run_id}/coherence/round-{N}-input.md.
3. Spawn Sonnet coherence-integrator agent. Output: deep-design-{run_id}/coherence/round-{N}-coherence.md. Timeout: 120s.
4. Parse structured annotations. Attach FINDING|{id}|{annotation} to each flaw in state.json as flaws.{id}.coherence_annotation.
5. Feed GAP lines into frontier as CRITICAL-priority angles for the next round.
6. Store PATTERN lines in state.json.emergent_patterns[] for Step 8 final spec.
7. If unparseable/timed out: proceed in degraded mode (judges run without annotations). Log COHERENCE_DEGRADED.

Severity judge (independent) — two-pass blind severity protocol:

1. The coordinator strips the SEVERITY_CLAIM block from the raw critic file to produce judge_input/{flaw_id}.md. The original critic file remains immutable. The stripping is recorded in state.json as judge_input_stripped: true.
2. A judge agent receives: {flaw_id, judge_input_file_path, fact_sheet_path, coherence_annotation} — a strict schema enforced by a validator before spawn. The coherenceannotation (from the integrator) gives the judge cross-finding context: PATTERNMEMBER suggests aggregate severity consideration; CONTRA

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: npow
• Source: npow/claude-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.