context-auditor

# Context Auditor Run this **before** a long build, not after it goes wrong. Everything in an always-loaded instruction file is a premise the agent reasons from on every turn. Premises rot. A count that was right in March, a path that moved, a rule written for one incident and never scoped — each one is a small confident wrongness the agent cannot detect, because from the inside a stale fact and a true fact look identical. The cost is not one bad answer. It is a whole session built on a wrong premise, and the loop that follows when the work does not match what the instructions promised. ## What you are looking for Two defects, and they fail differently. ### 1 · Stale facts — true when written, false now Anything that names a **number, a path, a version, or a name** is a claim about the world that the world can invalidate. These are cheap to check and worth checking every time: | Kind | Example of the rot | |---|---| | Counts | "12 services", after two were merged | | Paths | A file reference that moved in a refactor | | Versions | A pinned tool version the lockfile has since bumped | | Names | A module, script or command renamed | | Layout | A directory tree that no longer matches `ls` | | Status | "currently migrating to X", long after the migration finished | **Check them, do not read past them.** Every one is verifiable in a second: run `ls`, read the manifest, grep for the name. A claim you can check and did not is worse than no claim, because it carries authority it has not earned. ### 2 · Overconstraints — rules broader than the reason behind them Harder to spot, and they do more damage. An overconstraint is a rule that was correct in one situation and got written down without its scope, so it now applies everywhere: - **A prohibition with no live reason.** "Never use X" — because of an incident that a later fix already resolved. The rule outlived the cause. - **A rule with its scope stripped.** "Always do Y" was true of one module; it is now stated as a project-wide law, and it fights the code everywhere else. - **Mutually exclusive rules.** Two instructions that cannot both be satisfied. The agent satisfies one, appears to disobey the other, and looks unreliable when it is actually stuck. - **Rules already enforced mechanically.** A convention a linter, formatter or CI check already guarantees. Harmless but not free — it takes context budget and adds nothing. - **Instructions describing what the code already shows.** A layout, a signature, a dependency list. Derivable in one command, so it is paying rent to say what `ls` would say. The tell for an overconstraint: **you cannot state the reason it exists.** If nobody can say what goes wrong when the rule is broken, it is not protecting anything. ## The audit Work through the always-loaded files — the project instruction file, anything it imports, and any rules file loaded on every turn. Not every doc in the repo: **only what is in context on every turn**, because that is what shapes reasoning whether or not it is relevant. For each claim, put it in one of three buckets: | Verdict | Meaning | Action | |---|---|---| | **Verified** | Checked against reality, still true | Leave it | | **Stale** | Checked, no longer true | Propose the correction, with what you checked | | **Unscoped** | Cannot state the live reason, or it is broader than its cause | Propose scoping it or cutting it, and say which | Then report: what you checked, what you changed, and **what you could not verify** — that last list is the honest part, and it is where the next failure will come from. ## Rules for the audit itself **Propose, do not silently edit.** These files encode decisions you were not present for. A rule you cannot see the reason for may still have one. Show the diff and let a human decide. **Check, do not infer.** "This probably still points at the right directory" is how a stale fact survives an audit. Run the command. **When in doubt, keep it.** A slightly redundant rule costs a little context. A deleted rule that was load-bearing costs an incident. The asymmetry is not close. **Never cut a safety prohibition for looking generic.** "Never force-push to the shared branch", "never edit generated files", "never commit secrets" stay, whether or not anyone can recall the incident behind them. Those are the rules whose reason is *supposed* to be invisible — the incident did not happen because the rule worked. ## What good looks like afterwards Every remaining claim is either verified or explicitly marked unverified. Every remaining rule has a reason someone can state in one sentence. Anything derivable from the code in one command is gone. The agent is now reasoning from a smaller set of premises that are actually true — which is worth more than any amount of additional instruction sitting on top of a wrong one.