refactor

UTILITY SKILL — structural refactor survey and apply, not feature work.

Input

• Interactive (required): paths/symbols and optional mode — constraints in ## Constraints or category-scope.md
• Automation (optional): detect JSON with hints[] in prompt — from a caller or optional skill detect script; not required for interactive runs. Read agent_edit_allowed and agent_edit_target from ## Constraints per category-automation-envelope.md

Path allowlist, when present, arrives in ## Constraints.

Output Specification

Refactor report per common-output-format.md. Survey shape when no files are edited; apply shape when edited — within category-scope.md. Automation path: common-output-format-automation.md and category-automation-envelope.md.

Execution Scope

USE FOR:

• Survey structural candidates; dedupe, extract/inline, clarify, shallow moves; automation hints; architecture Phase A/B; characterization tests

DO NOT USE FOR:

• Lint/style-only; features/API/behavior fixes; cross-boundary apply; platform-wide architecture refactors; external debt-survey apply input

Reference Files Guide

• common-checklist.md (always read)
• common-output-format.md (always read)
• category-scope.md (always read)
• category-contract.md (always read)
• category-detect-scope.md (read on interactive path)
• category-verification.md (read when agent_edit_allowed is true)
• category-techniques.md (read when agent_edit_allowed is true)
• category-input-schema.md (read when structured mode JSON, automation detect JSON, or the optional detect script is run)
• category-automation-envelope.md (read on automation path)
• common-output-format-automation.md (read on automation path)
• common-troubleshooting.md (read on failure)
• category-pr-body-links.md (read when synthesizing the PR body)
• assets/pr-body-template.md and assets/pr-body-template-survey.md (read when synthesizing the PR body)

Workflow

Phases, modes, depth tiers, and intent: category-contract.md. Self-check gates: common-checklist.md.

Canonical sequence: resolve agent_edit_allowed → Phase A (discover/classify; emit only when stopping) → Phase B only when edit-authorized → emit one result shape (OUT-01).

Resolve agent_edit_allowed before Phase B. When structured JSON mode is present (category-input-schema.md), it wins over the interactive rows: survey → false; apply → true. Otherwise use the table. An imperative with a target ("refactor scripts/a.sh", "deduplicate these helpers") asks for changes; "use refactor on X" or "what could be refactored in X" only names the skill or asks to look, so it stays survey.

When intent is unclear, survey and offer to apply — edits are harder to undo than a report.

When agent_edit_allowed is true, resolve agent_edit_target: interactive → fix; automation → from ## Constraints. Do not branch on other caller metadata. Before Phase B, load category-techniques.md.

Phase B runs only when agent_edit_allowed is true and agent_edit_target is fix. Architecture without approved_slice never enters Phase B (INTENT-02).

Phase A — Survey (always)

Discover and classify only. Emit a final report from Phase A only when this run will not enter Phase B (see Interactive / Automation paths).

1. Resolve scope (category-scope.md); parse structured/detect JSON when present (category-input-schema.md).
2. Classify intent (category-contract.md).
3. Architecture without approved_slice: emit survey shape with ### Architecture Proposal only; stop (INTENT-02). Do not treat as zero-actionable no-op.
4. Discover candidates (SURVEY-01): structural → all in-scope; architecture Phase B → only the approved_slice. Read targets before classifying (SURVEY-03); route apply-worthy → Candidates, else → Watch (SURVEY-02).
5. Structural zero actionable → emit survey no-op per common-output-format.md (Overview explains no-op); stop.

Phase B — Apply (agent_edit_allowed: true and agent_edit_target: fix)

1. For each apply candidate: one technique (category-techniques.md); gate (category-verification.md); on failure revert → Deferred; continue (APPLY-01).
2. Re-run gates on touched areas; emit apply shape; reconcile with git diff --name-only (OUT-01).

Automation path (hints[] in detect JSON)

1. Parse detect JSON; read agent_edit_allowed / agent_edit_target from ## Constraints.
2. Empty/skip → emit survey no-op per common-output-format.md (Overview explains no-op) + Session Metrics; stop.
3. Phase A on all hints[] (structural only — no architecture Phase A/B).
4. agent_edit_allowed: false or agent_edit_target ≠ fix → emit survey shape + Session Metrics (note expected agent_edit_target: fix when mismatched); no Phase B.
5. Else → Phase B; emit apply shape + Session Metrics (category-automation-envelope.md).

Interactive path

1. Resolve agent_edit_allowed (table above). Load category-detect-scope.md.
2. Resolve universe from the prompt (default = REFACTOR_SCAN_GLOBS / skill defaults). If the user named paths/globs, narrow the universe before detect.
3. If detect JSON is absent, run scripts/detect_refactor.sh with the resolved scope (default --scope all; set REFACTOR_SCAN_GLOBS for a temporary universe). On non-zero exit or status: "error", read stdout and stop.
4. Phase A: classify every hints[] entry and Agent-complement structural candidates (read targets — SURVEY-03). Architecture without approved_slice stops inside Phase A step 3.
5. Empty detect alone is not a no-op if complement found apply-worthy or watch-worthy work.
6. agent_edit_allowed: false or agent_edit_target ≠ fix → emit survey shape; stop.
7. Else → Phase B; emit apply shape.

Error Handling

Examples

• Prompt: Survey structural refactor candidates in this package
• Result: Survey report per references/common-output-format.md; apply only when agent_edit_allowed is true, agent_edit_target is fix, and candidates are marked apply.