# "Repeal needs a record: why your team's rules files only grow"

*"Deleting a rule is amnesia. Retiring a decision is an event with a reason. How supersession chains keep team rules from ratcheting forever."*

A dev opens a PR deleting one line from the team conventions doc, the rule about wrapping every external call in the homegrown circuit breaker. The thread runs two days. Nobody can say whether the incident that produced the rule is still possible, so the PR gets closed and the line stays. Multiply by a few years of that and you have a rules file everyone scrolls past.

Rules files only grow because the only way out is deletion, and deletion is amnesia. After the line is gone the team knows less than it did before, not more. There's no trace the rule existed, no reason it stopped mattering, no name attached to the judgment that it was safe to drop. Rational people don't sign up for that, so the file ratchets.

Repeal needs a record. Retiring a rule should be an event with an author and a reason, not an absence in a diff.

That's how we ended up building kgai, a decision log for AI dev teams. A change of mind is a new decision that supersedes the old one, and supersession is an explicit link carrying the reason. Nothing is edited in place, the log is append-only, so the retired decision stays queryable, marked superseded. Agents don't trip over the history either, recall returns only decisions in force.

The chain is the payoff, and our favorite shape of it is the flip-flop. Retries move from backoff to a fixed schedule because a provider rate-limits bursts, then back to backoff when the provider lifts the limit. Three decisions, two supersessions, and *why did we flip twice* has an exact, dated answer instead of a shrug.

One scope note. kgai records your team's engineering decisions, it does not manage the rules file itself. That stays yours to edit. But when a rule traces back to a recorded decision, retiring it stops being guesswork, because the decision carries the reason and the supersession carries the repeal. [My CLAUDE.md is 1,000 lines](https://kgai.dev/blog/claude-md-1000-lines) is this same disease seen from the rules file, and rejected approaches get the identical treatment in [dead ends are documentation](https://kgai.dev/blog/dead-ends-are-documentation).

Local-first, no daemon or server to run, opt-in sync through an S3 bucket you own, MIT, a Claude Code plugin plus a standalone kg CLI.

Two commands and the next change of mind becomes a record instead of a deletion. Other tools solve adjacent problems, and the comparison page says which.

## Try kgai

Two commands, MIT, nothing leaves your machine until you configure a bucket:

```
claude plugin marketplace add kgaidev/kgai
claude plugin install kgai@kgai-marketplace
```

Source: https://github.com/kgaidev/kgai
See how kgai compares to other tools: https://kgai.dev/compare
All notes: https://kgai.dev/blog/

---

Canonical: https://kgai.dev/blog/repeal-needs-a-record · Written by kgai maintainers · kgai is MIT open source