improve-codebase

name	improve-codebase
description	Run a deep autonomous quality sweep of the whole codebase or named subsystems: survey, split into reviewable chunks, run multi-lens reviews, fix findings iteratively, and delegate to cleanup/test skills as needed.

improve-codebase

This is the whole-repository audit and improvement orchestrator. It should run a systematic survey that:

• decomposes the codebase into reviewable chunks by module/package/subsystem
• audits each chunk with parallel multi-lens reviewers
• runs cross-cutting reviews (architecture, consistency, security)
• fixes accepted findings iteratively
• delegates to complementary skills where they add value
• populates ISSUES.md with anything deferred
• reports each chunk's findings and fixes to the human

Use this skill for deep, independent codebase-wide quality sweeps. Use audit-and-fix-uncommitted-changes instead when the target is working-tree diffs only.

Scope default

Default scope:

• the entire repository source tree
• all production code, tests, docs, and configuration
• excluding generated files, vendor directories, and build artifacts

The user can narrow scope with:

• explicit paths or directories
• file-type filters (e.g., "only Go files", "only tests")
• subsystem names
• specific audit lenses (e.g., "security only", "architecture only")

Inputs

Accept any combination of:

• explicit paths or subsystem names
• audit lens filters (all, correctness, architecture, security, quality, coverage)
• a chunk iteration cap
• a findings-per-chunk severity threshold for stopping early
• whether to run complementary skills (simplify-codebase, boost-coverage, fix-issues)
• whether to operate in report-only mode (no fixes)

Required artifacts

Use one shared run-id = YYYYMMDD-HHMMSS-<short-rand>.

Always create:

• .agent-layer/tmp/improve-codebase.<run-id>.report.md

Create the file with touch before writing.

The master report is the human-facing ledger and the single place to preserve orchestrator state.

Delegated skill outputs are handled one way:

• Use review-scope report artifacts as findings input to resolve-findings.
• Copy resolve-findings, simplify-codebase, boost-coverage, audit-tests, and fix-issues outcomes from their final handoffs into the master report.
• Do not require, open, echo, or cross-reference child report artifacts from resolve-findings, simplify-codebase, boost-coverage, audit-tests, or fix-issues.

Required behavior

At minimum, use:

• a survey scout that maps the repository structure
• parallel audit reviewers with different lenses per chunk
• a findings resolver/fixer
• a cross-cutting reviewer for architecture and consistency
• a synthesizer that maintains the master report

Prefer the dedicated skills that already exist:

• review-scope for per-chunk auditing
• resolve-findings for triaging and fixing findings
• simplify-codebase when complexity warrants it
• boost-coverage when test gaps are significant
• audit-tests when test suite quality, redundancy, or organization is concerning
• fix-issues when existing ISSUES.md entries overlap with findings

Global constraints

• Treat the codebase as the target, not working-tree diffs.
• Do not attempt to review every line of every file. Prioritize by risk, complexity, and staleness.
• Fix all accepted findings regardless of severity.
• Do not stage, commit, or discard changes unless the user explicitly asks.
• Keep each chunk review focused and reviewable.
• If a fix changes the relevant surface area materially, re-audit that chunk.
• Log deferred findings to ISSUES.md instead of silently dropping them.
• Do not weaken tests, lower thresholds, or skip checks to clear findings.

Human checkpoints

• Required: ask when the repository is too large to audit meaningfully in one session and the user has not scoped it down.
• Required: ask when an accepted finding requires a breaking change, broad architectural refactor, or user-visible behavior change.
• Required: ask when a finding cannot be verified with available code, tests, or docs.
• Required: ask before any destructive or irreversible action.
• When a checkpoint involves a genuine tradeoff between substantive alternatives, present at least two options with brief pros and cons, state which you recommend and why, and let the human decide.
• Stay autonomous during normal survey, audit, fix, and re-audit cycles when findings and fixes are clear.

Orchestration loop

Phase 0: Preflight (Repo scout)

1. Confirm baseline with:
   • git status --porcelain
   • git diff --stat
2. Read in this order when they exist:
   • COMMANDS.md
   • README.md
   • DECISIONS.md
   • ISSUES.md
   • ROADMAP.md
3. Identify the repository structure:
   • top-level directories and their purposes
   • language(s) and framework(s) in use
   • test locations and conventions
   • generated or vendored paths to exclude
4. Note existing known issues from ISSUES.md to avoid reporting them as novel findings.

Phase 1: Survey and decompose (Survey scout)

1. Map the repository into reviewable chunks by:
   • package, module, or directory boundaries
   • functional subsystem (e.g., "config loading", "sync engine", "CLI commands")
   • test suites as their own review targets when relevant
2. Prioritize chunks by:
   • complexity signals (file size, function count, nesting depth)
   • recent change frequency (git log --since="3 months ago" --name-only)
   • test coverage gaps when coverage data is available
   • presence of TODO/FIXME/HACK markers
   • proximity to data boundaries, security surfaces, or reliability-critical paths
3. State the chunk list, priority order, and rationale in the master report.
4. If the total scope is clearly too large for one session, propose the highest-value subset and ask before proceeding.

Phase 2: Audit chunk N (Audit reviewers)

Use the review-scope skill on the current chunk with proactive hotspot mode.

The review-scope lenses cover correctness, architecture, and quality. For this orchestrator, also assess:

