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, usability_ux, economics_cost, 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. 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 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. 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 + DRIFT_CHECK_DEGRADED 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 × ~{token_estimate}k tokens/agent = structural bound ~${bound}. Spent so far: ~${cumulative}. Projected total to max_rounds: ~${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": "<name>", "behavior": "<description>"}, ...]
  

  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:

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 coherence_annotation (from the integrator) gives the judge cross-finding context: PATTERN_MEMBER suggests aggregate severity consideration; CONTRADICTS suggests evidence scrutiny. If coherence ran in degraded mode, this field is STANDALONE for all flaws. If validator fails: conservative enforcement (reject unknown fields, continue).
3. The judge first classifies severity without knowing the critic's severity claim (pass 1), writes an independent verdict to judge_verdicts/{flaw_id}.md.
4. The coordinator then provides the critic's severity claim (from severity_claims/{flaw_id}.txt) as a second-pass prompt. The judge confirms, upgrades, or downgrades with rationale in a second-pass addendum.
5. See "Judge Prompt Template" section below for required adversarial mandate.

Challenge token:

• Challenge execution is delegated to an independent challenger agent — the coordinator can request but cannot execute challenges.
• Each flaw gets one challenge token if the coordinator disputes severity.
• The challenger reads the original critic file + judge verdict + current spec and renders an independent decision.
• Challenge timing: challenges against flaws classified in rounds N-2 or earlier are rejected as untimely.

GAP_REPORT mechanism:

• Critics may file GAP_REPORT: {"references_flaw_id": "<flaw_id>", "gap_description": "<what the fix missed>"} to re-open a closed flaw whose fix was insufficient.
• GAP_REPORT bypasses dedup, does NOT consume challenge token, re-opens flaw for re-fix.
• GAP_REPORT cap: max 2 GAP_REPORTs per flaw per run (globally, not per-critic). Tracked in flaws[id].gap_report_count in state.json (persisted). A third GAP_REPORT for the same flaw causes the coordinator to file a PERSISTENT_TENSION note instead of re-opening.

Final-round pending judge sequencing:

• At Step 5, check: is current_round == max_rounds?
• If yes (final round): any pending judge run MUST complete before Step 5 finalizes
• Timeout in final round: retain ORIGINAL severity (not fail-safe critical); log CHALLENGE_TIMEOUT_FINAL_ROUND: {flaw_id}
• Timeout in non-final round: fail-safe critical escalation applies

Flaw validation (coordinator reads structured outputs, applies these checks):

1. Contradiction check: Does this flaw contradict another flaw? Contradictory flaws indicate at least one is misdiagnosed.
2. Premise check: Would this flaw manifest in practice, or does the design's existing strengths already handle it?
3. Existence check: Would cutting the flawed feature produce a better design than patching it?
4. Nerf check: Does the proposed fix weaken a core strength? If so, look for a format-level redesign instead.
5. Falsifiability check: Is this flaw verifiable/falsifiable? Reject unfalsifiable claims (e.g., "this might be slow" with no scenario, "users might not like this").

Flaws that fail validation are downgraded to "disputed" with a rationale. Disputed flaws are not redesigned but are noted explicitly.

Step 6: Redesign Phase

After flaw validation, if accepted critical or major flaws exist:

Independent redesign agent (coordinator does NOT write the updated spec):

1. Coordinator writes ungrouped flaw ID list + raw critic file paths to a hand-off file (no coordinator theme labels, groupings, or summaries).
2. Coordinator spawns an independent redesign agent that reads raw critic files directly.
3. Redesign agent receives:
   • Accepted flaw list: IDs + paths to raw critic files
   • Current spec path
   • Do-not-weaken list: mechanical projection of the full component_invariants array from state.json, verbatim, in written order — no coordinator selection or omission
4. The redesign agent performs its own internal grouping. It is the sole authoring agent for spec changes.
5. Redesign agent marks each change with <!-- Fixed: <description> -->.
6. Redesign agent prompt includes: "You MUST NOT weaken any invariant on the do-not-weaken list. If a fix requires weakening one, file a DESIGN_TENSION instead. You MUST NOT remove or move CORE_MECHANISM_START/END delimiters."
7. See "Redesign Agent" section below.

Complexity budget per round:

• Rounds 1–2: ≤ 2 new components or state fields per redesign
• Rounds 3+: ≤ 1 new component or state field per redesign
• Budget overflows → redesign agent files DESIGN_TENSION (appears in open issues)
• Complexity delta tracked in state.json.

CORE_TENSION path:

• Before filing a CORE_TENSION, the challenger agent must confirm it's a genuine irresolvable tension (not just a difficult fix).
• Final-round CORE_TENSION → UNACKNOWLEDGED_TENSION in final spec (not silent reclassification).

N-way co-round consistency check (independent agent):

• Write ALL proposed fixes for this round to a single file
• Spawn cross-fix checker with all fixes in one call; it checks fixes against each other AND against component_invariants
• Coordinator does NOT perform this check
• Structured output: CONFLICT: {fix_a, fix_b, description} or OK; ORDERING_EDGE: {from, to, basis} for new dependencies
• Unparseable → CONFLICT: assumed

Component invariant store (state.json):

• component_invariants[key] stores: {invariant, constraint_direction: "tightened"|"relaxed"|"neutral", tightened_rounds: [N, ...]}
• component_invariants is append-only; coordinator-write-prohibited. Only the invariant-validation agent and redesign agent may write entries.
• DIRECTION_REVERSAL warning when constraint_direction = "relaxed" and tightened_rounds is non-empty
• Per-component invariants cannot store cross-component ordering constraints; those go in ordering_graph

Ordering graph:

• ordering_graph: {edges: [{from, to, established_round, basis}]} stored in state.json
• Start empty (edges: []); add edges ONLY from cross-fix checker's structured ORDERING_EDGE output
• Cross-fix checker detects cycles when new edges are added
• Do NOT infer ordering edges from prose

Component invariant key migration (at inventory-rebuild time):

• When rebuilding the canonical component inventory from the new spec, detect renames via semantic equivalence
• If a component's canonical name changed: atomically rename the corresponding component_invariants key to the new canonical name in the same state write
• Log old→new in component_name_history
• Semantic normalization (at check time) handles new-fix aliases → canonical; key migration handles canonical → new-canonical on rename. These are distinct operations; neither substitutes for the other.

Concept drift check:

• SHA256 role — anti-tampering ONLY: Verify core_claim_sha256 matches SHA256 of stored core_claim text before using it as drift reference. Mismatch triggers CORE_CLAIM_TAMPERED and halts the run. SHA256 detects bit-level modification of the stored string. It does NOT detect semantic drift.
• Layer 1 — semantic comparison: Compare text within CORE_MECHANISM_START/CORE_MECHANISM_END delimiters against stored core_claim embedding. Base threshold: 0.80 — below this, DRIFT_WARNING is issued. Critical threshold: 0.65 — below this, DRIFT_CRITICAL triggers, halting redesign and routing affected flaws to PERSISTENT_TENSION.
• Layer 2 — discriminating test: Compare current spec to core claim using 2 domain-adjacent alternatives. Alternatives are refreshed every 2 rounds of major redesign but only against the original concept (not the current spec). Original alternatives are retained permanently as baseline.
  • If core_claim_calibrated: false: run with 50% tighter threshold (effective threshold 0.95) + tag as DRIFT_CHECK_DEGRADED. Do NOT skip.
  • If core_claim_calibrated: true: run normally (base threshold 0.80).

After redesign — Invariant-Validation Agent (NEW, runs before next round): See "Invariant-Validation Agent" section below. Violations block round advancement (treated as critical flaws).

Write updated spec:

• deep-design-{run_id}/specs/v{N}-post-round-{round}.md
• Written by the redesign agent, not the coordinator
• The next critique round uses this updated spec

Print summary: {N} flaws found, {M} validated, {K} disputed, {J} fixed in redesign

Step 7: Termination Check (see DFS.md Step 6)

Primary termination mechanism: max_rounds (default 5). All runs are expected to complete at max_rounds unless early exit fires first. "Conditions Met" is early exit — achievable but not the expected path.

Early exit (all conditions must be true — this is a quality signal, not the expected path):

1. All 5 required dimension categories have ≥ 1 angle that reached "explored" status (quorum_met: true)
2. No new DIMENSION CATEGORIES discovered by spec-derived critics for 2 consecutive rounds (outside-frame critic new-category discoveries do not reset this clock)
3. No open critical flaws (excluding those tagged accepted_with_tension or in pending_user_acknowledgment state)

Hard stop: max_rounds (default 5) → triggers coverage extension before labeling.

Coverage extension (mandatory at max_rounds): If any of the 5 required dimension categories have zero explored angles at max_rounds:

1. Force up to 2 additional extension rounds, targeting ONLY uncovered required categories
2. Each extension round spawns 1 critic per uncovered category (not the full frontier)
3. Extension critics follow the same quorum, judge, and redesign pipeline as regular critics
4. Mark category as covered on parseable critic output (regardless of flaw count — a critic that runs and finds nothing still explored the dimension)
5. After extension rounds complete: if all required categories now have ≥ 1 explored angle → label "Max Rounds Reached"; if gaps remain → label "INCOMPLETE — uncovered: {list}"
6. Extension rounds are NOT optional — they fire automatically when coverage is incomplete

The "INCOMPLETE" label is a hard signal that the output has known gaps. It appears in the coverage report and final spec header. Runs labeled "INCOMPLETE" must NOT be presented as finished work.

Note: "no major flaws unfixed" is tracked as a quality metric but is NOT a hard termination gate — major flaws may be accepted with rationale.

Note: "frontier empty" is NOT a termination condition. The frontier fill rate (up to +8 angles/round with outside-frame critic) exceeds drain rate (6/round) in most domains, making an empty frontier structurally unreachable under normal operation.

Step 7b: Pre-Synthesis Verification Gate (mandatory)

Before proceeding to final synthesis, the coordinator MUST programmatically verify coverage completeness. This is not optional — it fires on every run, in-session and sagaflow alike.

Verification checks (all must pass):

1. For each of the 5 required categories: explored_count >= 1 in the exhaustion map
2. No critical flaws with status open (flaws in persistent_tension or pending_user_acknowledgment are excluded)
3. State file exists and is parseable

If any check fails:

• Categories with explored_count == 0 → run coverage extension (up to 2 rounds, 1 critic per uncovered category)
• After extension: re-check. If gaps remain → label INCOMPLETE — uncovered: {list} and include the label prominently in the final spec header
• The coordinator MUST NOT proceed to Step 8 with a "Conditions Met" or "Max Rounds Reached" label while required categories are uncovered. The only valid labels for incomplete runs are INCOMPLETE — uncovered: {list}

What is NOT a valid reason to skip this gate:

• "Context window is running low" → use sagaflow durable execution or label INCOMPLETE
• "The spec is already good enough" → coverage completeness is structural, not qualitative
• "The uncovered categories aren't relevant to this concept" → the categories are required by the protocol, not by the coordinator's judgment of relevance
• "I'll note the gaps in the coverage report" → noting gaps while declaring completion IS the bug this gate prevents

Step 8: Final Spec

• Do NOT read all raw critique files — use the coordinator summary + per-critique mini-syntheses + latest spec + state file
• Spawn a Sonnet subagent to write deep-design-{run_id}/spec.md
• If --sdd-dir was provided (or auto-created): ALSO write an SDD-compatible copy to {SDD_DIR}/spec.md with the required SDD sections:
  • User Scenarios & Testing — prioritized user stories (P1, P2, P3) with Given/When/Then acceptance scenarios
  • Functional Requirements — FR-001, FR-002, etc.
  • Success Criteria — SC-001, SC-002, etc. (technology-agnostic, measurable)
  • Key Entities — if data is involved
  • Assumptions and Edge Cases
  • Design Decisions — traceable to the adversarial critique process (resolved flaws, accepted tradeoffs)
• Generate {SDD_DIR}/checklists/requirements.md for spec quality validation
• Termination label: "Conditions Met" or "Max Rounds Reached" — never "no critical flaws remain"
• Coverage report must include: dimensions covered, required categories covered, honest coverage caveats section, list of unverified sections, list of open issues at termination
• Includes: resolved flaws, disputed flaws, accepted tradeoffs, open questions, implementation notes
• If coherence integrator ran: include a 'Cross-Dimensional Patterns' section listing emergent patterns with member flaws, shared root causes, and aggregate implications

Step 9: QA Pass (automatic offer)

After writing deep-design-{run_id}/spec.md, offer a QA pass:

QA pass available. Run deep-qa on this spec? [y/N]
(Recommended: catches specification gaps, underspecified components, and implementation
inconsistencies that design critics — focused on the design process — may have missed.)

• If y: invoke deep-qa with --type doc on deep-design-{run_id}/spec.md
  • QA run_id: {parent_run_id}-qa
  • QA report written to: deep-design-{run_id}/qa-report.md
  • The QA pass is read-only — it does NOT modify the spec
• If n: skip. Final output remains deep-design-{run_id}/spec.md alone.

Note: deep-qa targets the final spec as a document — it finds defects in completeness, consistency, and feasibility, not the design decisions themselves (those were deep-design's domain).

Golden Rules

1. Critics must be adversarial. An agent that says "looks good" is a failed critic. Push agents to find REAL problems, not cosmetic issues.
2. Every flaw needs a concrete scenario. "This might be unbalanced" is not a flaw. "A user who does X in situation Y breaks the system because Z" is a flaw.
3. Fixes must address root causes. The fix for "trivia questions make it too easy for bots" is not "ban trivia" — it's redesigning the question/interaction system.
4. Check fixes for cascading effects. Every fix is a design change. Design changes can introduce new flaws.
5. Classify honestly. Don't inflate minor flaws to critical. Don't downgrade critical flaws to minor.
6. The design is never perfect — it's "good enough." Termination means coverage is saturated, not zero flaws.
7. Maintain design coherence. Fixes must be consistent with the core concept. If a fix contradicts the core vision, flag the tension.
8. Validate flaws before accepting them. A flaw is only real if it survives the falsifiability check, contradiction check, and premise check. Cross-check every flaw against the full set of critiques — contradictory flaws indicate at least one is misdiagnosed.
9. Never nerf what you can redesign. Ask: "Can I change the FORMAT or CONTEXT so the strength doesn't matter?" Redesign the battlefield, don't handicap the fighters.
10. Question whether the feature should exist at all. Before fixing a flawed mechanic, ask: "Does this mechanic earn its place?" Removing a broken feature is often better than patching it.
11. Critique what's missing, not just what's there. The most dangerous flaws are often omissions — components referenced but not specified. A label ("prompt pool," "matchmaking system") is not a design.
12. Independence invariant. The coordinator orchestrates; it does not evaluate. Any load-bearing evaluation (severity classification, fact verification, cross-fix consistency, section-impact scoring) must be performed by an independent agent with no stake in the outcome.
13. Judges must be adversarial too. An independent judge that rubber-stamps critical claims is as useless as a critic that rubber-stamps good design. A 100% acceptance rate from a judge is evidence of failure.
14. Input transparency. Log all angle definitions with source and rationale. The independence invariant protects outputs — you must audit inputs.

Anti-Rationalization Counter-Table

These are excuses agents use under pressure to inflate "good" verdicts on weak designs. Each row is a defensive entry — when you catch yourself thinking the excuse, look at the reality.

When you catch ANY of these in your reasoning, stop and apply the relevant validation gate (falsifiability, premise, contradiction, nerf, existence checks) or independence delegation.

Self-Review Checklist

• State file is valid JSON after every round
• generation counter incremented after every state write
• core_claim_sha256 stored at Step 0; verified before each drift check
• No critique angle has status "in_progress" after round completes
• No spawn_failed angles treated as "spawned" — resume retries spawns, not waits
• Every critique file has: Flaws + Severity + Scenario + Suggested Fix + Mini-Synthesis + New Angles
• No critique angle explored > 2 times
• All critical flaws have a resolution (fixed, accepted, or disputed with rationale)
• All major flaws have a resolution or explicit acceptance with rationale
• Disputed flaws are documented in coordinator summary — not silently dropped
• Final spec does NOT read raw critique files — uses coordinator summary + mini-syntheses
• Final spec is internally consistent (no fix contradicts another fix)
• Final spec traces each design decision to the flaw that motivated it
• No stale component_invariants keys from renamed components (migration logged in component_name_history)
• Ordering graph edges sourced only from cross-fix checker structured output — not inferred from prose
• Termination label is "Conditions Met" or "Max Rounds Reached" — never "no critical flaws remain"
• Coverage report includes unverified sections and open issues
• GAP_REPORT counts persisted in state.json flaws[id].gap_report_count (not in-memory only)
• Invariant-validation agent ran after this round's redesign
• Judge prompt includes adversarial mandate
• Prospective gate uses turn-boundary model (not blocking prompt)
• Concept summary sent to critics matches core claim verbatim
• Frontier pop decisions logged in logs/frontier_pop_log.jsonl
• Coherence integrator ran after each critique round's critics completed and before severity judges (or degraded mode logged)
• Coherence annotations attached to flaws in state.json before judge input files were written
• Coverage gaps from integrator fed into frontier as CRITICAL-priority angles
• Emergent patterns surfaced in Step 8 final spec
• Outside-frame critic spawned this round

Critic Agent Prompt Template

When spawning each spec-derived critic agent, use this prompt structure. All data passed via file paths — not inline.

You are an adversarial design critic. Your job is to BREAK this design — find flaws, exploits, edge cases, and failure modes. Do NOT be nice. Do NOT say "overall this is good." Find REAL problems.

**Your critique dimension:** {angle.dimension}
**Your specific angle:** {angle.question}
**Design concept:** {concept_summary}

(concept_summary is the locked core claim text verbatim — it has not been paraphrased.)

**Current design spec file:** {spec_file_path}
Read this file to get the full spec.

**Known flaws file:** {known_flaws_file_path}
Read this file for flaw IDs and titles. Do NOT repeat any flaw with these IDs.

**Before filing flaws — Diagnostic Inquiry (REQUIRED):**

Answer each of these through the lens of your critique dimension BEFORE producing flaws. These MUST appear as a "Diagnostic Answers" section in your output file, above the Flaws section.

1. What is the mechanism this dimension depends on, and does the spec specify it (vs. merely name it)?
2. What is the most realistic consumer/user scenario in this dimension, and what does that scenario require that the spec must provide?
3. What assumption does the design make about this dimension that is not stated in the spec?
4. If this dimension's worst-case scenario occurs, which specific component in the spec absorbs the impact — and does the spec actually give that component the mechanism to do so?
5. What does the spec claim about this dimension that, if wrong, invalidates the core mechanism?

The Diagnostic Answers section forces you off auto-pilot before proposing flaws. Flaws that contradict your own diagnostic answers are likely misdiagnosed and will be dropped at validation.

**Instructions:**
1. Read the design carefully through the lens of your specific critique dimension
2. Think about real users — what would they ACTUALLY do? (not what the designer hopes)
3. Construct concrete scenarios where the design fails
4. For each flaw, provide:
   - A clear title
   - Severity: critical (design-breaking) / major (significantly degrades) / minor (polish)
   - A specific scenario demonstratin

…(truncated)