Add refactor-scout agent — read-only technical-debt surveyor for source code

The janitor's source-code sibling: surveys existing code (not a diff) for smells,
dead code, duplication, and over-complexity, prioritizes by churn × complexity, and
recommends a disposition (refactor/delete/defer/accept) per finding designed to feed
/triage. Test-net status and risk-to-change are first-class so a refactor is only
recommended when behavior preservation can be proven. Read-only; the risky auto-apply
half is deliberately deferred and gated. ROADMAP item 11.
This commit is contained in:
Keysat
2026-06-19 22:57:32 -05:00
parent 4533cc1d85
commit f258f9fd3c
4 changed files with 245 additions and 9 deletions
+19 -9
View File
@@ -20,8 +20,8 @@ file added under `adapters/` is live immediately — no per-file linking:
`/handoff`, `/full-eval`, `/capture`, `/triage`, `/roundup`, `/new-project`, `/design`,
`/adjudicate`).
- `~/.claude/agents``adapters/claude/agents/` — global subagents (reviewer, evaluator,
security-auditor, doc-auditor, exerciser, researcher, janitor, portability-checker,
start9-spec-checker, design-checker, onboarding-tester).
security-auditor, doc-auditor, exerciser, researcher, janitor, refactor-scout,
portability-checker, start9-spec-checker, design-checker, onboarding-tester).
- `~/.claude/CLAUDE.md``how-i-work.md` — my universal preferences, loaded every session.
(Distinct from this repo's *root* `CLAUDE.md`, which → `AGENTS.md`: same filename, different
scopes — global preferences vs. this repo's orientation.)
@@ -89,9 +89,18 @@ should carry this so any vendor's agent surfaces pending items at session start:
## Current state
- **Fleet built and live** — commands `/capture /triage /roundup /new-project /handoff /retrofit
/full-eval /design /adjudicate`; subagents incl. `design-checker` + `onboarding-tester`
(substance in `guides/`, thin wrappers in `adapters/claude/`, symlinked into `~/.claude`).
Dogfoods its own standard. Latest `/roundup`: `STATUS.md` 2026-06-16.
/full-eval /design /adjudicate`; subagents incl. `design-checker`, `onboarding-tester` +
`refactor-scout` (substance in `guides/`, thin wrappers in `adapters/claude/`, symlinked into
`~/.claude`). Dogfoods its own standard. Latest `/roundup`: `STATUS.md` 2026-06-16.
- **`refactor-scout` shipped this session (ROADMAP item 11).** The janitor's source-code
sibling: read-only technical-debt surveyor that finds code smells, dead code, duplication, and
over-complexity in *existing* code (not a diff), prioritizes by churn × complexity, leans on the
repo's own analyzers, and recommends a **disposition** per finding (refactor / delete / defer /
accept) designed to feed `/triage`. Test-net status + risk-to-change are first-class so a refactor
is only ever recommended when behavior preservation can be proven. **Untested on a real repo** —
the first run should sanity-check that it stays opinionated/tiered (≤~12 findings, not a dump) and
honest about test coverage. The risky auto-apply half is deliberately **not built** (deferred +
gated — see item 11). Good first targets: recap, keysat.
- **`/adjudicate` shipped this session (ROADMAP item 10).** Debates parked P2/P3 backlog to
DROP/DO/ESCALATE verdicts; recommend-only v1, autonomy gated by blast radius, ROADMAP-only.
**Untested on a real backlog** — the first run should eyeball the judge's drop-bias before
@@ -107,10 +116,11 @@ should carry this so any vendor's agent surfaces pending items at session start:
notes promoted to `guides/design.md` (`176eebe`). The "confirm export internals + tune Phase-C"
open item is **closed**. Residual is per-project execution (ten31-database mobile build, being
scoped in that repo — not standards work).
- **Next steps:** (1) first real `/adjudicate` run on keysat/recap to calibrate the drop-bias
(item 10); (2) Stage-1 `onboarding-tester` harness in a keysat session (item 9); (3) cross-repo
quality-gate standard + `/harden` (item 1); (4) non-git-folder sweep under `~/Projects` (item 6
residual).
- **Next steps:** (1) first real `refactor-scout` run on recap/keysat to calibrate the tiering +
test-net honesty (item 11); (2) first real `/adjudicate` run on keysat/recap to calibrate the
drop-bias (item 10); (3) Stage-1 `onboarding-tester` harness in a keysat session (item 9);
(4) cross-repo quality-gate standard + `/harden` (item 1); (5) non-git-folder sweep under
`~/Projects` (item 6 residual).
- Queued in `INBOX.md` for other repos' `/triage`: keysat design cleanup (P2) + onboarding Path-2
(P3); `ten31-transcripts` mini-retrofit; `ten31-database` networking/icon/intake; (standards)
operator-onboarding agent (P3).