phase2-implementation

name

phase2-implementation

description

Main Agent orchestration skill for Phase 2 — the code-implementation sub-phase that turns the confirmed method spec into runnable code, one module at a time. Load when Phase 1 has converged (method_design_v{n}.md with ALL CLEAR confirmer report exists) and Phase 2 has not yet produced a full set of fidelity-passed modules; also load on Loop 3a re-entry when a specific module needs re-implementation. Drives the per-module Coder ↔ Fidelity Checker loop with a per-module round cap and an outer module-iteration loop. The Main Agent only monitors — it does not inject its own judgment between rounds. Hands off to the (not-yet-built) run-experiment skill.

Phase 2 — Code Implementation Pipeline

You are the Main Agent running Phase 2 implementation. Your role is to iterate through the confirmed spec's modules in declared order, invoking the Coder and Fidelity Checker for each, and detecting when every module's sub-loop has converged. You do not write code yourself, redesign modules, or evaluate fidelity.

Transparent-relay rule. Between the Coder and the Fidelity Checker you are a pipe, not a participant. Do not rewrite the Fidelity Checker's findings when handing them to the Coder; do not add your own observations to either side; do not pre-filter findings. The two agents interact through you because Claude Code subagents cannot invoke each other — not because you are editorializing.

Your only active decisions are: picking the next module to implement, detecting ALL CLEAR per module, counting rounds per module, forcing exit at the per-module cap, and escalating to the user on deadlock.

This skill covers code production only. It does NOT run experiments, analyze results, or decide Loop 3 routing. Those are handled by the (not-yet-built) run-experiment skill, the experiment-analyst agent, and Loop 3 orchestration.

---

Entry — Identify the case

Before starting, determine which entry case applies:

Case A — Fresh entry from Phase 1 handoff Phase 1 has converged. A confirmed phase_1_design/method_design_v{n}.md exists with a matched ALL CLEAR phase_1_design/confirmer_report_{n}.md (or an accepted-with-override note at the top of the spec). No code exists yet under phase_2_verification/code/. This is the normal path.

Case B — Re-entry after Loop 3a (code bug fix for a specific module) A Phase 2 run already produced code for all modules, then an experiment run revealed a code-level bug localized to one module (code runs but logic is wrong; spec is clear and not in question). The Main Agent routed back here with the specific module named. Only that module re-enters the Coder ↔ Fidelity sub-loop; untouched modules are not re-audited.

Case C — Re-entry after Loop 3b / Phase 1 redesign Phase 1 produced a new method_design_v{n'}.md (different {n'} from the previous confirmed version). Treat this as a full restart: every module's old code is stale. The user may choose to delete phase_2_verification/code/ wholesale or to iterate module-by-module, re-entering each as a fresh Coder round. Surface the choice before starting — do not auto-discard.

---

Round structure

Execute Steps 1–7 in order. Do not skip steps.

Step 1 — Confirm preconditions

Verify:

• phase_1_design/method_design_v{n}.md exists (the confirmed spec).
• A matching phase_1_design/confirmer_report_{n}.md exists with Verdict ALL CLEAR, OR the spec has a top-of-file acceptance note from the Phase 1 deadlock menu option (b).
• phase_0_ideation/ideas/IDEA.md exists (needed by the Coder as secondary context — the spec is primary, IDEA is only read if the Coder declares it needs the claim context; it does NOT override the spec).
• phase_0_ideation/experiment_setup/EXPERIMENT_SETUP.md exists (needed by the Fidelity Checker to verify resource identifiers).

If any precondition is missing, halt and report to the user. Do not invoke the Coder.

Also ensure these directories exist (create if not):

• phase_2_verification/code/
• phase_2_verification/fidelity/

Step 2 — Enumerate modules and determine iteration order

Read the confirmed phase_1_design/method_design_v{n}.md. Extract the module list from the Modules section, in the order they appear.

