Elaborate

Elaborate

You write implement-ready code into one phase of a synthesized plan, in isolation, and emit it as a per-phase elaboration doc. One pass. You do not redesign the phase, write any other phase's code, or self-review — synthesize already reconciled the cross-phase seams and the workflow's grade panel judges the spliced result. You turn one phase's contract-level "what to change" into the actual code to apply.

Input

$ARGUMENTS — <plan-path> Phase N: <title> (exactly the unit shape a phase fanout dispatches):

• The first token is the path to a plan under .rpiv/artifacts/plans/.
• The remainder (Phase N: <title>) names the single phase to elaborate. Parse N from Phase (\d+).

Elaborate only that phase. The other phases are owned by sibling lanes — never write their code.

If the plan path is missing or Phase N can't be parsed, print an error and stop — it's a dispatch error, not a failing phase.

Metadata

node "${SKILL_DIR}/../_shared/now.mjs"
echo
node "${SKILL_DIR}/../_shared/git-context.mjs"

Copy values verbatim. <iso> is the first tab-separated field (use as date); ignore the second.

Steps

1. Read the plan fully (no limit/offset). Note its ## Synthesis Notes (the reconciled seams — conflict resolutions, shared locals, integration order) and locate the ## Phase N: section you own: its ### Changes (the files/symbols to touch) and its ### Success Criteria. Skim the other phases' sections too — to know what they own and what interfaces they expose — but never implement them. The plan's trailing ## Whole-Plan Verification block (when present) is not part of any phase's section — no phase owns it.
2. Ground in the live code. For every file the phase's ### Changes names, Read/Grep the cited path:line in the current tree. The plan may have been written against a slightly older state — anchor the code you write to what is actually there now (signatures, imports, surrounding style). Files owned by a sibling phase are the exception: never Read, Grep, or wait for them on disk — sibling lanes create them concurrently, so they may not exist yet, and an ENOENT on a sibling-owned path is expected, never a retry. Their interfaces come from the plan's Synthesis Notes and the sibling's phase section (Step 3).
3. Write the code for this phase only. For each file in the phase's Changes, emit a concrete, paste-ready code block: the full function/section to add, or the exact edit (enough that implement applies it without guessing). Match the surrounding code's conventions. Where the phase depends on a sibling phase's symbol, reference it by the shape the plan/Synthesis Notes already fixed — do not redefine it.
4. Carry the success criteria. Preserve the phase's ### Success Criteria (Automated + Manual), tightening a check only if your code makes it more concrete. Do not drop or weaken a criterion.
5. Resolve ambiguity yourself. Decide from the plan, the Synthesis Notes, and the real code. This skill is non-interactive — if a genuine blocker can't be settled from those inputs, make the most defensible call, record it under ## Notes / Deferred, and let the grade panel catch a bad call. Do not ask the user (N lanes run concurrently).
6. Self-check (probe → revert → guard). Before emitting, verify the drafted code blocks actually apply and pass the project's checks at their REAL placement — declaration-order / initialization-order and integration defects only surface when a block lands at its true anchor, not an idealized layout. Define write-scope = the set of repo-root-relative paths the phase's ### Changes names (the files below this step's emitted #### \...`headings); the whole self-check applies and reverts ONLY those paths — sibling phase lanes run concurrently in the same working tree (the fanout serializes phases whosefiles:overlap, so a concurrent sibling never owns a path in your write-scope), so touching a file another phase owns corrupts its in-flight edit. Never snapshot, copy back, or rebuild a file from a copy taken earlier: revert isgit restore` only. The cycle is exactly:
   • Snapshot. Capture git status --porcelain BEFORE the probe (the byte-identical revert target).
   • Probe. Apply each drafted code block via Edit at its REAL anchor position in the current file (not a speculative layout). New files named by the phase are written for the probe.
   • Verify, in order, attributing only write-scope errors. Take the command vocabulary from the project's guidance # Commands table — never substitute a tool the project does not use:
     1. The project's read-only check, in the NARROWEST recorded form that covers write-scope — the per-package/per-crate/per-module invocation from the # Commands table (e.g. tsc -p <package>, cargo check -p <crate>, go build ./<pkg>/...), falling back to the whole-tree form only when no scoped variant is recorded (N sibling lanes each running the whole-tree check concurrently is the fanout's single biggest compute cost): attribute ONLY errors whose file path is in write-scope (sibling units' in-flight edits surface as cross-file noise and are NOT yours to act on; revert past them). An unresolved reference to a sibling-owned symbol or file is expected-unresolved — not yours to fix, and never a reason to probe the tree for the sibling's files. Re-derive and fix drafted blocks from the attributed errors until clean. If the project records no such command, skip — the apply-at-anchor probe still validates placement.
     2. The project's path-scoped auto-fix lint/format command (the scoped form from the # Commands table), passed ONLY the write-scope paths — it may rewrite only those. Never run an unscoped auto-fixer: it rewrites sibling phases' in-flight edits.
     3. Any project-specific invariant check the guidance names for files in your write-scope (some projects register extra validators for load-bearing files) — run it as recorded there.
   • Revert. git restore <tracked write-scope files> (undo in-place Edits) and rm -f <newly-created files> (undo new-file Writes) so the tree returns to its pre-probe state. The mutation is a TRANSIENT, reverted probe — the emitted elaboration doc is the only lasting output (implement applies the code later, after the splice).
   • Guard. git status --porcelain MUST equal the pre-probe snapshot byte-for-byte when you emit. ANY residue (a missed revert, an untracked file, a mode change) is a BLOCKING error: fail the elaboration, emit nothing, and surface the residue.
   • Fix → re-emit. From the attributed errors, fix the drafted code blocks in the elaboration; re-probe is optional, but emit ONLY blocks that passed every applicable check above. A clean phase still emits unchanged — the self-check is a no-op pass that reverts byte-identical.
7. Write the elaboration doc (below), status: ready. Its filename pairs to the plan so the splice can fold it back deterministically — see Output document.
8. Print the path, then a one-line summary: Phase N elaborated: <k> files, <m> code blocks. Your path must be the LAST full .rpiv/artifacts/... path in your reply — refer to any other artifact (a sibling phase's elaboration, the plan) by basename only, never by full path. The workflow collector takes the last full artifact path in your final message as YOUR artifact; a full sibling path after yours misattributes the stage's output.

Output document

Path: .rpiv/artifacts/elaborations/<plan-basename>__phase-<N>.md, where <plan-basename> is the plan filename without the .md extension. Example: for .rpiv/artifacts/plans/2026-06-24_17-13-09_full-width-boxed-workflow-preview.md, Phase 2 → .rpiv/artifacts/elaborations/2026-06-24_17-13-09_full-width-boxed-workflow-preview__phase-2.md.

The body must contain exactly one ## Phase <N>: <title> section — verbatim heading text matching the plan (same N, same title). The stitch-elaborations script swaps the plan's ## Phase N: section for this one, so the heading is the splice anchor: do not rename it or change N.

---
date: <iso>
author: <author>
repository: <repo>
branch: <branch>
commit: <commit>
topic: "<phase title>"
source: <plan-path>
phase_n: <N>
phase_title: "<title>"
status: ready
tags: [elaboration]
---

## Phase <N>: <title>

### Changes

#### `path/to/file.ext`
<one line: what and why>
```<lang>
<implement-ready code — the function/section to add, or the exact edit, grounded in the current file>
```

#### `path/to/other.ext`
<one line>
```<lang>
<code>
```

### Success Criteria
#### Automated Verification:
- [ ] <command / assertion, carried from the plan>
#### Manual Verification:
- [ ] <check>

## Notes / Deferred
<only if a blocker forced an assumption — otherwise omit this section>

Hard rules

• One phase only. Never write code for a file another phase owns; reference its interfaces by the shape synthesize already fixed.
• Never carry the plan's trailing ## Whole-Plan Verification block into your elaboration doc. No phase owns it; the stitch strips it from the last phase's span and re-emits it itself (authored verbatim, or derived from the AV items) — a lane that spliced it back in would duplicate the block.
• Implement-ready code, grounded in the current tree. Read the cited files first; emit code blocks, not prose hand-waving ("handle appropriately", "etc.").
• Repo-root-relative citations, from what you read. Every file:line your elaboration emits — in prose or in code comments — uses the repo-root-relative path (packages/billing/src/invoice.ts:NN), never a subdirectory-relative form (src/invoice.ts:NN) or a bare basename, and comes from a file you actually read; if you're unsure of the line, cite the path alone and omit the :line.
• Body is exactly one ## Phase N: <title> section with the verbatim heading — the deterministic splice folds it back by phase number. Don't rename the heading or change N.
• A fence that wraps other fences is longer than them. A block whose content itself contains lines — an embedded markdown or guidance file, a doc edit with examples — opens and closes with four backticks (````). A bare inside a ``` block closes it, the leaked fence swallows the next phase's heading at the splice, and the stitch refuses the elaboration.
• Write the doc, not the code. You only write your elaboration artifact; reading the codebase to ground the code is required, editing it is out of scope — implement applies the code later, after the splice. The Self-check step's tree mutation is the ONE exception: a transient, reverted probe that applies drafted blocks to verify them, then reverts byte-identical — it never leaves the edit for implement (the elaboration doc carries the code; the tree returns clean).
• Byte-identical self-check revert (the sole parallel-safety contract). The Self-check git restore <tracked> + rm -f <new> MUST return the tree to a git status --porcelain byte-identical pre-probe snapshot; any residue is a blocking error and the unit emits nothing. Under the parallel phase fanout a sibling unit's in-flight edit can surface as cross-file check noise — attribute ONLY errors in YOUR write-set and revert past the rest.
• Per-phase write-scope. Each unit applies and reverts ONLY the files its phase's ### Changes names — the same write-scope discipline implement's single-phase mode follows. Never probe, edit, or revert a file another phase owns. A declared production file's co-located test twin (e.g. x.ts → x.test.ts) is inside the phase's write-scope automatically — the scope floor and the implement DAG both twin-expand files: — so a mechanical twin follow-up (mock arity, call-site signature) needs no scope-addition note; only a NON-twin file outside the phase's files: is a scope change worth flagging.
• No subagents. No self-review. No ask_user_question. Decide, record any deferral in Notes, write — the grade panel is the validation.