design-then-apply-loadbearing
The pattern
For LOAD-BEARING code, subagents DESIGN precise edit-plans; the MAIN LOOP applies, verifies, tests, and commits them ONE AT A TIME. The subagent makes NO edits to the tree.
This is the Planner/Editor/Verifier split (SAFEdit, AgentForge, XieZhi) with the Editor + Verifier roles HELD BY THE ORCHESTRATOR, not delegated. An agent edit is a hypothesis; on money-path / transport / eval-runner / contract code you cannot land a hypothesis blind, and on a concurrently-dirty tree you cannot trust an agent's git add not to sweep a peer's in-flight work.
The unit of subagent output is an edit-plan, not a diff-in-the-tree:
FILE: <abs path>
ANCHOR (old_block): <verbatim unique slice from the real file>
REPLACEMENT (new_block): <exact text>
WHY: <one line — the bug / gap>
TEST DESIGN: <the test name + the assertion that fails before / passes after>
CONTRADICTING-CONTRACT CHECK: <grep for an existing test on the changed symbol — or NONE>
When to use this vs worktree-isolated editors
|
this skill (design-then-apply) |
worktree-isolated editor agents |
| who edits the tree |
the ORCHESTRATOR, one plan at a time |
each AGENT, in its own checkout |
| the code |
load-bearing: transport / money-path / eval-runner / contracts |
greenfield, mechanical, or large parallel refactor |
| the tree |
concurrently dirty with a peer's mainline lanes |
clean or fully owned by this run |
| failure it prevents |
over-reach landed blind; git add sweeping a peer's edit; per-file-green hiding cross-file breakage |
N agents trampling one working tree |
Use worktree isolation when the work is parallel and self-owned. Use THIS when correctness is load-bearing AND the mainline is shared — worktree isolation does not protect a peer's in-flight changes on the SAME mainline.
The loop (orchestrator-owned)
- Design (subagent, sonnet; opus for a hard debug). One subagent per gap (or a design-Workflow for a cluster). It returns edit-plans ONLY — no Edit/Write/mutating-Bash. Pass the load-bearing constraint + the contradicting-contract check verbatim.
- Apply ONE. Read the REAL file; apply old_block→new_block with Edit. If old_block doesn't match the live file VERBATIM, the plan is STALE — re-Read + re-anchor; NEVER force, never hand-translate the agent's JSON-escaped block blind (
>/< un-escape, indentation).
- Verify vs real code. The plan's WHY must be true of the file you just read, not of the agent's mental model. Grep for an existing test/contract on the changed symbol — a test asserting the OPPOSITE means the "bug" is INTENDED; DEFER it.
- Test it. Write the designed test, run it (+ ruff, +
bash -n for shell, + a $0 behavioral check for a transport/gate). Run the FULL relevant suite, not just the one file — per-file-green hides cross-file breakage (a schema-test in another file caught a real regression this session).
- Commit exact slices.
git add <the-files-this-fix-touched>, never git add . / git add <whole-file> while a peer edits the same file — that sweeps the concurrent edit into a mislabeled commit.
- Next plan. Money/security-path fixes follow the SAFE direction over the finding (fix the contradicting doc, not the safe code).
Red flags — STOP
- Pasting an agent's
new_block into Edit without first Reading the real file (the anchor may be stale).
- "The per-file test is green" → you have NOT verified cross-file breakage. Run the broad suite.
git add <file> when a workflow/peer is editing that file → check git diff first.- Trusting a modeling/library error message's OWN fix advice (it can be WRONG — verify against the real imports/source).
Receipt
A design-Workflow once designed several load-bearing gap-fixes (an env-var transport encoding bug, a config auto-load gap, an honesty-gate edge case, a pre-flight mode check); the orchestrator applied + verified + tested + committed each one-at-a-time. An earlier same-session workflow had an agent OVER-REACH into a file outside its assigned scope (the failure this skill prevents). Cross-references: worktree-fanout dynamic workflows, and a template encoding the agent-owns-the-apply / verify-the-finding discipline, if this project has one.
1---2name: design-then-apply-loadbearing3description: Use when changing LOAD-BEARING code (a transport/driver path, a money-path or safety gate, the eval runner, a reload/merge contract, a release script) with help from subagents — ESPECIALLY when the working tree is concurrently dirty with another agent's in-flight lanes so worktree isolation cannot protect the human-owned mainline. Triggers on "have a subagent fix the transport/driver/money-path", "multi-gap hardening of one file", "an agent edit broke a contract test in another file", "a concurrent-agent git-add swept my change", "apply-then-verify the agent's patch", or any time an agent EDIT would be a hypothesis you must not land blind. NOT for greenfield/throwaway code or large parallel refactors with no shared mainline — those want worktree-isolated editor agents instead.4---56# design-then-apply-loadbearing78## The pattern910For LOAD-BEARING code, subagents **DESIGN** precise edit-plans; the **MAIN LOOP** applies, verifies, tests, and commits them ONE AT A TIME. The subagent makes NO edits to the tree.1112This is the Planner/Editor/Verifier split (SAFEdit, AgentForge, XieZhi) with the **Editor + Verifier roles HELD BY THE ORCHESTRATOR**, not delegated. An agent edit is a *hypothesis*; on money-path / transport / eval-runner / contract code you cannot land a hypothesis blind, and on a concurrently-dirty tree you cannot trust an agent's `git add` not to sweep a peer's in-flight work.1314The unit of subagent output is an **edit-plan**, not a diff-in-the-tree:1516```17FILE: <abs path>18ANCHOR (old_block): <verbatim unique slice from the real file>19REPLACEMENT (new_block): <exact text>20WHY: <one line — the bug / gap>21TEST DESIGN: <the test name + the assertion that fails before / passes after>22CONTRADICTING-CONTRACT CHECK: <grep for an existing test on the changed symbol — or NONE>23```2425## When to use this vs worktree-isolated editors2627| | this skill (design-then-apply) | worktree-isolated editor agents |28|---|---|---|29| who edits the tree | the ORCHESTRATOR, one plan at a time | each AGENT, in its own checkout |30| the code | load-bearing: transport / money-path / eval-runner / contracts | greenfield, mechanical, or large parallel refactor |31| the tree | concurrently dirty with a peer's mainline lanes | clean or fully owned by this run |32| failure it prevents | over-reach landed blind; `git add` sweeping a peer's edit; per-file-green hiding cross-file breakage | N agents trampling one working tree |3334Use worktree isolation when the work is parallel and self-owned. Use THIS when correctness is load-bearing AND the mainline is shared — worktree isolation does not protect a peer's in-flight changes on the SAME mainline.3536## The loop (orchestrator-owned)37381. **Design (subagent, sonnet; opus for a hard debug).** One subagent per gap (or a design-Workflow for a cluster). It returns edit-plans ONLY — no Edit/Write/mutating-Bash. Pass the load-bearing constraint + the contradicting-contract check verbatim.392. **Apply ONE.** Read the REAL file; apply old_block→new_block with Edit. If old_block doesn't match the live file VERBATIM, the plan is STALE — re-Read + re-anchor; NEVER force, never hand-translate the agent's JSON-escaped block blind (`>`/`<` un-escape, indentation).403. **Verify vs real code.** The plan's WHY must be true of the file you just read, not of the agent's mental model. Grep for an existing test/contract on the changed symbol — a test asserting the OPPOSITE means the "bug" is INTENDED; DEFER it.414. **Test it.** Write the designed test, run it (+ ruff, + `bash -n` for shell, + a $0 behavioral check for a transport/gate). Run the FULL relevant suite, not just the one file — **per-file-green hides cross-file breakage** (a schema-test in another file caught a real regression this session).425. **Commit exact slices.** `git add <the-files-this-fix-touched>`, never `git add .` / `git add <whole-file>` while a peer edits the same file — that sweeps the concurrent edit into a mislabeled commit.436. Next plan. Money/security-path fixes follow the SAFE direction over the finding (fix the contradicting doc, not the safe code).4445## Red flags — STOP4647- Pasting an agent's `new_block` into Edit without first Reading the real file (the anchor may be stale).48- "The per-file test is green" → you have NOT verified cross-file breakage. Run the broad suite.49- `git add <file>` when a workflow/peer is editing that file → check `git diff` first.50- Trusting a modeling/library error message's OWN fix advice (it can be WRONG — verify against the real imports/source).5152## Receipt5354A design-Workflow once designed several load-bearing gap-fixes (an env-var transport encoding bug, a config auto-load gap, an honesty-gate edge case, a pre-flight mode check); the orchestrator applied + verified + tested + committed each one-at-a-time. An earlier same-session workflow had an agent OVER-REACH into a file outside its assigned scope (the failure this skill prevents). Cross-references: worktree-fanout dynamic workflows, and a template encoding the agent-owns-the-apply / verify-the-finding discipline, if this project has one.
oimiragieo