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, so touching a file another phase owns corrupts its in-flight edit. 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.