• Security: input validation gaps, injection risks, credential handling
• Consistency: naming conventions, error patterns, style drift across the codebase

Copy the high-signal findings summary into the master report under ## Chunk N: <name> Findings.

Phase 3: Fix chunk N findings and re-audit (Fixers + Auditors)

Use the resolve-findings skill on the chunk N review report.

Fix every accepted finding regardless of severity. For findings that cannot be fixed in scope:

• log them to ISSUES.md with the severity, location, and next step
• mark them as deferred in the master report

Copy the fix summary into the master report under ## Chunk N: <name> Fixes.

If a fix exposes obvious local complexity:

• use the simplify-codebase skill on the affected area

After fixes are applied, run one explicit re-audit pass on the chunk using a fresh-context reviewer subagent, not a continuation of the fixer's context. The fixer just rationalized each change as correct; re-grading from the same context inherits that bias and produces sunk-cost "we just fixed that" agreement. The fresh-context reviewer sees only the post-fix chunk and the originating findings, never the fix narrative.

Pass the contents of reviewer-prompt.md to the reviewer subagent verbatim — do not paraphrase, summarize, or modify the rubric.

Inputs the reviewer receives alongside the prompt:

• The post-fix content of every file in the chunk.
• The originating findings list (titles, severities, locations only).
• Nothing else. No fixer narrative, no resolve-findings report, no chat history, no "we decided to ___" rationalizations.

Loop rules:

• If the fresh-context re-audit returns new Critical or High findings, fix them and re-invoke the reviewer (fresh context again, fresh inputs each time).
• Stop the per-chunk loop when the fresh-context re-audit returns no Critical or High findings.
• If the loop does not converge after 3 iterations, escalate to the user.

Phase 4: Cross-cutting review (Architecture reviewer)

After all chunks have been individually audited, run a cross-cutting review covering:

• Architectural consistency: do modules respect their boundaries? Are there layering violations?
• Pattern consistency: are similar problems solved differently in different places?
• Error handling patterns: consistent approach across the codebase?
• Naming and convention drift: inconsistencies that accumulated over time?
• Dependency health: outdated, duplicated, or unnecessary dependencies?
• Documentation alignment: do README, memory files, and inline docs match the actual code?

Record cross-cutting findings in the master report under ## Cross-Cutting Findings.

Fix accepted cross-cutting findings using the same resolve-findings workflow.

Phase 5: Complementary skill delegation (Orchestrator)

Delegate to complementary skills only when the audit surfaces systemic issues in their domain: boost-coverage for significant test gaps, audit-tests for widespread redundancy/misclassification, simplify-codebase for significant complexity, fix-issues for overlapping ISSUES.md entries. Skip delegation when no meaningful gaps exist.

Record delegation outcomes in the master report under ## Complementary Skill Results.

Phase 6: Close the run (Reporter)

When all chunks and cross-cutting reviews are complete:

1. Add ## Final Summary to the master report
2. Summarize:
   • chunks audited and their status
   • total findings by severity
   • findings fixed vs. deferred
   • complementary skills invoked and their outcomes
   • overall codebase health assessment
3. Add ## Residual Risk for any systemic concerns that remain

Required master report structure

Write .agent-layer/tmp/improve-codebase.<run-id>.report.md with:

1. # Codebase Improvement Summary
2. ## Repository Overview
3. ## Chunk Map and Priority Order
4. For each chunk:
   • ## Chunk N: <name> Findings
   • ## Chunk N: <name> Fixes
5. ## Cross-Cutting Findings
6. ## Cross-Cutting Fixes
7. ## Complementary Skill Results
8. ## Final Summary
9. ## Residual Risk

Minimal status protocol

At each major stage, echo the master report path, identify the current chunk, and state one of:

• preflighting the repository
• surveying and decomposing
• auditing chunk N:
• fixing chunk N findings
• running cross-cutting review
• delegating to
• closing the run

Guardrails

• Do not attempt to review every line. Prioritize by risk.
• Do not silently skip chunks that were in the plan.
• Do not carry unresolved deferred findings without logging them to ISSUES.md.
• Do not expand a chunk review into unrelated areas.
• Do not treat the cross-cutting review as optional.
• Do not claim a clean codebase without evidence from the audit rounds.
• Do not modify unrelated code just because it is nearby.
• Keep each chunk review grounded in concrete reviewed code, review-scope findings, and observed verification.

Definition of done

• The master report exists at .agent-layer/tmp/improve-codebase.<run-id>.report.md with every required section, including one ## Chunk N: <name> Findings + ## Chunk N: <name> Fixes pair per chunk in the plan and a populated ## Cross-Cutting Findings section.
• Every chunk in the planned chunk map was audited (no silent skips); per-chunk re-audit loops used a fresh-context reviewer subagent (not the fixer's context) and ended with no new Critical or High findings or with an explicit 3-iteration escalation recorded.
• Every deferred finding has a matching entry in ISSUES.md cited by the master report.
• The ## Final Summary states overall codebase health with evidence, and ## Residual Risk names any systemic concerns that remain.

Final handoff

After the run, present the results to the user in chat:

1. Echo the master report path.
2. State total chunks audited, total findings, and fixes applied.
3. Present a Key findings and fixes table sorted by Chunk (primary) then Severity (secondary).
4. Below the table, list deferred findings with their ISSUES.md entry references.
5. State the overall codebase health assessment.
6. List any complementary skills that were invoked and their outcomes.