Refine

refine

Charter-bound clean-up of a feature's changed code — Checkpoint 6. Modeled on Claude Code's stock /simplify (a three-subagent parallel review) with two layers the stock skill lacks: charter validation of every proposal, and graceful breaking changes.

The behavior contract (ACs + specs) is sacred — a refactor that breaks it is a category error. New shapes are introduced alongside old, never instead of.

When to use

Checkpoint 6, after atdd:atdd-team produces passing code, before crap-analyzer (Checkpoint 7).

Verification independence: if manifest.verification.apply_to_checkpoints includes 6, refine must run on a non-implementer agent. The three review subagents (Step 2) are fresh regardless, so independence is satisfied by construction.

Not for: changing behavior (feature-edit); risk analysis (crap-analyzer); code that isn't implemented/green yet.

Workflow

Step 0 — Entry gate. Before starting, verify the prior checkpoint is complete: run ${CLAUDE_PLUGIN_ROOT}/scripts/dae_handoff.py <feature-dir> --through 5. On a non-zero exit, stop and surface the gap to the human — do not proceed.

Verify branch hygiene: run ${CLAUDE_PLUGIN_ROOT}/scripts/dae_branch.py <feature-dir>. On a non-zero exit, stop and surface the message to the human — switch branches and re-invoke. The check honors the git.manual: true manifest opt-out.

After the gate passes, show the pipeline breadcrumb: run ${CLAUDE_PLUGIN_ROOT}/scripts/dae_progress.py <feature-dir> and present its output to the human — it shows where this checkpoint sits in the DAE pipeline. The breadcrumb is advisory: a non-zero exit or a missing progress.md never blocks the skill. Then create one TodoWrite todo per workflow step below. See ${CLAUDE_PLUGIN_ROOT}/references/progress-indicator.md.

1. Resolve + scope — resolve the methodology root + manifest via ${CLAUDE_PLUGIN_ROOT}/scripts/dae_resolve.py (see references/resolving.md); locate the feature. Scope = the feature branch's changed code (git diff against the branch point). Load feature.md, acs.md, spec.md, CHARTER.md.
2. Dispatch three parallel review subagents: three Agent-tool calls in one message, each subagent_type: engineer:reviewer (or the project override; see ${CLAUDE_PLUGIN_ROOT}/references/host-capabilities.md, "Role agents"), each over the same changed code and each with its lens named in the brief. The agent is read-only and caps its reply, so three results fit in context. Before dispatching, run ${CLAUDE_PLUGIN_ROOT}/scripts/dae_dup.py <methodology-root> to get deterministic project-wide duplicate findings; pass the JSON result into the Reuse subagent's context as a tool input (the subagent treats it as one signal alongside its own LLM judgment, and produces a unified set of findings — not a separate list). If dae_dup.py returns anything other than status: ok — status: unavailable (the backend tool isn't installed), status: skipped (manifest duplication.skip: true), status: unsupported (the configured backend isn't implemented in this version), or status: error (scan failed) — surface that status in the Reuse subagent's prompt and proceed with its existing LLM-only judgment.
   • Reuse — duplication (LLM + dae_dup.py findings), reinvented wheels, dead code, missed existing utilities. LSP-first lookup — at dispatch time, check whether an LSP MCP capability is available; pass that detection result and the LSP-first preference into the Reuse subagent's prompt so it uses find-references / workspace-symbols when available, with graceful fallback to grep + Read. See ${CLAUDE_PLUGIN_ROOT}/references/code-lookup.md.
   • Quality — clarity, structure, naming, incidental complexity, maintainability
   • Efficiency — redundant computation, repeated lookups, visible performance smells
3. Consolidate — merge findings; dedup overlaps (note multi-lens hits as strong signals); keep genuine conflicts as alternatives for the human.
4. Charter filter — check every proposal against CHARTER.md (architecture, conventions, methodology, the ACs+specs contract). Charter-violating proposals are rejected internally — never shown. This filter is the DAE-specific layer the stock skill lacks.
5. Classify breaking changes — consumer-facing (something outside the blast radius depends on the old shape) → graceful path: deprecation-marked forwarding shim + migration note, new shape alongside old. Internal-only → hard change is fine.
6. Present; human picks — show charter-compliant proposals (change, why, blast radius, churn). The human selects which are worth the churn.
7. Apply — apply selected; install graceful paths where needed; re-run both test streams. Before running the test streams, ensure required infra is up: read manifest.yml's infra: section, then call ${CLAUDE_PLUGIN_ROOT}/scripts/dae_infra.py ensure <names> for each declared dependency the tests need. On a start-failed structured failure → stop and surface the diagnosis. On a missing manifest declaration for required infra → stop with the "declare in manifest" message. Any failure → revert that proposal and report.
8. Handoff — emit a summary.