Start here
ReferenceNormative
Evidence and forecast
Every claim carries a pointer someone can open; every multi-step goal is priced before it starts; every check is proportional to what the change can break.
Evidence — ground every claim
Every factual statement carries a pointer that can be opened and checked.
| Claim | What must accompany it |
|---|---|
| Code behaviour | path/file.ext:line, a symbol, or a test name |
| "It works" / "fixed" | The command run and its real output |
| Live or production behaviour | The request and response, or the query and its rows |
| An external fact — library capability, pricing, API contract | The version or URL, and when it was read |
| A number — timing, cost, counts, lines | The command or query it came from, else labelled an estimate |
Rules:
- If the pointer cannot be resolved, it is not evidence. A confident summary is not evidence.
- Did not check? Say "unverified" or "assumed" in the same sentence.
- Never report a plan, an intention, or a clean compile as a tested outcome. See testing for what a green suite has to be worth before it counts as evidence.
- Report what ran, what passed, and what was skipped. Where the claim is coverage, it is a query, not an opinion — see the checking scripts.
- When asked for advice, look up what the industry actually does rather than answering from instinct.
Forecast — price the work before doing it
Any goal with more than a handful of steps starts with a cost model, not a task.
- State the deliverable in countable units — "950 records imported", "12 endpoints live".
- Forecast wall-clock from arithmetic — units × unit cost, tasks × observed cadence — labelled as an estimate. If it exceeds the session or the stated horizon, say so in the first reply and get assent before starting.
- State when the first deliverable unit lands. A plan whose first unit arrives late must name that as a risk up front: a long runway of pure preparation is a decision to be taken, not a fact to be discovered.
- Name the dominant cost. If an alternative is at least twice as cheap, present both.
- Progress reports lead with deliverable units — "0 of 950" — never with process phases. Preparation is labelled preparation. Never say "the hard part is done".
- Announce any forecast change over 20% unprompted, with its cause.
- Calibrate. When a task overruns its estimate, revise the remaining tail by the observed factor — unprompted, with the arithmetic shown.
- Set checkpoints before starting — "by hour 4, gate green". A missed checkpoint is a stop-and-re-plan event, not a keep-going event.
- "Why is this slow?" gets numbers and a re-forecast, never justification.
Verify in proportion to the blast radius
Match the checking to what the change can actually break. The default is the smallest thing that could fail because of this edit — not the biggest thing available. Spinning containers or running a full gate for a comment is not diligence, it is theatre.
| What changed | What it earns |
|---|---|
| A comment, a document, a log message, a variable rename | Nothing. Maybe a format or build. Read the diff. |
| One function's logic, with tests | That package's tests. |
| A package's public surface | That package plus its direct callers. |
| Schema, migrations, auth, wiring, anything cross-cutting | The full gate. This is what it is for. |
| Anything touching production, or hard to reverse | Everything — and say so first. |
- Never rebuild a container to check something a
grepanswers. If the question is did my edit land, read the file. - One check that can fail is worth more than five that cannot. Pick the test that would actually go red, and run that one.
- Batch the expensive gates. Run the full set once before committing, not after each edit in a sequence.
- State what you ran and why that was enough. "Built and read the diff — this is a comment" is a complete answer. So is "full gate: this touches migrations".
- When unsure whether a change is trivial, ask what it could break. If the honest answer is "nothing that compiles", trust that.