Better Codebase

Improve the codebase as one system

Preserve intended behavior, find root causes instead of isolated smells, and prefer the smallest safe change with the highest maintainability impact.

Own orchestration only. Let each specialized skill own its domain rules:

| Skill | Ownership | | --- | --- | | better-architecture | Boundaries, dependency direction, coupling, cohesion, and system structure | | better-simplicity | Unnecessary complexity and the simplicity review of every proposed change | | better-duplication | Repeated knowledge and unsafe or missing abstractions | | better-maintainability | Local clarity, control flow, side effects, naming, and changeability | | better-dependencies | Dependency necessity, health, compatibility, and upgrade risk | | better-testing | Behavioral protection, test design, confidence, and testability | | better-performance | Measured bottlenecks and established complexity problems |

Never duplicate or override domain rules here.

Resolve the request

Resolve three independent inputs: depth, action, and scope. State all three in the result.

Depth

| Depth | Coverage | Finding cap | | --- | --- | --- | | quick | Default. Inspect the requested scope or a risk-weighted complete slice. Report only high- and medium-impact findings. | 7 | | full | Inspect the entire credible scope across every available owner, including tests, manifests, boundaries, and runtime evidence when relevant. | 20 |

Never claim repository-wide coverage from a sample. If a full review is too large, narrow it to a complete subsystem or end-to-end path and name the boundary.

Action

| Action | Behavior | | --- | --- | | review | Default. Remain read-only and return evidence-backed findings. | | plan | Remain read-only and turn confirmed findings into ordered, reversible steps. | | implement | Modify only explicitly selected findings or a scope the user clearly approved, then verify each step. |

Treat a bare implement with no prior report, finding IDs, or explicit change scope as review + plan. Do not choose an unbounded refactor on the user's behalf.

Examples:

$better-codebase
$better-codebase full src/
$better-codebase plan findings 1, 3, and 4
$better-codebase implement findings 1 and 3

Review workflow

1. Recon before judgment

Identify:

• repository instructions and dirty-worktree state;
• languages, frameworks, build systems, and supported runtime versions;
• entry points, module boundaries, public APIs, storage and network boundaries;
• test, lint, type-check, build, benchmark, and dependency-audit commands;
• manifests, lockfiles, generated code, vendored code, and migration constraints;
• the requested scope and any surfaces that will not be inspected.

Follow established repository conventions unless a convention is itself the evidenced problem.

2. Establish the baseline

Run safe, relevant checks already available in the project. Record the exact command and observed result. Distinguish pre-existing failures from failures caused by later implementation.

Do not change configuration merely to make a check pass. If no trustworthy test exists for behavior that will be refactored, ask better-testing to define the smallest characterization test before implementation.

3. Apply every available owner

Confirm that all seven owner skills are available. Load and apply every available owner, but spend depth only where evidence exists in quick mode.

Use this order:

1. better-testing — establish behavioral protection and verification gaps.
2. better-architecture — inspect system boundaries and dependency direction.
3. better-maintainability — inspect local changeability and control flow.
4. better-duplication — distinguish repeated knowledge from harmless similarity.
5. better-dependencies — inspect necessity, health, and migration risk.
6. better-performance — inspect only measured symptoms or established complexity issues.
7. better-simplicity — review existing complexity and challenge every proposed change.

When an owner is unavailable, mark its domain Not reviewed and continue. Do not reconstruct its rules from memory or claim holistic coverage.

When invoked through this orchestrator, apply each owner's principles but ignore its standalone output format. This skill owns consolidation and final output.

4. Enforce the evidence gate

Read [references/evidence-model.md](references/evidence-model.md) before consolidating findings.

Require every finding to include:

• a root cause rather than a smell label;
• exact path/to/file:line evidence and the current implementation;
• an observable or credible engineering impact;
• the smallest safe change;
• impact, reach, confidence, and change risk;
• a verification method.

Treat a metric, linter warning, complexity score, outdated version, long function, or duplicated block as a lead—not a finding by itself. Exclude subjective taste.

5. Consolidate and rank

Report one finding per root cause. List all confirmed locations under that finding instead of repeating the same issue. Assign ownership to the skill that owns the underlying rule and mention cross-domain effects in the explanation.

Rank by impact first, then reach, confidence, remediation leverage, and change risk. A shared dependency hub can outrank a more dramatic but isolated smell.

Do not pad the report to reach the finding cap. No findings is a valid result.

6. Make restraint visible

Record real candidates that were inspected and deliberately rejected because:

• the evidence was insufficient;
• the code represents different concepts that may evolve independently;
• the existing abstraction protects a real boundary;
• the proposal would add more indirection than value;
• the migration cost exceeds the verified benefit;
• the current implementation is consistent with project constraints.

Never invent rejected candidates as filler.

7. Plan or implement safely

For plan, order changes so each step is independently reviewable and verifiable. Separate behavior changes from refactoring.

For implement, read [references/safe-implementation.md](references/safe-implementation.md) and follow it. Preserve public APIs, persisted data, wire formats, and intended observable behavior unless the user explicitly approves a change.

Do not rewrite the project when a local correction is sufficient. Do not combine unrelated modernization, cleanup, formatting, and behavior changes.

8. Verify the outcome

Re-run the baseline and the narrowest relevant checks after every material implementation step. Add focused tests only when they protect behavior or reproduce the finding.

Report what passed, what failed, and what remains unverified. A verification gap is not proof that the code is defective.

Consolidated output

Use the following sections in order.

Scope and baseline

State depth, action, exact scope, stack, relevant conventions, baseline commands, and review boundaries.

Coverage

| Domain | Evidence inspected | Result | | --- | --- | --- | | Testing | Files, commands, behavior, or gaps inspected | Count, Clear, or Not reviewed |

Include all seven domains. Clear means inspected with no actionable finding.

Findings

Order findings by priority:

| # | Impact | Reach | Confidence | Change risk | Domain | Evidence | Smallest safe change | Why | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |

Use exact file and line citations in Evidence. If there are no findings, omit the table and state No actionable codebase findings.

Considered but rejected

| Candidate | Evidence inspected | Rejected because | | --- | --- | --- |

Include only genuine candidates.

Safe change sequence

For review, provide a short recommended order only when findings exist. For plan, include steps, dependencies, rollback boundaries, and verification. For implement, list the completed steps and any intentionally deferred work.

Verification

List exact commands or inspections and observed results. Separate passed checks, failed checks, and Not verified items.

Recommendation

End with exactly one:

• Implement now — at least one high-confidence improvement has a safe, verified path.
• Plan first — worthwhile work exists but requires coordination, missing evidence, or a high-risk migration.
• No change — no actionable finding remains in the inspected scope.

Non-negotiable guardrails

• Preserve intended behavior unless a behavior change is explicitly approved.
• Never apply SOLID, DRY, Clean Architecture, patterns, or metrics dogmatically.
• Never introduce an interface for one implementation without a concrete boundary reason.
• Never remove duplication solely because code looks similar.
• Never split coherent code into micro-functions merely to shorten it.
• Never change a public API, schema, or wire format casually.
• Never recommend an upgrade without checking compatibility and migration cost.
• Never claim a performance improvement without measurement or established complexity evidence.
• Never hide pre-existing test failures or unverified assumptions.
• Never turn a review request into an edit.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NicolasYusim
• Source: NicolasYusim/better-codebase
• License: MIT

Install and usage instructions live in the source repository linked above.