Edit Design

Reading workflow files (TOC protocol)

When you Read any file under .claude/workflow/ or .claude/skills/, follow the protocol in conventions.md §1.8:

1. Read the TOC region: from <!--Document index start--> to <!--Document index end--> (read to the closing delimiter, not a fixed line count). If the file has no TOC region (a file whose only ## heading is this bootstrap block carries none, per §1.8(d)), read the file in full.
2. Match TOC rows where Roles contains any of your roles (or your role is any, or the row's Roles is any) AND Phases contains any of your phases (or your phase is any, or the row's Phases is any).
3. Use Read(offset, limit) to read only matched sections; if no row matches your role/phase, the file holds nothing for you — do not read further.

Your role: orchestrator, planner, or final-designer (whichever invoked this skill). Your phase: determined by the auto-resume State in workflow.md § Startup Protocol.

Inline refs you find inside workflow files carry the same name:roles:phases suffix; apply file-level filtering before opening: a ref matches when any of your roles is in its roles and any of your phases is in its phases, your own any on either axis matches every ref on that axis, and a ref whose own roles or phases is any matches you. Backtick-wrapped refs carry no suffix; open or skip them at your discretion.

<!--Document index start-->

<!--Document index end-->

Apply an edit to design.md (or design-mechanics.md) through the mutation discipline defined in .claude/workflow/design-document-rules.md. The skill bundles (apply edit → auto-review → bounded iterate → present) into one atomic action so the structural rules are self-enforcing. On the creation kinds (phase1-creation, phase4-creation) the skill is a multi-agent orchestrator: it spawns the code-grounded author to write the document and runs the dual-clean inner loop (the cold readability auditor plus a per-round second check) followed by the cold comprehension gate. The interactive kinds keep the original single-agent shape (edit inline, one cold-read, iterate).

Stamp discipline. design.md and design-mechanics.md carry a line-1 <!-- workflow-sha: <40-char SHA> --> stamp written at creation only: by this skill on the phase1-creation and length-trigger-crossing kinds, or by /create-plan's planning-transition step when it seeds design.md directly. Every other mutation kind (content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, mechanics-edit, design-sync) leaves the stamp untouched and preserves its line-1 position; only creation, migration replay, and no-drift normalization write the stamp. The prepend is performed via Edit/Write against the now-existing file, not a shell redirect. design-mutations.md is deliberately excluded from stamping (see the review-log append step for the rationale). Phase 4 final artifacts (design-final.md, design-mechanics-final.md) are not stamped either; they survive the merge into develop where per-branch migration never applies. Format definition, parser idioms, and the paired SHA-computation idiom that the phase1-creation and length-trigger-crossing kinds copy verbatim are anchored in conventions.md:orchestrator,planner,final-designer:1,3A,3C,4 §1.6. Read that section for the single source of truth.

You MUST use this skill — not raw Edit/Write — for every modification to design.md / design-mechanics.md and for every Phase 4 creation of design-final.md / design-mechanics-final.md. That includes initial creation in Phase 1 (phase1-creation), interactive iteration ("add a section about X"), and Phase 4 production of the final committed artifacts (phase4-creation). The design is frozen after Phase 1 (design-document-rules.md Rule 15), so Phase 3 inline replanning never invokes this skill — replan design intent is recorded in the plan's Decision Records and the track narrative instead (see inline-replanning.md:orchestrator:3A,3C § Process).

Two operational modes

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="Working mode edits the polished design; sync mode re-distills it from the mechanics companion." -->

The skill supports two complementary workflows. Pick by where you are in the plan lifecycle:

• Working / sync (Phase 1 and large iterative revisions): mutation kinds phase1-creation, mechanics-edit, design-sync. design.md stays frozen between syncs as a stable reference; cold-read is deferred to sync.
• Direct mutation (small post-publication edits): mutation kinds content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, length-trigger-crossing. Full discipline runs on every mutation.

Phase 4 special case. Phase 4 produces design-final.md (and design-mechanics-final.md if the original had a mechanics companion). Use the phase4-creation kind — structurally similar to phase1-creation (one-shot creation, full discipline; one or both files depending on whether a mechanics companion is needed) but targeting the *-final.md paths and skipping plan / track-file ref propagation (those refs point at the original design.md, not at the new final artifact). No follow-up mechanics-edit / design-sync cycle: Phase 4 is committed once.

Full rationale, sub-phase diagram, and sync-trigger rules live in design-document-rules.md § Two-mode editing — working vs sync.

Skill inputs

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="The mutation kind, target file(s), and edit payload the skill consumes on each invocation." -->

The invoking agent supplies these when calling the skill:

If any required input is missing, ask the user before proceeding. The mutation discipline depends on the agent stating the mutation kind explicitly so the cold-read scope and check-set are correct; do not guess.

Cold-read scope and check-set by mutation kind

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="The per-mutation-kind table mapping each kind to its target files, cold-read scope, and mechanical check set." -->

The --target column reads as a function of whether design-mechanics.md exists at the time of the mutation. When a value is written design \| both, resolve to design if the mutation touches only design.md (the common case for small designs without a mechanics companion) or both if the mutation also propagates into design-mechanics.md.

Periodic whole-doc check. Independent of mode: every Nth design-touching mutation (default N=5, counted from the review log) escalates the cold-read scope to whole-doc regardless of the kind. mechanics-edit mutations do NOT increment this counter.

Two distinct N=5 counters. Both fire at "5", but they count different things and trigger different actions; do not collapse them mentally:

See design-document-rules.md:planner,final-designer:1,4 § Mutation discipline § Cold-read scope by mutation kind for the canonical statement of both counters.

Workflow

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="The mutation loop: a dual-clean multi-agent loop for creation kinds, a single-agent loop for interactive kinds." -->

The high-level steps are the same across all mutation kinds; what differs is who does the work inside the apply and review steps, and how the cold-read pass is gated. Two shapes run under one frame:

• The creation kinds (phase1-creation and phase4-creation) run the dual-clean multi-agent loop. Step 1 spawns the code-grounded author instead of authoring inline; Step 4 spawns the per-round readability-auditor plus its second per-round check (the warm absorption check at phase1-creation, the fidelity check at phase4-creation), then, after the inner loop converges, the cold comprehension gate; Step 6 is the bounded dual-clean inner loop. These are the kinds the design-creation callers route through: create-plan Step 4a routes phase1-creation, create-final-design.md routes phase4-creation.
• Every other (interactive) mutation kind keeps the single-agent shape. Step 1 applies the edit inline; Step 4 spawns the cold comprehension gate (plus, on design-sync only, a cold readability-auditor prose pass so the re-distilled human-facing prose keeps its one prose owner, S4); Step 6 iterates on the merged findings. These kinds touch a frozen, already-reviewed design.md post-publication, so the author spawn buys nothing and the lighter loop is correct.

There is no in-skill adversarial pass on any kind. The decision/assumption challenge for phase1-creation was relocated onto the research log at the Phase 0 → 1 gate (D6, prompts/adversarial-review.md §Research-log-scoped review (Phase 0→1)), so for phase1-creation the Step 4 cold comprehension gate is gated behind that log-adversarial gate clearing (the S3 freeze-order gate; see Step 4) rather than preceded by a local adversarial step. Every other mutation kind runs its cold-read with no gate.

Step 1: Apply the edit

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="Spawn the code-grounded author for the creation kinds or edit inline for the interactive kinds; stamp only on creation." -->

The apply step has two shapes. The creation kinds (phase1-creation, phase4-creation) spawn the code-grounded author to write the document; the skill never writes the seed content inline. Every interactive mutation kind (content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, length-trigger-crossing, mechanics-edit, design-sync) applies the edit inline with Edit/Write as before — read the target file first to satisfy the Edit precondition, then apply the focused edit or full-file rewrite. The stamp directives below apply to both shapes (the author writes content; the skill owns the line-1 stamp).

Spawn the author for the creation kinds. For phase1-creation and phase4-creation, decide the companion-file shape and the seed scope exactly as described below, then hand that decision to the design-author agent rather than writing the content yourself. The author is the sole writer of the document (.claude/agents/design-author.md): it reads the research log and the live codebase through PSI — never this authoring conversation — and drafts cold-readable prose for a reader who has only the finished document. The author write happens on round 1 of the inner loop and again on each later round against the auditor's flagged passages; the spawn mechanics, the params-file contract, and the ground-once-with-targeted-re-grounding lever live in Step 6 (the inner loop) where the per-round author re-spawn is wired. On round 1 the author writes the full seed; Step 1's job is to settle the companion-file and seed-scope decision the round-1 author spawn carries.

For phase1-creation: decide first whether the design needs a mechanics companion. Default is single file. Most designs (under ~5 sections, no # Part N headings, no anticipated long-form derivations) seed only design.md — pass target=design and leave design_mechanics_path=null. The author seeds design.md with Overview (concept-first elevator pitch), Core Concepts (when the doc will have Parts or ≥3 new domain terms), Class Design, Workflow, and TL;DR-shaped Part sections.

Seed both files only when the design genuinely needs the split — typically when the user has signaled it up front ("this will have a mechanics companion") or when a single-file seed would already exceed the 2,000-line / 50,000-token length trigger. In that case, pass target=both and design_mechanics_path=<abs path>; the author seeds design-mechanics.md with the long-form mechanism content that supports each design.md section, with section names matching between the two files from the start. A design that doesn't need mechanics on day 1 crosses into one later via length-trigger-crossing, not by retroactively re-running phase1-creation.

Stamp the seeded file(s) with an idempotency guard. Apply this directive after the initial Write lands the seeded content on disk; the presence check then runs against the just-written file. A missing file is treated identically to an unstamped file. phase1-creation is the canonical writer for design.md (and design-mechanics.md when target=both), but /create-plan's planning-transition step also writes design.md directly from its own template with the stamp already in place. Both invocation paths converge here, so the directive below must stamp an unstamped file and skip the prepend on an already-stamped one.

For each path the kind touches (design_path; design_mechanics_path as well when target=both), run the presence check from conventions.md:orchestrator,planner,final-designer:1,3A,3C,4 §1.6(a1):

head -1 <path> | grep -qE '<!-- workflow-sha: [0-9a-f]{40} -->'

A zero exit code means the file is already stamped — skip the prepend for that path (this is the post-/create-plan case, where design.md's line 1 already carries the stamp written by the planning-transition step's template, or the target=both case where /create-plan seeded the dual files and both files already carry the stamp). A non-zero exit code means the file is unstamped — compute $WORKFLOW_SHA via the §1.6(b) paired idiom and prepend <!-- workflow-sha: $WORKFLOW_SHA --> (followed by a newline) above the H1, then re-read the file to satisfy the next Edit precondition:

WORKFLOW_SHA="$(git log -1 --format=%H HEAD -- .claude/workflow .claude/skills .claude/agents)"
[ -z "$WORKFLOW_SHA" ] && WORKFLOW_SHA="$(git rev-parse HEAD)"

Compute $WORKFLOW_SHA at most once per invocation — when both paths need a stamp (a direct phase1-creation invocation outside /create-plan with target=both), reuse the same value so the two sibling files start life with matching stamps. The guard is symmetric across design_path and design_mechanics_path: a same-invocation run where /create-plan pre-stamped one file and the other was added after (an edge case the guard tolerates by design) is handled by the per-path presence check.

Cross-session target=both may produce non-matching stamps on design.md and design-mechanics.md when the phase1-creation invocation lands in a later session than /create-plan's preamble. The drift gate's no-drift normalization collapses the divergence on the next clean gate run, and the per-branch migration reunifies the stamps end-of-migration.

For phase4-creation: same as phase1-creation — the author writes the document — but the file paths are design-final.md and (optional) design-mechanics-final.md, and the content reflects what was actually built (not the planned design). The author grounds on the step and track episodes and the live code rather than the research log (the Phase 4 second check is fidelity, not absorption; see Step 6). The caller (prompts/create-final-design.md) is expected to have run the PSI-backed verification tables before invoking the skill, so each diagram element traces to a real code location. Do not pass --plan-path / --plan-dir (the cross-file ref check is naturally skipped; see the table above). Skip the idempotency-guarded stamp directive above. Phase 4 final artifacts are not stamped: see the Stamp-discipline blockquote at the top of this file and conventions.md §1.6(f).

For length-trigger-crossing: split a single-file design.md that has grown past the ~2,000-line / ~50,000-token threshold into the canonical pair. Caller-supplied design_mechanics_path carries the absolute path of the new sibling file; target=both. Move every long-form mechanism walk-through, full state-machine table, exhaustive worked example, and file:line citation out of design.md and into the freshly-created design-mechanics.md. Keep Overview, Core Concepts, every section's TL;DR + mechanism overview + edge cases + references footer in design.md; keep diagrams in design.md and duplicate any diagram into design-mechanics.md only when the mechanics-side prose needs the same visual context. Every section name in design-mechanics.md matches the corresponding section name in design.md byte-for-byte so that each section's Mechanics: design-mechanics.md §"<exact same section name>" link resolves and the plan / track-file **Full design** references land in either file by name. See design-document-rules.md:planner,final-designer:1,4 § Length-triggered split into design-mechanics.md for the canonical split rule.

Stamp the freshly-created design-mechanics.md before continuing. The file is unstamped at creation, so the per-path presence check from conventions.md:orchestrator,planner,final-designer:1,3A,3C,4 §1.6(a1) will always return non-zero on this path — but applying the guard keeps the directive symmetric with the phase1-creation paragraph above and tolerates a re-invocation against an already-split pair:

head -1 <design_mechanics_path> | grep -qE '<!-- workflow-sha: [0-9a-f]{40} -->'

A non-zero exit code (the expected case) means the file is unstamped — compute $WORKFLOW_SHA via the §1.6(b) paired idiom and prepend <!-- workflow-sha: $WORKFLOW_SHA --> (followed by a newline) above the H1 in design-mechanics.md, then re-read the file to satisfy the next Edit precondition:

WORKFLOW_SHA="$(git log -1 --format=%H HEAD -- .claude/workflow .claude/skills .claude/agents)"
[ -z "$WORKFLOW_SHA" ] && WORKFLOW_SHA="$(git rev-parse HEAD)"

The $WORKFLOW_SHA value is computed at trigger time, not at the original phase1-creation moment, so the new design-mechanics.md's stamp can differ from its design.md sibling's stamp by however many workflow-format commits landed between the two creation events. The asymmetry is expected — the no-drift normalization in the drift gate collapses the divergence on the next clean gate run, and the per-branch migration reunifies the stamps when it next runs end-to-end. design.md already carries a stamp from its earlier creation; leave that stamp byte-for-byte intact (the move of mechanism content from design.md is a content-edit-shaped mutation against line 1's position-preservation contract from §1.6(a)). The intra-invocation SHA reuse rule from the phase1-creation paragraph does not apply here: only design_mechanics_path is stamped, and design.md's line-1 stamp is preserved byte-for-byte under §1.6(a).

For design-sync: see Step 1.5 below — sync has a distillation sub-step before the apply.

Do not retry the apply — if Edit fails because old_string is not unique or doesn't match, surface that to the user and stop. The mutation action does not paper over a malformed edit.

Step 1.5: Distillation (only for design-sync)

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="For design-sync only, re-distill the polished design from the current mechanics companion before the cold read." -->

Sync re-distills design.md from the current state of design-mechanics.md. The agent does the distillation:

1. Read the most recent design-sync entry in <plan-dir>/design-mutations.md to find the last sync point.
2. Walk every mechanics-edit entry after that point — each entry's "Diff summary" tells you what changed in mechanics.
3. For each section in mechanics whose content moved since the last sync, update the corresponding section in design.md:
   • TL;DR: re-write to reflect the current mechanism.
   • Mechanism overview: update the prose to match the new mechanics.
   • Edge cases / Gotchas: add/remove/edit bullets to mirror mechanics.
   • References footer: ensure the Mechanics: link still resolves and any new D/S codes are listed.
4. For sections added in mechanics: create a corresponding section in design.md following the per-section mandatory shape.
5. For sections removed in mechanics: remove from design.md (or, if the section was renamed, propagate the rename and update the Mechanics: link).
6. Update plan / track-file **Full design** refs for any section that was added/removed/renamed in this sync — the plan-file checklist entries' Decision Records and every track file's ## Decision Log may carry references to the affected section.

Apply the distilled design.md to disk via Edit/Write.

Step 2: Determine cold-read scope

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="Pick the cold-read scope (bounded or whole-doc) for this mutation kind from the check-set table." -->

Per the table above. For mechanics-edit, scope is none (cold-read is skipped) — proceed straight to Step 3 mechanical checks.

For other mutations: track a mutation counter from the review log. Count all design-touching entries (everything except mechanics-edit) since the log was created. If count % 5 == 0 (i.e., this is the 5th, 10th, 15th mutation), escalate the cold-read scope to whole-doc.

Step 3: Run mechanical checks

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="Run the mutation kind's mechanical checks (link resolution, stamp position, section presence) before the cold read." -->

python3 .claude/scripts/design-mechanical-checks.py \
    --design-path <design_path> \
    --design-mechanics-path <design_mechanics_path or omit> \
    --plan-path <plan_path or omit> \
    --plan-dir <plan_dir or omit> \
    --changed-section "<title>" \
    --target <design|mechanics|both> \
    --scope <bounded|whole-doc>

Two flags need derivation:

• --target comes from the cold-read scope table above (column 3). When the table writes design \| both, resolve to design if the mutation only edits design.md (no design-mechanics.md companion exists, or the rename / rewrite did not propagate into mechanics) and to both if both files are touched in this mutation.
• --scope is the mechanical-check scope — orthogonal to the cold-read scope conveyed to the sub-agent. Pass --scope=bounded (and supply --changed-section) when column 4's cold-read scope starts with bounded; the script then runs the per-section shape check only on <changed-section> instead of every section. Other checks (per-section length cap, parenthetical asides, top-level cap, mechanics-link resolution, full-design-link resolution, reverse- direction refs) always run whole-doc regardless of --scope. Pass --scope=whole-doc for any kind whose cold-read scope is whole-doc (or for mechanics-edit, where there is no cold-read but the script still runs in whole-doc mode for the parenthetical- aside scan over the mechanics file). The cold-read scope itself is passed through the sub-agent prompt's Inputs block, not via this CLI flag.

For mechanics-edit, --design-path is still required even though the design.md file is not touched by this mutation kind — it is the reference for cross-file ref checks and reverse-direction-ref detection. Treat design.md as read-only inputs to the script for this kind.

The script prints JSON to stdout. Exit code 0 ⇒ no blockers; 1 ⇒ NEEDS REVISION. Capture and parse the JSON; do not act on the exit code alone — the findings list is what drives iteration.

Step 4: Run the review sub-agents

<!-- roles=orchestrator,planner,final-designer phases=1,4 summary="Spawn the review roles: the per-round pair plus the S3-gated gate for creation kinds, else one comprehension read." -->

Step 4 owns the review-spawn contracts; Step 6 owns the round-by-round sequencing that calls them. The review surface has two shapes:

• Creation kinds (phase1-creation, phase4-creation) run three review roles. Each round of the inner loop (Step 6) spawns the cold readability-auditor plus the round's second check; after the inner loop converges to dual-clean, Step 4 spawns the cold comprehension-review gate once. The second check is the warm absorption-check for phase1-creation and the fidelity check for phase4-creation (this skill calls the same author, auditor, and comprehension gate on both kinds and swaps only the second check; its spawn contract is the per-round paragraph under §"Spawning the per-round auditor and second check").
• Interactive kinds run the cold comprehension-review gate — no author spawn (Step 1 edited inline), no inner loop, no second check. For every interactive kind except design-sync the comprehension gate is the only review role; the lighter single-pass cold-read is unchanged in substance, only re-pointed onto the comprehension-review agent definition (its Read,Grep allow-list is the D13/D14 tool-surface cut).
• design-sync also spawns a readability-auditor prose pass. design-sync re-distills the human-facing design.md from the mechanics companion, so its freshly rewritten prose is judged on the prose AI-tell axis like any other human-facing surface. The de-warmed comprehension gate runs that axis nowhere (D9), so leaving design-sync on the comprehension gate alone would strand the prose axis on neither reviewer — the "never neither" case S4 forbids. design-sync therefore stays an interactive kind (no author spawn, no inner loop, no absorption check) but gains one cold readability-auditor spawn alongside its comprehension-review gate, so the auditor is the single prose owner on design-sync (S4 holds), matching what design-document-rules.md and prompts/design-review.md assert. The auditor's findings merge into the same single-agent fix loop (Step 6) as the comprehension-gate findings.

Skip review entirely for mechanics-edit. Mechanics is agent-targeted long-form content, not the human-facing summary; comprehension is not the discipline that protects it. The next design-sync will cold-read against the re-distilled design.md.

Skip the review when mechanical checks have any blocker finding. No point asking a sub-agent to assess comprehension if the structure is broken — iterate on mechanical first, then review once the doc is structurally sound. On the creation kinds this skip applies to the per-round pair as well: a round whose just-written draft fails a mechanical blocker iterates mechanical-first before the auditor and second check run.

The per-round pair spawns are wired in Step 6 (the inner loop), because they re-spawn every round with that round's slice ranges and flagged-passage lists. This step defines their spawn contracts (the agent types, the params-file contract, the cache warm-up) so Step 6 can call them; the comprehension gate below is the one role Step 4 spawns directly, after Step 6 reports dual-clean.

Spawn contract shared by all review roles (D13/D14 cost levers)

Every review role is an agent definition with a minimal tools: allow-list, not a general-purpose spawn — the per-spawn tool surface is the largest fixed cost, so cutting it is the first cost lever (D13). Spawn each via the Agent tool with subagent_type set to the agent's basename:

Per-agent parameters go in a params file, not the spawn prompt (D13). The spawn prompt body stays byte-identical across the fan-out so the shared prompt body (including the injected CLAUDE.md, which cannot be skipped per-agent, D14) caches. Write each round's per-agent inputs — the auditor's slice range, each role's target / target_path / output_path, the author's target / research_log_path / output_path / design_path (track/full seed) / round / flagged_passages (its full set matches design-author.md § Inputs key-for-key, so the round-1 author has the research_log_path it grounds from), the absorption check's research_log_path and draft_path, the fidelity check's episodes_path / draft_path / design_path (and explicitly no research_log_path) — to a params file under _workflow/reviews/ (one file per spawn; this authoring-loop review scaffolding lives in the plan-scoped reviews home per conventions-execution.md §2.5 Third-scope review-file home), and pass only that file's path in the spawn prompt. Each agent reads its params file as its first action (its agent definition mandates this). A varying spawn-prompt tail would bust the whole shared body, so never inline a per-agent value into the prompt.

Fan-out cache warm-up (D13, the tunable cost lever). When a round fans out more than one auditor slice, sequence the fan-out instead of racing it: spawn one auditor, wait a short fixed delay (the warm-up delay, default about a minute) for its cold prefix write to land and propagate, then spawn the rest concurrently against the now-warm prefix. This takes the fan-out from N cold prefixes to roughly one cold plus the rest at a fraction. Do not block until the first agent finishes — the cache TTL could age the prefix out and serializing loses the parallelism; wait only the fixed warm-up delay. The wait mechanism is an implementation choice deferred to wiring (gate A7): use whatever non-blocking fixed delay the harness offers between the first spawn and the rest; if no such delay mechanism is available, disable the warm-up and pay N cold prefixes. The warm-up is a cost lever, not a correctness dependency: its delay is a tunable with a measured fallback (a heavy author's long first turn can push its cold write past the default delay, so the delay may need to be role-specific), and the loop must produce correct dual-clean output with the warm-up disabled (the disabled path just pays N cold prefixes). Confirm the byte-identical-prompt assumption against the live Agent-tool prompt assembly when wiring this; the assumption is what makes the shared body cache, and it is the lever's only correctness-adjacent precondition.

The S3 freeze-order gate (creation kinds, before the comprehension gate)

Block the comprehension gate while a log-adversarial entry is open (the S3 freeze-order gate). Under D6 the decision/assumption challenge runs as a gate on the research log at the Phase 0 → 1 boundary, not as a local adversarial pass here. So for phase1-creation, after the inner loop reports dual-clean and before spawning the comprehension gate, read the research log's ## Adversarial gate record section (the gate's durable verdict carrier; the heading shape and the open/resolved and latest-dated-entry rules are defined once in research.md §The research log under Gate-record cadence). The gate's own review files under _workflow/reviews/ are ephemeral and not the carrier. The gate's verdict is encoded in the section's headings: when the gate has looped, match the latest dated heading, and a NEEDS REVISION heading with any open blocker or should-fix is an open entry. The comprehension gate must not run while the latest log-adversarial entry is open: that is the S3 invariant. A design.md draft cannot reach the comprehension gate while a log-adversarial entry is open, so a load-bearing decision surfaced while authoring the design (whether the author appended it to the log or the absorption check surfaced a draft-invents-decision finding) is re-challenged at the gate and cleared before the comprehension gate assesses it. When the gate is clear (every log-adversarial entry resolved), proceed to the comprehension gate; the comprehension pass then assesses a design whose decisions have already survived challenge. The de-warmed comprehension reviewer reads no log itself, so the gate guards it on the loop's behalf, not for the reviewer's own sake. The author and the absorption check are the log readers the gate protects.

The S3 gate holds across the D15 batch loop-back. Once design.md is presented for review, post-presentation findings queue and batch through the D15 review-iteration loop (create-plan/SKILL.md § Step 4 review-hold batching). A decision-shaped finding (a comprehension-gate finding, or an absorption-surfaced draft-invents-decision) re-enters the gate step — it is appended to the log and re-challenged — so the gate re-opens and the comprehension gate does not re-run until the log entry is resolved again. There is no path where the comprehension gate runs with an open log entry, on the first pass or on any batch loop-back iteration.

Spawning the comprehension gate

For the creation kinds, spawn the comprehension gate only after Step 6 reports the inner loop dual-clean and (for phase1-creation) the S3 gate is clear. For the interactive kinds, the comprehension read is the cold-read pass (the only one, except on design-sync, which also runs the readability-auditor prose pass below) — there is no inner loop and no gate; spawn it once mechanical has zero blockers. Either way, spawn the comprehension-review agent via the Agent tool:

• subagent_type: comprehension-review
• description: "Cold comprehension gate (<mutation_kind>)"
• prompt: a byte-identical body that names the params file (per the shared spawn contract above). The params file carries the ## Inputs block the comprehension-review agent forwards to prompts/design-review.md:

- design_path: <abs path>
- design_mechanics_path: <abs path or "(none)">
- scope: <bounded|whole-doc>
- bounded_scope: <changed_section name + surrounding section names, when bounded>
- mutation_kind: <kind>
- plan_path: <abs path or "(none)">
- plan_dir: <abs path or "(none)">

No research_log_path is ever passed to the comprehension gate. The absorption-completeness cross-check moved off this role onto the per-round absorption-check spawn (below), so the comprehension gate's params file names no log path; the comprehension-review agent reads no log regardless (S1/S2). If a log path is wired into its params file, that is a wiring error.

Inject output_path only for phase4-creation. When mutation_kind == phase4-creation, the comprehension gate's params file carries one more line so the Phase 4 cold-read persists its output to a file and returns a summary (prompts/design-review.md § Output format, the path-conditional branch; the review-file coverage rule in conventions-execution.md §2.5):

- output_path: <abs path under _workflow/reviews/ for the cold-read output>

For every other kind — including phase1-creation — omit the output_path line. The comprehension gate's no-path branch then returns its verdict inline.

For design-sync, also include in the params file body: "This sync re-distills design.md from the current state of design-mechanics.md. Verify that every TL;DR and mechanism overview in design.md accurately summarizes the current mechanics file's content for the same-named section."

Also spawn the readability-auditor for design-sync (the one prose owner, S4). design-sync is the only interactive kind whose review surface adds a prose pass, because it rewrites the human-facing design.md prose. Spawn the cold readability-auditor over the re-distilled design.md so the prose AI-tell axis lands on exactly one reviewer (the auditor) and is never stranded on the de-warmed comprehension gate that runs it nowhere (D9/S4). This is a single cold prose pass, not the creation-kind inner loop: no author spawn, no absorption check, no per-round re-grounding, no cache warm-up (one auditor over the whole document). Spawn it via the Agent tool with subagent_type: readability-auditor and description: "Readability audit (design-sync)", following the same params-file-plus-byte-identical-prompt contract. The auditor's params file carries target=design, target_path=<design_path>, and a whole-document range (the sync re-distills the whole design.md, so it is not range-sliced like a creation-kind fan-out); it names no research_log_path (S1 — the auditor never reads the log). It intentionally omits slice_count and total_lines: this single whole-document pass is not a fan-out, so the agent-side whole-doc guard must stay inert here (per readability-auditor.md § The whole-doc guard, the guard applies only when both params are present). Passing them would falsely trip the guard, since a whole-document design.md over 300 lines is exactly the collapse shape the guard catches on the design-creation path — but here it is the legitimate sync surface, not a bypassed partition. The auditor's findings merge into the same single-agent fix loop (Step 6) as the comprehension-gate findings; the loop's inline fixes re-distill the flagged prose, and the loop re-runs the auditor on the next iteration like any other finding source.

The comprehension gate returns a structured Markdown verdict per the prompt's output format, in one of two shapes split by whether output_path was injected (prompts/design-review.md § Output format, the path-conditional branch):

• output_path absent (the default — every kind except phase4-creation): the sub-agent returns the full Markdown inline. Parse the Verdict line (PASS or NEEDS REVISION) and the inline Structural findings list.
• output_path supplied (phase4-creation): the sub-agent returns only a summary (the Verdict line plus the blocker/should-fix counts) and writes the ## Structural findings detail to the file at output_path. Parse the Verdict and counts from the return, then partial-fetch the written file's ## Structural findings section for the finding detail that Step 5 merges.

Spawning the per-round auditor and second check (creation kinds)

Step 6 spawns these every round of the inner loop; their contracts live here. The auditor runs on both creation kinds; the second check is the absorption check on phase1-creation and the fidelity check on phase4-creation. All three follow the shared params-file-plus-byte-identical-prompt contract above.

The readability auditor (subagent_type: readability-auditor, description: "Readability audit (<mutation_kind> round <N>)") fans out one spawn per slice. Each slice's params file carries target=design, target_path=<design_path>, the slice range, and the two slicing-metadata params slice_count and total_lines (defined under "Deterministic design-path slice partition" below). The auditor reads only house-style.md, its slice, and the standing anchors (the ## Overview and ## Core Concepts of design.md); its params file names no research-log path (S1). It returns the enumerated readability findings for its slice.

Deterministic design-path slice partition (the mandatory fan-out rule). The fan-out is a deterministic orchestrator obligation, not a free choice. It is the same partition /readability-feedback Procedure step 2 carries (the proven rule this ports). Compute the slice set as a pure function of inputs the orchestrator already holds — the design's total line count, a ~200-line window, and a ~6-window cap — so two runs on the same document produce the same slices:

1. Capture total_lines (the design.md line count) and the ## / # Part heading boundaries (grep -nE '^#{1,3} ' <design_path>).
2. Split design.md into ~200-line windows aligned on those ## / # Part boundaries. Cap at ~6 windows. Spawn exactly one auditor per window. This is the slice_count.
3. Whole-doc floor (a hard invariant). Never emit a single whole-doc slice for a design.md over ~300 lines. The ~200-line window already forces this: any doc over ~250 lines yields ≥2 windows. The floor is restated as an invariant so the rule cannot be misread as permitting one whole-doc spawn. A doc under ~300 lines legitimately produces one slice (see the agent guard below — that single-slice short-doc case is not a collapse).

Verifiable spawn count (the orchestrator self-check). Before the fan-out, compute expected_slice_count from step 2's rule (total line count, the ~200-line window, the ~6 cap). Spawn exactly that many auditors and assert slices_spawned == expected_slice_count. On a mismatch, stop and surface a wiring error — report the bad slice count rather than proceeding with the wrong fan-out. This self-check is the orchestrator's own assertion; it is not visible to the auditor.

The self-check and the agent-side guard (in readability-auditor.md) enforce the floor independently — a deliberate redundant double-check, not a redundancy bug. The two layers are not coextensive: the agent-side guard fires only on the total collapse (slice_count == 1 AND total_lines > ~300), so this orchestrator self-check is the sole catcher of a partial collapse (e.g. 2 slices where the partition demands 5). The redundancy is full for the total-collapse case and self-check-only for a partial-count mismatch.

slice_count and total_lines are constant across a round's fan-out — slicing metadata, not conclusions about the prose — so passing them does not nudge any auditor toward a finding and does not breach the cold-read guarantee (S1). Keep the partition decision separate from the cache warm-up framing above: the warm-up only sequences the N>1 spawns (it spaces the first cold prefix from the rest) and never reduces N to 1. "Disable the warm-up" means "pay N cold prefixes," never "run one whole-doc spawn."

The absorption check (phase1-creation only — subagent_type: absorption-check, description: "Absorption check (phase1-creation round <N>)") is the role that carries the research_log_path (the injection that pre-de-warm lived on the comprehension cold-read). Its params file carries target=design, research_log_path=<abs path to _workflow/research-log.md>, and draft_path=<design_path>. It does two-way coverage matching: every load-bearing research-log decision (each ## Decision Log entry whose **Alternatives rejected:** field names a real fork) appears as a seed D-record in design.md, and no seed D-record invents a decision the log lacks. A missing seed D-record is a finding the Step 6 inner loop must resolve before dual-clean; a draft-invents-decision that is load-bearing re-opens the S3 gate (above) exactly as a decision-shaped comprehension finding does.

The fidelity check (phase4-creation only — subagent_type: fidelity-check, description: "Fidelity check (phase4-creation round <N>)") is the Phase 4 second check, in the slot the absorption check fills at phase1-creation. It grounds on the episodes and the code, not the log, because Phase 4 reflects what was built rather than what was planned (S6) — so no research_log_path is passed on the Phase 4 path. Derive its three paths from the design directory, not from the --plan-dir flag (which phase4-creation omits): design-final.md is fixed at docs/adr/<dir>/design-final.md, so the episodes directory and the frozen seed sit at a fixed offset from it. Its params file carries episodes_path=<docs/adr/<dir>/_workflow/plan/> (the plan/track-N.md files whose ## Episodes sections it matches against), draft_path=<the skill's design_path arg, = design-final.md> (the document it is checking), and design_path=<the frozen docs/adr/<dir>/_workflow/design.md, NOT the skill's design_path arg> for the residual reference only; it carries no research_log_path. It matches design-final.md against the episodes both ways: a claim an episode contradicts is a finding the Step 6 inner loop must resolve before dual-clean, and a behavioral claim with no episode trace routes to the code through PSI rather than passing on an unrecorded episode-match (gate A8, the coverage residual). A design-final.md claim that re-asserts a decision an episode records as superseded is a finding (S6). The fidelity check's Read + PSI allow-list is the D13/D14 tool-surface cut; it reads no log (S2), so it is not gated by the S3 freeze-order gate that protects the absorption check and the author. The check is text-against-text for the bulk and PSI only for the diagram / signature precision and the no-episode-trace residual, so the per-round cost stays close to the absorption check's.

Map every review role's findings into the same severity schema as mechanical findings.