# Edit Design

> Apply an edit to `design.md` or `design-mechanics.md` through the mutation discipline: apply → auto-review → iterate → present. Use this instead of directly Editing those files.

- Skill: `jetbrains/edit-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jetbrains/edit-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jetbrains/edit-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jetbrains (https://skillmd.com/u/jetbrains)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jetbrains/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-->

| Section | Roles | Phases | Summary |
|---|---|---|---|
| §Two operational modes | orchestrator,planner,final-designer | 1,4 | Working mode edits the polished design; sync mode re-distills it from the mechanics companion. |
| §Skill inputs | orchestrator,planner,final-designer | 1,4 | The mutation kind, target file(s), and edit payload the skill consumes on each invocation. |
| §Cold-read scope and check-set by mutation kind | orchestrator,planner,final-designer | 1,4 | The per-mutation-kind table mapping each kind to its target files, cold-read scope, and mechanical check set. |
| §Workflow | orchestrator,planner,final-designer | 1,4 | The mutation loop: two shapes — the dual-clean multi-agent loop for the creation kinds, the single-agent loop for the interactive kinds. |
| §Step 1: Apply the edit | orchestrator,planner,final-designer | 1,4 | Spawn the code-grounded author for the creation kinds or edit inline for the interactive kinds; stamp only on the creation kinds. |
| §Step 1.5: Distillation (only for `design-sync`) | orchestrator,planner,final-designer | 1,4 | For design-sync only, re-distill the polished design from the current mechanics companion before the cold read. |
| §Step 2: Determine cold-read scope | orchestrator,planner,final-designer | 1,4 | Pick the cold-read scope (bounded or whole-doc) for this mutation kind from the check-set table. |
| §Step 3: Run mechanical checks | orchestrator,planner,final-designer | 1,4 | Run the mutation kind's mechanical checks (link resolution, stamp position, section presence) before the cold read. |
| §Step 4: Run the review sub-agents | orchestrator,planner,final-designer | 1,4 | Spawn the review roles: the per-round pair plus the S3-gated comprehension gate for creation kinds, or the single comprehension read for interactive kinds. |
| §Step 5: Merge findings | orchestrator,planner,final-designer | 1,4 | Merge the mechanical-check and review findings into one deduplicated list for the iterate step. |
| §Step 6: Iterate | orchestrator,planner,final-designer | 1,4 | Run the dual-clean inner loop for creation kinds or the single-agent fix loop for interactive kinds until findings clear or the cap is reached. |
| §Step 7: Append to the review log | orchestrator,planner,final-designer | 1,4 | Append the mutation's record to the design-mutations log, which is itself exempt from stamping. |
| §Step 8: Auto-suggest sync at N=5 (working mode only) | orchestrator,planner,final-designer | 1 | In working mode, suggest a design-sync once five mechanics edits have accumulated since the last sync. |
| §Step 9: Present to the user | orchestrator,planner,final-designer | 1,4 | Present the merged result and surviving findings to the user as the mutation's final output. |
| §Staleness reconciliation | orchestrator,planner,final-designer | 1,4 | The prompt shown when a request references a polished design that mechanics edits have since outpaced. |
| §Tools used | orchestrator,planner,final-designer | 1,4 | The tools the skill invokes: the mechanical-check script, Edit/Write, and the author and review-role spawns. |
| §When NOT to use this skill | orchestrator,planner,final-designer | 1,4 | The cases that bypass the mutation discipline: non-design files and pure workflow-artifact edits. |
| §Failure modes and recovery | orchestrator,planner,final-designer | 1,4 | How the skill recovers when a check fails, the cold read stalls, or the iteration budget is exhausted. |
| §Examples | orchestrator,planner,final-designer | 1,4 | Worked examples of a content edit and a section rename run through the full mutation discipline. |
| §Reference | orchestrator,planner,final-designer | 1,4 | On-demand pointers to the design-document rules, the file layout, and the mutation-kind definitions. |

<!--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:

| Input | What it carries |
|---|---|
| `design_path` | Absolute path to `design.md` (or `design-final.md` in Phase 4). |
| `design_mechanics_path` | Absolute path to `design-mechanics.md` (or `null` if no companion). |
| `plan_path` | Absolute path to `implementation-plan.md` (for `**Full design**` link resolution). |
| `plan_dir` | Absolute path to the `plan/` directory containing every `plan/track-N.md` track file (same purpose — each track file's `## Decision Log` may carry `**Full design**` references that the cross-file ref check has to resolve). |
| `target` | `design`, `mechanics`, or `both` — the file(s) the edit touches. Threaded through to the script's `--target` flag verbatim. (No `.md` suffix — the script's argparse choices are `design`/`mechanics`/`both`.) |
| `intended_edit` | Either `(old_string, new_string)` for a focused edit, or full new content for a section-add / section-rewrite / file creation. |
| `mutation_kind` | One of the values listed in the mode table above. |
| `changed_section` | Title of the section being changed (for bounded cold-read scope). For `section-rename`, supply the **new** name. Optional for `mechanics-edit` and `design-sync`. |
| `iteration_budget` | Default `3` — max number of (apply → review) rounds. |

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`.

| Mutation kind | Touches | Mechanical script `--target` | Cold-read scope |
|---|---|---|---|
| `phase1-creation` | `design.md` only when the design will not need a mechanics companion (small designs under ~5 sections), or both files when the design will exceed the length trigger / already plans for mechanics | `design \| both` | `whole-doc` on `design.md` (mechanics is exempt from cold-read since it's agent-targeted) |
| `mechanics-edit` | mechanics only | `mechanics` | **NONE** — cold-read deferred to next `design-sync` |
| `design-sync` | both files (re-distill `design.md` from updated mechanics) | `both` | `whole-doc` on `design.md`, plus mechanics-link-resolution sweep |
| `content-edit` | `design.md` | `design` | `bounded` — changed section + 1-2 surrounding sections + Overview + (when present) Core Concepts |
| `section-add` | `design.md` | `design` | `bounded` — new section + Overview + (when present) Core Concepts + structure roadmap |
| `section-remove` | `design.md` (+ plan / track-file ref cleanup — `**Full design**` lines pointing at the removed section must be updated in the same mutation, otherwise `**Full design**` link resolution fails) | `design` | `whole-doc` |
| `section-rename` | `design.md` + (when mechanics exists) the matching section in `design-mechanics.md` + plan / track-file ref propagation | `design \| both` | `whole-doc` |
| `section-move` | `design.md` | `design` | `whole-doc` |
| `structural-rewrite` | `design.md` + (when mechanics exists and any rename or split propagates) the matching sections in `design-mechanics.md` | `design \| both` | `whole-doc` |
| `length-trigger-crossing` | both files (split into design-mechanics) | `both` | `whole-doc` |
| `phase4-creation` | `design-final.md` + (optional) `design-mechanics-final.md` | `both` if mechanics-final exists, else `design` | `whole-doc` on `design-final.md` (mechanics-final is exempt — agent-targeted long-form). Skip plan / track-file ref propagation: omit `--plan-path` / `--plan-dir` so the cross-file ref check is naturally skipped. |

**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:

| Counter | Counts | Resets on | Triggers |
|---|---|---|---|
| Periodic whole-doc counter | All mutation log entries except `mechanics-edit` | Never resets — running modulo over the log | Cold-read scope is escalated to `whole-doc` for the current mutation, regardless of its declared scope |
| Working-mode counter | `mechanics-edit` entries since the most recent `design-sync` (or since `phase1-creation` if no sync has happened yet) | Resets to 0 on every `design-sync` | The skill surfaces *"5 mechanics edits have accumulated since the last sync — want me to run `design-sync`?"* at the next conversational turn (Step 8) |

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)`:

```bash
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:

```bash
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:

```bash
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:

```bash
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." -->

```bash
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:

| Role | `subagent_type` | Allow-list | Reads the log? |
|---|---|---|---|
| code-grounded author | `design-author` | `Read`,`Write`,`Edit`,`Bash`,PSI | yes (the sanctioned authoring read, S2) |
| cold readability auditor | `readability-auditor` | `Read`,`Grep` | **never** (S1) |
| warm absorption check (`phase1-creation`) | `absorption-check` | `Read`,`Grep` | yes (the sanctioned absorption read, S2) |
| fidelity check (`phase4-creation`) | `fidelity-check` | `Read`,PSI | **never** (matches episodes + code, not the log) |
| cold comprehension gate | `comprehension-review` | `Read`,`Grep` | **never** |

**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 th

…(truncated)