simplify-codebase

name	simplify-codebase
description	Codebase-wide complexity reduction: remove dead code, simplify overly complex functions, and split files with mixed responsibilities across explicit paths or the whole repo. Use `simplify-new-code` instead when the target is the current uncommitted diff.

simplify-codebase

This is a complexity-reduction workflow, not a redesign workflow. Default behavior is:

• assess complexity using measurable signals, then apply judgment
• keep changes behavior-preserving
• verify with repo-defined checks before stopping

Philosophy

Complexity metrics (cyclomatic complexity, function length, nesting depth, file size) are diagnostic signals, not pass/fail gates. A 1000-line file with one clear responsibility may be the right solution. A 30-line function with deeply nested conditionals may not be.

The question is always: would simplification actually improve this code for a reader and maintainer? Use the metrics to find candidates, then decide with judgment informed by:

• the language and its idioms
• the domain and its inherent complexity
• whether the code mixes unrelated responsibilities
• whether a reader can hold the logic in their head
• whether the current structure makes bugs easy to introduce or hide

Do not simplify code that is already clear. Do not add complexity in the name of reducing a metric.

Scope default

• Default scope is the full codebase (the repository source tree, excluding generated files, vendor directories, and build artifacts).
• The user can narrow scope with explicit paths, directories, or file-type filters.
• Use simplify-new-code instead when the target is the current uncommitted diff — that skill is the diff-scoped sibling. This skill never operates on the diff alone.

Focus effort on the worst offenders rather than exhaustively rewriting everything. Identify, prioritize, and fix the highest-value simplifications first.

Defaults

• Default file-size target for splits is a judgment call, not a fixed number. Consider the language, the file's role, and whether the current size hurts navigability or understanding.
• Attempt dead-code removal first with trustworthy existing tooling; otherwise decide whether a credible tool proposal or agent-led evidence is the better fit.
• Prefer no-op on speculative simplification over risky "improvements."

Inputs

Accept any combination of:

• explicit paths or directories
• file-type filters
• whether to attempt dead-code removal
• a maximum number of file splits
• whether to run in assessment-only mode (report without fixing)

Required artifact

Write the report to:

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

Use run-id = YYYYMMDD-HHMMSS-<short-rand>. Create the file with touch before writing.

Multi-agent pattern

Recommended roles:

1. Repo scout: finds commands, target files, and verification lanes.
2. Complexity analyst: measures and identifies simplification candidates.
3. Dead-code analyst: identifies safe removals with evidence.
4. Simplifier: performs function-level and local simplifications.
5. Splitter: plans and performs safe file splits.
6. Verifier: runs the fastest credible checks.

Global constraints

• Never change behavior, public contracts, or intended control flow.
• Do not install new tooling without a credible proposal and human approval.
• Do not broaden scope with opportunistic refactors.
• Keep file splits logical and substantial rather than exploding files into fragments.
• Do not simplify code just because a metric is high; simplify when the complexity genuinely hurts readability, maintainability, or correctness risk.

Human checkpoints

• Required: ask when "dead code" evidence is ambiguous or external references cannot be ruled out.
• Required: ask when no credible verification path exists for a non-trivial change.
• Required: ask when a simplification would change the public API surface or require callers to adapt.
• 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 for clear simplifications and straightforward verification.

Simplification workflow

Phase 0: Preflight (Repo scout)

1. Confirm baseline with git status --porcelain and git diff --stat.
2. Read COMMANDS.md before selecting verification commands.
3. Determine the actual target scope: the full codebase by default, or the explicit paths/file-type filters the user supplied. Do not implicitly narrow to uncommitted changes — that is simplify-new-code's job.
4. Identify the language(s) and any available complexity tooling in the project.

Phase 1: Assess complexity (Complexity analyst)

Gather complexity signals across the target scope:

• cyclomatic complexity per function (when tooling is available or estimable)
• function length and nesting depth
• file size and responsibility count
• number of parameters, return paths, and branch density
• any language-specific complexity indicators

For each signal, identify candidates that stand out relative to their peers in the codebase — not against an arbitrary threshold.

