codebase-zero

Files (13)

• DIFFERENTIATION.md
• SKILL.md
• consolidate-three-http-clients.md · examples/
• defer-cleanup-report-builder.md · examples/
• delete-legacy-csv-exporter.md · examples/
• index.md · examples/
• invest-matching-engine.md · examples/
• keep-idempotency-replay-guard.md · examples/
• keep-v1-webhook-payload-shape.md · examples/
• simplify-notification-provider-abstraction.md · examples/
• blast-radius.md · references/
• complexity.md · references/
• evidence.md · references/

SKILL.md (first lines)

# Codebase Zero

**Every artifact must keep earning its right to exist.**

Requirement Zero asks whether a requirement deserves to be built. Codebase Zero asks the same
question one stage later, about code that is already here: *does this still deserve to exist?*

This is an audit. The output is a verdict per artifact with the evidence behind it — not a diff.
Do not delete, move, or rewrite anything unless the user has separately asked you to apply a
finding; see "Applying a finding" below.

## Before auditing anything: state the mission

Answer first, in one sentence: **what must this system do well, such that doing it badly makes
everything else worthless?** Payments: settle money correctly. Search: relevance. Database:
durability.

Every verdict below is relative to that sentence. Without it there is no difference between this
audit and a size preference, and the audit will quietly become "delete the code I find
unfamiliar". If the mission cannot be stated from the repository, its docs, or the user, say so
and ask — do not substitute lines of code, file age, or churn as a proxy.

## Per-artifact procedure

For each artifact under audit, in this order:

1. **Objective** — what user-visible, operational, or contractual outcome does this artifact
   enable? State it as an outcome, not as a description of the code. "Serializes the config" is a
   description; "lets an operator change retry limits without a deploy" is an outcome.

2. **Origin** — what requirement caused it to be built, and is that requirement still valid?
   Use `git log`, `git blame`, and linked tickets or PRs to find the original reason. An artifact
   whose original requirement is gone is a deletion candidate; an artifact whose reason cannot be
   found is *not* the same thing, and is at most DEFER CLEANUP until it is understood.

3. **Dependents** — who or what depends on it *today*: callers, imports, tests, config,
   deployment manifests, external clients you cannot enumerate. Search before asserting. See
   [references/evidence.md](references/evidence.md).

4. **Failure on removal** — what observably breaks if it disappears, and who notices through what
   signal? Name the observer and the signal. If neither can be named *and* step 3 found no
   dependents, deletion is a live hypothesis. If the only answer is "a protection stops
   protecting", read "Constraints not yours to delete" before going further.

5. **Complexity class** — accidental, historical, or essential to the mission. This is the step
   that decides between SIMPLIFY and INVEST, and getting it backwards is the expensive error. See
   [references/complexity.md](references/complexity.md).

6. **Blast radius and cost** — how far a change reaches, and what keeping it costs per unit time.
   See [references/blast-radius.md](references/blast-radius.md).

Then one verdict.

## Verdicts

State exactly one per artifact. Do not offer the user a menu, and do not average several artifacts
into one vague assessment — audit them separately even when they touch.

| Verdict | Select when |
|---|---|
| **DELETE** | No current dependent, no nameable observer of its absence, and its original requirement is gone or was never valid. Removal risk is understood and acceptable. |
| **CONSOLIDATE** | Two or more artifacts do substantially the same job. The behavior is needed; this many implementations of it are not. Name the survivor. |
| **SIMPLIFY** | The behavior is justified, the implementation carries structure nothing uses — an abstraction with one implementation, an unreached branch, a layer that only forwards. |
| **DEFER CLEANUP** | It looks removable but the evidence is not there yet, or the risk is not currently worth the benefit. Name the specific missing evidence or the trigger. |
| **KEEP** | It still earns its place — a live dependent, a real contract, or a protection whose value does not show up as traffic. |
| **INVEST** | It is complex and expensive *and* it is where the mission is currently won or lost. Spend more engineering here; do not simplify the capability away. |

An audit that never reaches KEEP or INVEST is not rigorous, it is miscalibrated. The failure mode
of a subtraction practice on an existing codebase is not over-building — it is removing the load-
bearing thing because it was the hardest to understand.

## What every non-trivial verdict must include

Seven fields. A verdict missing any of them is not reviewable, and a reviewer cannot disagree with
it cheaply, which is the only property that makes an audit useful.

1. **Fundamental objective** — the outcome the artifact serves, from step 1.
2. **Evidence** — what you actually searched and what you found, including "searched X, found no
   callers". State absence as absence; never fill a gap with plausible reasoning.
3. **Confidence** — high, medium, or low, and the one thing that would raise it.
4. **Blast radius** — what a change to this reaches, including anything you could not enumerate.
5. **Expected benefit and cost** — what removing or changing it buys, against what the change
   costs to make and verify. If the benefit is only "less code", say that plainly; it is a weak
   benefit and should read like one.
6. **What is retained** — the behavior that must still hold afterwards.
7. **Verification needed** — the specific test, check, or observation that would show the change
   was safe. "Run the test suite" is only sufficient if you checked that the suite actually covers
   this artifact.

## Evidence rules

Absence of evidence is a finding, not a licence. Three fallacies decide most wrong verdicts:

- **Age is not irrelevance.** Code untouched for four years may be finished. Stable and dead look
  identical in `git log`.
- **Churn is not value.** A file changed every week may be a defect cluster, not a core asset.
- **No traffic is not no purpose.** A kill switch, a rate limiter, a fallback path, or an audit log
  can be doing its job precisely by never being exercised.

Prefer evidence in this order: current references in code and config; tests that assert the
behavior; a contract with a caller; history explaining the original requirement; telemetry, but
only where it is already collected and trustworthy. Do not commission new telemetry to justify a
cleanup — that is a bigger project than the cleanup.

Do not read the whole repository. Search for what would change the verdict, and stop when it
would not. [references/evidence.md](references/evidence.md) has the specific searches.

## Constraints not yours to delete

Some artifacts exist to stop something rare and expensive. Their evidence profile looks exactly
like abandonment: no traffic, no recent change, no one who remembers why.

Do not recommend DELETE on your own authority for: authentication, authorization, encryption,
input validation, audit trails; rate limits, circuit breakers, kill switches, idempotency and
replay protection; data integrity constraints, privacy, consent, retention and deletion behavior;
anything satisfying a regulation or contract; migration and backfill correctness; the compatibility
surface of an interface whose callers you cannot enumerate.

For these the default is **KEEP**, and the challenge is aimed at the *size of the implementation*,

From Chisanan232/requirement-zero, MIT.

More from Chisanan232/requirement-zero