gilde

← All craftbooks

Codebase Refactoring Review

Review and QAevalv1.0.0released 2026-06-05workflow: build-loop

Review an entire codebase for the least cogent, highest-leverage refactoring opportunities without changing source. Uses the repository map and per-file AI health index to rank weak areas, then verifies each lead in the real code and leaves a file-and-line-cited morning report with sequenced refactor plans, risk, effort, and tests that must protect behavior. Use for a weekly code-health sweep, refactoring review, technical-debt triage, finding code smells, or deciding which files should be refactored first.

Steps

Entry step: rank. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Rank weak areasreviewerentry

    use the repo map and per-file health index to build a coverage-aware candidate list

    Show working prompt
    Start with `map_repo` and record the indexed review coverage (reviewed/eligible), average health, major-issue count, and worst files. Call `list_file_issues` across the repo, then use `search_code` for cross-cutting duplication, oversized orchestration, unclear ownership, error handling, and tightly coupled state. If git history is available, use read-only `run_git` queries to add churn/fix-frequency evidence; missing history is not a failure. Rank candidate files or cohesive areas using explicit factors: low indexed health, confirmed major issues, too many responsibilities, coupling/fan-out, duplication, change frequency, test difficulty, and blast radius. Do not call an indexed lead a finding yet and do not modify source. Write the coverage statement, ranking method, and top candidates to `notes/refactoring/candidates.md`.
  2. Verify refactoring candidatesreviewer

    inspect candidate symbols, responsibilities, callers, and tests in real source

    Show working prompt
    Verify every shortlisted candidate in source. Call `file_review` for the indexed rationale, `outline_file` before reading a large file, `read_symbol` for the implicated units, and `find_references` to understand callers and blast radius. Locate tests with `search_code`/`search_files`. For each confirmed candidate record real file:line evidence, the current responsibilities, the specific cohesion/coupling/duplication/testability problem, why it matters, a bounded refactor seam, dependencies and migration order, behavior-preserving tests required first, effort, risk, and expected payoff. Reject false-positive index leads explicitly. Prefer a smaller ranked list of verified opportunities over a long smell inventory. Write the evidence matrix to `notes/refactoring/verified.md`; do not change code.
  3. Write the refactoring reportreviewer

    prioritized code-health report with safe, sequenced refactor plans

    Show working prompt
    Write `refactoring-review.md` for an admin to read in the morning. Use these exact sections: `## Executive summary`, `## Index coverage`, `## Ranked opportunities`, `## Cross-cutting themes`, `## Defer or leave alone`, and `## Recommended sequence`. Each ranked opportunity must cite real file:line evidence; state why the area is insufficiently cogent; name the proposed seam and steps; list behavior-preserving tests; and include impact, effort, risk, and dependencies. Separate systemic themes from individual files. State index gaps and unreviewed areas so a quiet report is not mistaken for a clean codebase. Do not include style-only churn or recommend rewrites without a migration boundary. On a loop-back, repair only the named report gaps.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Grade `refactoring-review.md`: (1) index coverage and limitations are explicit; (2) every ranked item was verified in source and cites a real file:line; (3) ranking uses impact, evidence, effort, risk, and blast radius rather than file size alone; (4) each recommendation names a bounded seam, sequence, and behavior-preserving tests; (5) systemic themes are distinguished from local smells; (6) false positives and areas to leave alone are recorded; (7) no source was changed and no vague rewrite advice remains. PASS every item or loop back with exact gaps.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Toolsets

Source

View this craftbook on GitHub · MIT license