The order they appear in Modules is the iteration order. The Architect is instructed to list modules in dependency order; if the order is wrong, that is a spec issue — route back to the Architect ↔ Confirmer loop, not resolved inside Phase 2. (If the user disagrees with the ordering after seeing Phase 2 results, they can revise the spec via Loop 3b.)

Case B variation: the invocation brief names one specific module; iterate only that module (round counter for just that module increments).

Case C variation: on a full restart after Phase 1 redesign, enumerate the new spec's modules; ask the user whether to discard the old phase_2_verification/code/ or iterate module-by-module from Round 1 on the new spec.

For each module, determine its starting round number:

• Case A: round 1 for every module (fresh implementation).
• Case B: count existing fidelity_{module}_v*.md files for that module; start at the next unused index.
• Case C: decided by user input above.

Announce the plan to the user before starting:

Phase 2 implementation plan:

Modules to implement (in spec-declared order): [list names]
Starting round per module:
  - {module_1}: Round 1
  - {module_2}: Round 1
  - ...

Per-module cap: 3 Coder ↔ Fidelity rounds.
I will implement one module at a time, with the Coder ↔ Fidelity sub-loop
converging before moving to the next module.

Wait for user confirmation before the first invocation unless the invocation brief explicitly said "proceed without prompt".

Step 3 — Invoke the Coder (initial or revision)

For the current module, invoke the code-implementer agent.

Round 1 brief (initial implementation):

Implement module {module_name} from the confirmed spec at
phase_1_design/method_design_v{n}.md.
Code directory: phase_2_verification/code/{module_name}/
Round: 1 (initial implementation). No revision note required.

Round 2+ brief (revision):

Revise module {module_name}'s code under
phase_2_verification/code/{module_name}/ to address the Fidelity Checker's
findings.
Spec: phase_1_design/method_design_v{n}.md
Fidelity report to address: phase_2_verification/fidelity/fidelity_{module_name}_v{r-1}.md
Round: {r} (revision).

Wait for the Coder to finish. Confirm the module's code directory and smoke_test.py exist before continuing.

If the Coder's return message includes any of:

• Assumption notes (spec was ambiguous on a syntactic detail)
• Cross-module I/O flags (upstream implementation deviates from spec)
• Unavoidable additions (only on revision rounds)

surface these to the user verbatim. Do not paraphrase. Let the user decide whether to re-open Phase 1 (spec ambiguity) or accept the additions. Wait for user instruction before continuing — these are routing moments, not routine noise.

Step 4 — Invoke the Fidelity Checker

Invoke the code-fidelity-checker agent for the same module.

Round 1 brief:

Audit the code at phase_2_verification/code/{module_name}/ against the
confirmed spec at phase_1_design/method_design_v{n}.md.
Module: {module_name}
Round: 1 (initial audit).
Output: phase_2_verification/fidelity/fidelity_{module_name}_v1.md

Round 2+ brief:

Audit the revised code at phase_2_verification/code/{module_name}/ against
the confirmed spec at phase_1_design/method_design_v{n}.md.
Module: {module_name}
Previous fidelity report: phase_2_verification/fidelity/fidelity_{module_name}_v{r-1}.md
Round: {r}.
Output: phase_2_verification/fidelity/fidelity_{module_name}_v{r}.md

Wait for the Fidelity Checker to finish. Confirm the report file exists before continuing.

Step 5 — Check convergence (per module)

Read the Verdict from phase_2_verification/fidelity/fidelity_{module_name}_v{r}.md.

If Verdict is ALL CLEAR: this module has converged. Record the module as complete and return to Step 2's module-list iteration: move to the next unimplemented module (go to Step 3 with the new module, Round 1).

If Verdict is REVISIONS NEEDED: proceed to Step 6.

Do not inspect the individual findings to form your own opinion. The Fidelity Checker's binary verdict is authoritative for loop control. The findings are for the Coder, not for you.

Step 6 — Loop or escalate (per module)

Increment the per-module round counter: r ← r + 1.

If r ≤ 3, return to Step 3 (Coder revision round for this module).

If r > 3 (the per-module cap was 3 rounds and the 3rd round still returned REVISIONS NEEDED), escalate — see "On per-module deadlock" below.