Large file review (mandatory): Identify every file in the target scope that is notably large relative to its peers or the project norm. For each large file, make an explicit decision:

• keep: the file has one clear responsibility and splitting would fragment understanding — state why
• split: the file mixes unrelated responsibilities or has clear structural boundaries that would improve navigability — plan the split

Record every large-file decision in the report, including files you decide to keep. The goal is evidence that each large file was reviewed, not that every large file was split.

Produce a prioritized list of simplification candidates, ordered by the expected value of simplifying (how much clarity the change would add vs. the risk and effort involved).

Phase 2: Remove clearly dead code (Dead-code analyst)

Remove only when at least one of these is true:

• trusted dead-code tooling marks it unreachable
• local repo search shows no live references and the symbol is clearly private
• the code is obviously unused scaffolding in the current scope

If evidence is mixed, escalate instead of guessing.

When tooling is not available or not appropriate, use the strongest manual evidence available:

• repo-wide reference search
• private symbol boundaries
• registration/reflection checks
• test coverage and entrypoint reachability
• roadmap or issue context showing the code path is obsolete

Phase 3: Simplify flagged functions and code (Simplifier)

For each candidate from Phase 1, apply the simplification that best fits:

• reduce nesting by inverting conditions or using early returns
• extract a meaningful helper when a block has a clear single responsibility that the parent function should not own
• replace complex conditional chains with clearer structure
• flatten obvious local indirection
• clarify misleading names without semantic change
• remove stale comments that no longer describe the code
• tighten boundary validation when it is already implied by existing behavior

Do not:

• extract helpers for one-time operations just to shorten a function
• rename things for style preference alone
• add abstraction layers that increase the total amount of code to understand
• break apart a function that reads clearly as a linear sequence

Phase 4: Split oversized files (Splitter)

For files marked split in Phase 1:

• split by responsibility, not by arbitrary line count
• ensure the result remains easy to navigate and understand
• keep splits logical and substantial — two cohesive files, not ten fragments
• update imports and references in the same pass

Do not split when:

• the file has one clear responsibility regardless of length
• the resulting layout would be harder to understand than the current one
• the split would create circular dependencies or awkward coupling

Phase 5: Verify and re-assess (Verifier)

1. Run the fastest credible repo-defined checks.
2. Re-assess the target scope to confirm complexity was reduced where intended.
3. Stop and report if verification fails or no credible verification exists.

Required report structure

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

1. # Simplification Summary
2. ## Scope
3. ## Complexity Assessment
   • key metrics gathered
   • candidates identified and their ranking rationale
4. ## Large File Decisions
   • every large file reviewed, with verdict (keep/split) and reasoning
5. ## Dead Code Removed
6. ## Simplifications Applied
7. ## File Splits
8. ## Verification
9. ## Deferred Opportunities

Guardrails

• Do not use simplification as cover for feature work or architecture changes.
• Do not rewrite stable code just because it looks old or a metric is high.
• Do not split files when the new layout is harder to understand than the old one.
• Do not delete code whose liveness depends on reflection, registration, or external contracts unless the evidence is explicit.
• Do not simplify code that is already clear just to improve a number.
• Do not add abstraction to reduce line count.

Definition of done

• The report exists at .agent-layer/tmp/simplify-codebase.<run-id>.report.md with every required section (Summary, Scope, Complexity Assessment, Large File Decisions, Dead Code Removed, Simplifications Applied, File Splits, Verification, Deferred Opportunities).
• Every large file in scope has an explicit keep or split verdict with reasoning in Large File Decisions — none silently omitted.
• Every applied change is behavior-preserving, no public contract changed without an approved checkpoint, and the fastest credible repo-defined checks ran with observed output cited in Verification.
• Any "dead" code removal either has trusted-tooling evidence or the manual evidence is recorded in the report.

Final handoff

After writing the report:

1. Echo the report path.
2. Summarize: complexity candidates found, dead code removed, simplifications applied, and file splits performed.
3. Call out large-file decisions, verification commands run, and any simplification opportunities deliberately deferred.