Using Ledger

Using ledger

Ledger is the operating discipline for a codebase worked on over a long horizon: hundreds of turns, thousands of changes, across sessions that share no memory. At that scale the thing that kills a project is not a bad commit — it is silent rot. Prose stops describing the code, rules go unenforced, dead surface becomes undeletable because nobody can prove it is dead, and claims pile up that nobody can check.

Every skill here exists to keep one of those from happening. This one tells you which to reach for.

The seven rules

These compress most of the pack. They are worth holding in view even when no skill is loaded.

1. Narrowest sufficient evidence. Run the check that would actually fail. Never the full suite by reflex.
2. Never fake a green. No suppressing empty results, no lowered thresholds, no narrowed scope to hide a file.
3. Return the budget; do not invent headroom. Restoring a limit that was already granted is not masking. Widening an unexamined wait is.
4. Brevity is not the goal. A smaller word count alone is not an improvement.
5. No quotas. Age, length, and count are discovery aids, never criteria.
6. A green signal is not evidence. Coverage is not correctness. A passing rerun proves nothing. A queued merge is not a landing. A zero-hit search proves nothing until it has matched a known positive.
7. A mechanism's existence is not a reason to use it. Tools invite the work they are capable of.

And the one that subsumes several of them: verify the world, not the self-report. A keyword probe on a worker's own output lets a worker that did nothing pass by claiming success.

Before you start working

Measured, not assumed: given a realistic prompt in a session with a full tool set, this pack's skills often did not load at all — and in every one of those runs nothing else loaded either. The model simply began working. The first move was ls -la.

That is not a neutral outcome. It means the discipline that would have applied was never in view, and the work proceeded on whatever the model already believed. The pull toward starting is strongest exactly when a rule would have changed what you did.

Reaching for the wrong one costs a few seconds. Reaching for none is how a change lands with nothing behind it.

Where to reach for what

Load more than one when more than one applies. They are written to compose, and each names the boundary where it hands off.

The five pillars

If you want the shape rather than the index:

1. Documentation is the substrate, not the byproduct. For a human team docs are a courtesy; for an agent they are the working memory. Every fact gets one home, and a rule that becomes mechanical is promoted into a check and deleted from the prose. — writing-complete-propositions, fact-checking-by-execution
2. Agent-native by construction. Written for the case where a model is the author, which changes what the failures are: prose carries the authoring session's viewpoint, speculative surface accretes fast and evenly, and the worker will report success — including to itself, by writing down what a thing means and treating that as having built it, and by reading a green suite as a working product. — trimming-session-vantage, what-counts-as-evidence, specifying-acceptance, validating-real-scenarios, proving-code-is-dead
3. Loop engineering: each iteration cheap and true. A long-horizon loop dies of wasted turns. What a request earns before it earns a change, verified bases, an arrangement that says where each unit runs, narrowest checks, and a gate that decides when one is finished. — qualifying-a-request, scoping-a-change, planning-the-work, running-a-bounded-loop, refusing-busywork
4. Long-horizon automation needs a durable record. A reader 500 turns later must resolve every reference and re-derive every decision. — curating-decision-records, recording-ui-evidence
5. Rot resistance as a build requirement, not a cleanup task. Pin the absence of dead values so a stale reference fails a check instead of aging quietly. Prove code is dead before deleting it. Every other discipline here produces knowledge; exactly one reclaims it, and without that one the record only grows. — proving-the-regression, designing-concurrent-tests, diagnosing-flakes, reviewing-as-cis-complement, pushing-safely, metabolizing-knowledge

The adapter is not an adoption gate

No skill in this pack names a command. Project-varying values — test lanes, CI ownership, hooks, source globs, protected designs — live in .ledger.yml at the repository root, and the skills that need to run something read it.

A missing .ledger.yml does not mean these disciplines do not apply here. Most of them never touch it: what a signal proves, whether a passage carries its propositions, whether code is provably dead, what a review must cover, whether a guard has been seen to fail — none of that needs to know your test command. Apply them regardless.

Only two things change when the file is absent:

• A skill that needs to execute a specific project command says the value is missing and stops there, rather than guessing. A wrong command is worse than a missing one, because it runs and produces a result you will believe.
• adapting-to-a-project is worth running at some point, so those skills stop being blocked. It is a convenience, not a precondition.

Treating the file's absence as "this pack is not adopted here, skip it" is the one reading to avoid. It was a real observed failure: with this router in context and no adapter present, the discipline was skipped wholesale on exactly that reasoning.