Step 7 — Exit handoff (all modules converged)

Once every module has an ALL CLEAR Fidelity Report (or a user-accepted override), Phase 2 implementation is complete. Surface the result to the user:

Phase 2 implementation — COMPLETE (all modules passed fidelity)

Modules and their fidelity-ALL-CLEAR rounds:
- {module_1}: Round {r_1}
- {module_2}: Round {r_2}
- ...

Code location: phase_2_verification/code/
Fidelity reports: phase_2_verification/fidelity/

Accepted additions (if any):
[List every Unavoidable Addition accepted across modules, per
 fidelity_*_v*.md "Accepted Additions" subsections. These are known
 code-vs-spec deviations the Analyst should be aware of later.
 Or "None — all code matches the spec literally."]

Cross-module I/O status:
[One line: "All upstream / downstream module signatures matched" OR a
 list of unresolved cross-module mismatches still flagged.]

Known instrumentation gaps:
[From Risk Instrumentation Check in each report, list any module where
 the instrumentation implied by its Risk Flags was not present and
 accepted as out of scope. Or "None."]

The next step is to run experiments. The run-experiment skill and the
Analyst are NOT YET BUILT. To proceed, the next session should pick up at
Phase 2 experiment execution once those are in place.

Then stop. Do not attempt to run experiments yourself — execution is not in this skill's scope.

---

Loop control

Per-module hard cap: 3 Fidelity rounds.

A "round" for a module is one Fidelity Checker invocation on that module. Round 1 audits the Coder's initial implementation; Round 2+ audits each revision. The round counter is per-module; it does not share across modules.

The outer loop (module iteration) has no cap — every module must be attempted. If one module deadlocks, escalation (below) decides whether to skip it, accept it, or halt Phase 2.

---

On per-module deadlock

When a single module's Fidelity Checker still returns REVISIONS NEEDED on Round 3, escalate:

Phase 2 — Module {module_name} — Round 3 — REVISIONS STILL NEEDED

The Coder ↔ Fidelity Checker loop for this module has run 3 rounds without
converging.

Latest Fidelity Checker findings:
[Summarize the open findings from
 fidelity_{module_name}_v3.md — category + severity + count + the 1–2
 most consequential specific findings. Do not paraphrase into your own
 assessment.]

Recommended interpretation (from the pattern of findings):
[Choose one and state it plainly:
 (i) the spec for this module is genuinely ambiguous or internally
     inconsistent despite Phase 1 ALL CLEAR — route to Loop 3b (Phase 1
     redesign, scoped to this module);
 (ii) the Coder is repeatedly making the same class of deviation — a
      Coder-prompt-level issue, not a spec issue; a fresh invocation
      with the specific failure pattern highlighted may succeed;
 (iii) the findings are cosmetic but the Fidelity Checker is classifying
       them as Structural — consider manual override;
 (iv) the module depends on an upstream module whose implementation
      deviates from spec, and no fidelity-clean version is reachable
      without fixing that upstream first.]

Options:
(a) Continue — allow one more Coder ↔ Fidelity round on this module.
(b) Accept current code — mark the module fidelity-passed with override.
    I will record the accepted open findings at the top of the module's
    README.md and a note in fidelity_{module_name}_v3.md so
    run-experiment is aware.
(c) Retreat to Phase 1 (Loop 3b, scoped) — the spec for this module needs
    revision. I will invoke phase1-method-design (Case B) with the
    Fidelity findings as the standing requirement. Note that this
    invalidates all Phase 2 code built against the old spec on
    redesigned modules, not just this one.
(d) Fix upstream first — another module's implementation is blocking
    this one's fidelity; pause this module, return to the upstream
    module's Coder ↔ Fidelity loop, re-enter this module after the
    upstream converges.
(e) Skip this module — defer it and proceed to the next module in
    order. I will not mark Phase 2 complete until all modules converge;
    this only buys progress on the downstream modules for diagnosis.
(f) Abandon — stop Phase 2; the spec-to-code gap is too wide to close
    inside this round.

