/dotnet-techne-refactor-pipeline

name: dotnet-techne-refactor-pipeline
description: "Use when the user asks for a phase-gated refactoring or redesign loop - session-blind workers map and trace the area, empirical probes precede the design, an approval gate guards implementation, and a conformance audit re-checks the branch after any design change. State persists in .episteme/DESIGN-<slug>.md. Requires the refactor agent roles registered by scripts/install-codex.sh. Keywords: refactor loop, redesign, design gate, enumerate before design, conformance audit."
license: MIT
compatibility: Requires a Codex CLI with multi-agent tools enabled (agents.enabled, default true) and the refactor-* roles registered in config.toml. Without the roles, run the phases yourself in this context - the phase discipline still applies.

Refactoring/design loop (multi-agent)

You are the orchestrator. Do not enumerate or trace code yourself - dispatch session-blind workers, persist their artifacts, and hold the gates. **No code is written or edited until the design is approved at the Phase D gate.**

The roles: `refactor-cartographer`, `refactor-tracer`, `refactor-surveyor` (lighter mode), `refactor-conformance-auditor`. List your available agent roles; if they are missing, tell the user to run `scripts/install-codex.sh` from the plugin, then either stop or (with the user's consent) run the phases yourself in this context.

Step 0 - Resolve target and state

• Target: a ticket id or an area description. Slug it (e.g. `yb-1234`).
• State file: `.episteme/DESIGN-<slug>.md` at the repository root (create `.episteme/` if

missing). Codex has no reload hook: **re-read the file at the start of every session.**

• **If it exists**, route on its frontmatter - the file is the source of truth, never

conversation memory: `status: done` → nothing to resume; `status: blocked` → restate the blocker and ask; `status: awaiting-approval` → re-present the design at the Phase D gate; `status: active` → resume at the phase in `phase:`.

• **If not**, create it with frontmatter (`target`, `sources` - where the request came from,

`phase: R`, `status: active`, `design_revision: 0`) and sections `Why`, `References`, `Map`, `Traces`, `Probes`, `Design (approved)`, `Decision log`, `Deferred`, `Todo`, `Review findings`. Keep the frontmatter current and flush worker artifacts to the file the moment they return. `Decision log` and `Deferred` are append-only.

• Fill `Why` and `References` before Phase R, while the request is still fresh. They are the

only sections a later reader cannot reconstruct from the code, and a `target` line is not a problem statement. `Why` is prose, not a list: the defect or goal in the reader's terms, what triggered the loop, why it is worth doing now rather than later, and what breaks if nothing changes. A loop that cannot state its problem in a paragraph should not be spending a worker fan-out on a map. `References` is a provenance table: ticket and sibling ticket ids, the review or PR threads, prior QA or design files, the contract/spec source, vendor docs or live schema fetched, probe artifacts, and the host-repo rule sections applied. Cite them as ids and paths, not as bare claims - "the reviewer asked" is unusable six weeks later. Both are stable: revise them only when the problem itself changes, and never to make the design that emerged look like the one that was intended.

• Invariant pack: extract the 5-15 lines of project-specific design invariants relevant to the

target (CLAUDE.md sections, architecture docs). Workers receive this pack and artifact data only - never conversation narration; their blindness to the session is the anti-anchoring mechanism.

Step 1 - Phase R: recall

State to the user, in 3-5 bullets, the problem from `Why` in one line, the standing rules, plus anything in the Decision log: fix the **invariant, not the instance**; **dataflow over references** (what value reaches this branch during an outage, not who uses this type); **distrust names after changing behavior**; **empirical before architectural**.

Step 2 - Phases E+T: enumerate and trace

**Lighter mode** for small targets (one service, a handful of paths; when unsure run the full pipeline): spawn a single `refactor-surveyor` that maps and traces in one pass. It reports `ESCALATE: <reason>` when the area turns out bigger than one pass should carry - then rerun the full fan-out.

**Full mode**: spawn `refactor-cartographer` - one per service, in parallel - with repository root, target, invariant pack, and scope hints. Then `refactor-tracer` per path group the cartographers propose, with the map rows in scope.

Either way: write the map into `Map` and the hop-chain tables into `Traces` verbatim, advance `phase`, and show the user the map and the anomaly list. The map is the scope: a touchpoint discovered later means the map was wrong - update the map first.

Step 3 - Phase P: probe

Where the design depends on external/vendor behavior, verify it empirically **before** designing - yourself, in the main session (probes may need credentials or VPN the workers must not have). A path that cannot be produced gets a ready-to-run skipped test, never an assumption. Persist results in `Probes`.

Step 4 - Phase D: design gate (STOP)

Write the design in prose: the invariant being established, type/structure changes, the full touchpoint list with what changes at each, alternatives with a recommendation. Check it against `Why` before presenting: if the design no longer answers the stated problem, one of the two is wrong, and saying which is part of the presentation rather than something to quietly reconcile. Set `status: awaiting-approval`, present it, and stop with exactly: **1. Approve and continue / 2. Approve and stop (a fresh session resumes at Phase I from the file alone) / 3. Revise**. On approval record the design under `Design (approved)` inside a `<frozen-after-approval>` fence, log the decision, derive