Refactorlib Cc

Workflow

Phase 1 -- Route on context

The project context above was resolved at skill load time. Use it to decide which pattern catalogs each agent should read:

• If has_effect == "yes": include references/patterns/effect-infra.md in the infra agent's pattern list
• Always: include references/patterns/runtime-infra.md for infra agent, references/patterns/general-utility.md and references/patterns/runtime-utility.md for utility agent

The subagents have effect-usage and bun skills preloaded — no need to load companion skills in the orchestrator.

Phase 2 -- Parallel exploration

Spawn two custom subagents in parallel. Each receives a short task prompt with:

• Project dependencies (from deps above)
• Source directories (from src_dirs above)
• Pattern catalog file paths to read (from Phase 1 routing)
• Guardrails: ~/.claude/skills/refactorlib-cc/references/guardrails.md
• Report format: ~/.claude/skills/refactorlib-cc/references/report-format.md
• The user's request (or "Full audit -- no scope restriction")

Agent({ subagent_type: "refactorlib-infra", prompt: <task prompt> })
Agent({ subagent_type: "refactorlib-utility", prompt: <task prompt> })

The agents' system prompts (from their markdown definitions) provide the methodology. Their preloaded skills (effect-usage, bun) provide deep API knowledge with progressive disclosure.

Phase 3 -- Triage and deep-dive

Synthesize agent findings. For each candidate, classify:

For REPLACE and INVESTIGATE candidates, perform these verification steps:

1. Read the source -- understand the full implementation, not just the grep match
2. Count callers -- grep -r for imports to gauge blast radius
3. Verify the API exists -- grep type declarations in node_modules/*/dist/dts/ for the replacement API. An API that looks right in docs might not exist in the installed version.
4. Test output compatibility (for INVESTIGATE) -- run both implementations with identical input via bun -e and compare output. This catches subtle differences in encoding, formatting, or edge-case behavior.

Only promote INVESTIGATE to REPLACE after step 4 confirms identical behavior.

Phase 4 -- Structured output

Produce the final report using this template:

## Library Replacement Audit

### Dependencies scanned
- <dep>: <what it provides>

### Candidates

#### [REPLACE] <title>
- files: <paths with line ranges>
- callers: <N files import this>
- current: <what the code does, 1 line>
- replacement: <library API, 1 line>
- effort: low | medium | high
- gain: <lines removed, better edge-case handling, etc.>
- verified: yes | no
- code_before: |
    <snippet>
- code_after: |
    <snippet>

#### [INVESTIGATE] <title>
- files: <paths>
- current: <what the code does>
- candidate: <library API>
- blocker: <what needs verification>

#### [KEEP] <title>
- files: <paths>
- reason: <why this is intentionally custom>

### Summary
| Candidate | Verdict | Effort | Gain | Verified |
|-----------|---------|--------|------|----------|

False-positive guardrails

See references/guardrails.md. Agents are directed to read this file during exploration.

Reference navigation