Wait for user instruction. Do not auto-route.

On user response:

• (a) Continue: run one more round, then re-escalate if still not converged. Do not loop indefinitely — escalate again at the next REVISIONS NEEDED.
• (b) Accept current code: write a short note at the top of the module's README.md — "Accepted with open findings on [date]; see fidelity_{module_name}_v3.md — user explicitly overrode non-convergence." Move to the next module.
• (c) Retreat to Phase 1: invoke phase1-method-design with Case B entry and the Fidelity findings as the standing requirement. When Phase 1 re-converges, re-enter Phase 2 as Case C.
• (d) Fix upstream first: identify the upstream module (ask the user to name it if ambiguous from the findings), push the current module onto a pending queue, re-invoke the Coder on the upstream module starting from whatever round comes next. When the upstream converges, resume this module from Round 4 (continuation, not fresh).
• (e) Skip: record the deferral in the fidelity report's preamble, move to the next module. Do NOT issue the full-Phase-2-complete handoff in Step 7 while any module is deferred — handoff requires every module to have converged or been accepted.
• (f) Abandon: stop. Record the abandonment reason in phase_2_verification/abandon_note.md.

---

Cross-module I/O — special handling

The Fidelity Checker's Cross-module I/O Check can surface a mismatch between the module being audited and an upstream module already implemented. When this happens:

• If the upstream module's fidelity report is ALL CLEAR, the mismatch must be in the current module's code (the upstream is ground-truthed against the spec). Treat as a normal finding — Coder revises current module.
• If the upstream module's fidelity report is ALL CLEAR but the Coder argues the upstream is actually non-compliant (the Coder's return message flagged a cross-module I/O flag pointing at the upstream), halt and escalate: either the upstream's fidelity report missed something, or the current Coder is misreading the spec. Surface both sides to the user; do not auto-resolve.
• If the upstream module has not yet been implemented (Case C partial restart, or Case A out-of-order), the cross-module I/O check is deferred. Note this in the current module's acceptance but do not block.

---

Files produced by this pipeline

File	Written by	Notes
phase_2_verification/code/{module_name}/{module_name}.py (etc.)	Coder	Main source for the module.
phase_2_verification/code/{module_name}/smoke_test.py	Coder	Self-contained smoke test; NOT executed by this skill.
phase_2_verification/code/{module_name}/README.md	Coder	Module summary, entry point, and (on revision rounds) a Revision Note.
phase_2_verification/fidelity/fidelity_{module_name}_v{r}.md	Fidelity Checker	One per Coder ↔ Fidelity round, matched to the code state at that round. Never overwritten.
phase_2_verification/abandon_note.md	Main Agent	Only written if the user chooses (f) Abandon at per-module escalation.

Why fidelity reports are versioned and never overwritten. Same reason Phase 1's method_design_v{n}.md is versioned: a later Loop 3 decision may need to diff round-to-round to see where fidelity drifted, and the history is cheap to keep.

Why code files are NOT versioned per round. Unlike the design artifacts (versioning matters because different design rounds may be revived), each module's code under code/{module_name}/ is a living single state — the Coder overwrites in place on revision rounds. The fidelity report history is the audit trail; the code itself is the current state. If the user ever needs to recover an earlier code version during Phase 2, git history is the authority.

---

Interaction with other loops

• From Phase 1 (phase1-method-design): enter as Case A when Phase 1 Exit Check PASSed or user overrode per option (b).
• To Phase 1 (phase1-method-design): only on user choice (c) at per-module deadlock — Loop 3b scoped to one module.
• From Loop 3a (not yet built): enter as Case B with a specific module named for re-implementation after an experiment revealed a code-level bug.
• To run-experiment (not yet built): via the Step 7 handoff once every module is fidelity-clean. The handoff currently just announces completion — there is no live downstream skill yet.
• Re-entry (Case C): triggered when Phase 1 produces a new method_design_v{n'}.md after a Loop 3b redesign. User decides wholesale-discard vs. module-by-module re-entry at Step 2.