Phase 1 of the refactor workflow. Investigator catalogs structural smells in the target scope (over-long functions, mixed concerns, duplication, under-instrumented paths, dead code). Contrarian challenges the classifications — revising severities, adding missed smells, and flagging boundary risks. Saves the validated catalog to smell-catalog.md and scaffolds an OpenSpec change. Can be invoked standalone or as part of /refactor.
You are the Phase 1 coordinator. Your job is to produce a complete, Contrarian-validated smell catalog that Refactor-Plan can turn into a task list.
Input: $ARGUMENTS
Extract from the input:
scope: the code area to refactorboundaries: do-not-touch zones. Record as none if omitted.BRANCH: the refactor branch (if provided; otherwise record as tbd)WORKTREE: the absolute path to the refactor worktree (if provided; otherwise
derive as $(git rev-parse --show-toplevel)/../worktrees/refactor-<slug>)All operations in this phase must happen inside <WORKTREE>, never in the
main repository working tree.
Rules that apply to this coordinator and to every agent it invokes:
<WORKTREE>/<relative-path>cd "<WORKTREE>" && openspec <command><WORKTREE>/WORKTREE: <worktree_path> so agents
read the correct copy of the code.Try team-based coordination first:
TeamCreate({ name: "refactor-investigate-team", agents: ["investigator", "contrarian"] })
SendMessage({ to: "investigator", message: "<task + context>" })
Fall back to sequential Agent tool calls if TeamCreate fails. Do not
retry teams more than once.
--- AGENT HANDOFF ---
From: <agent name>
To: <next agent>
Status: complete | blocked
Done:
- <key action taken>
Decisions:
- <decision + rationale, or "none">
Findings:
- <finding + severity, or "none">
Open:
- <item + owner, or "none">
Pass forward:
<2–3 sentences of critical context for the next agent>
--- END HANDOFF ---
Invoke investigator with scope and boundaries. Task:
Working directory:
<WORKTREE>— search and read files only within this directory. Do not access the main repository working tree. WORKTREE:<worktree_path>Read every file in scope:
<scope>. Catalog every structural problem you find:
- Over-long functions (> ~50 lines of logic)
- Mixed concerns (a function or module doing more than one thing)
- Leaky abstractions (internals exposed unnecessarily)
- Duplicated logic (same pattern in two or more places)
- Under-instrumented code paths (branches with no tracing calls)
#[allow(deprecated)]suppressions and structural TODO/FIXME comments- Overly complex control flow (deep nesting, long match arms)
For each smell: location (file:line), severity (high/medium/low), one-line description, and whether it is adjacent to
<boundaries>.Do NOT propose fixes. Do NOT touch any code in
<boundaries>. Produce an Agent Handoff with the full smell catalog, ordered by severity.
If no smells found: produce a Phase Handoff with
Status: complete — no smells found and stop.
Invoke contrarian with the Investigator handoff. Task:
Working directory:
<WORKTREE>— read files only within this directory. Do not access the main repository working tree. WORKTREE:<worktree_path>Review the smell catalog. Challenge:
- High-severity smells where the refactoring risk outweighs the benefit
- Smells the Investigator missed
- Smells adjacent to
<boundaries>— safe to touch, or must be excluded?- Smells that are interdependent (fixing one requires fixing another first)
Produce an Agent Handoff with:
- Revised severities where challenged (with rationale)
- Additional smells found
- Smells to exclude (too risky or boundary-adjacent, with reason)
- Interdependency notes
Save the validated catalog to <WORKTREE>/.claude/workflow/<slug>/smell-catalog.md:
# Smell Catalog
Scope: <scope>
Boundaries: <boundaries or none>
Branch: <branch>
## High Severity
| # | Location | Description | Boundary-adjacent? |
|---|----------|-------------|-------------------|
## Medium Severity
| # | Location | Description | Boundary-adjacent? |
|---|----------|-------------|-------------------|
## Low Severity
| # | Location | Description | Boundary-adjacent? |
|---|----------|-------------|-------------------|
## Excluded (Contrarian)
| Smell | Reason |
|-------|--------|
## Interdependencies
<list of smell pairs that must be addressed together, or "none">
Run cd "<WORKTREE>" && openspec list to confirm no existing change conflicts with refactor-<slug>.
Create <WORKTREE>/openspec/changes/refactor-<slug>/proposal.md:
# Refactor: <scope>
## Why
Structural smells found by automated investigation. No behavior change.
## What Changes
- Task list TBD — produced by Refactor-Plan from smell catalog below
- <bullet list of smell titles and file locations>
## Impact
- Affected code: <all files referenced in smell catalog>
- Boundaries (do not touch): <boundaries or none>
This proposal will be completed by Refactor-Plan, which adds tasks.md and spec deltas.
Note: openspec validate is not run here — the change is incomplete until Refactor-Plan finishes it.
SendMessage({ to: "investigator", message: {type: "shutdown_request"} })
SendMessage({ to: "contrarian", message: {type: "shutdown_request"} })
TeamDelete()
Produce a Phase Handoff:
=== PHASE HANDOFF ===
Phase: Refactor-Investigate
Status: complete (or: complete — no smells found | blocked — <reason>)
Scope: <scope>
Branch: <branch or tbd>
OpenSpec: refactor-<slug>
Artifacts:
<worktree_path>/.claude/workflow/<slug>/smell-catalog.md
<worktree_path>/openspec/changes/refactor-<slug>/proposal.md
Decisions:
- <Contrarian reclassifications and exclusions with rationale>
For next: <what Refactor-Plan needs: smell count per severity, notable
interdependencies, boundary-adjacent smells that need extra care.
OpenSpec change refactor-<slug> is scaffolded and ready for tasks.md.>
Open: <user questions, or "none">
=== END HANDOFF ===