/plumb-line-method

name: plumb-line-method
description: "Use when an edit would make the system look more real, finished or certain than it is, to make the honest version instead: a failing test or red CI that cannot honestly pass (a dependency down, a bar missed, nobody knows why) under pressure to get it green anyway; a fallback, fixture or generated value passed off as real; a guessed threshold hardcoded as if measured; a stub called production-ready; a baseline regenerated without explaining the drift; a confidence or provenance field dropped; an inconclusive result shown as a number; a layer shortcut. It answers yes, and: meet the need, keep what is uncertain visible. Not for changes with a known, honest cause or a decision behind them: a code bug, a wrong test, a signed-off change, intended behaviour. Also use when a builder wants to learn the plumb-line method: the thesis, the nine principles, the maturity vocabulary, the one-line test."

The plumb-line method

Read `reference/portable-principles.md` (relative to the plugin root) and teach from it. Do not restate the principles here — that file is the single source. If the file cannot be read, stop immediately and report: "Cannot teach: `reference/portable-principles.md` is missing or unreadable. Do not continue from memory."

If you were invoked in the middle of a task, go straight to the section for that moment; the walk can wait. A failing test or red CI that has to be made to pass, where the reason may lie outside the code: **Mid-task: a test that cannot pass honestly**. Any other edit that would make something look more real, finished or certain than it is: **Mid-task: other moments**.

When invoked:

1. Read the principles document. 2. Give the builder the thesis and the spine (null results are valid) first. 3. Walk the nine principles only as deep as asked; lead with the one most relevant to what the builder is doing. 4. Always end on the one-line test as the portable gut-check. 5. Point onward to the next step (below) — a builder who has just learned the method should not be left wondering how to apply it.

This skill never edits files or installs anything.

Mid-task: a test that cannot pass honestly

The moment: you have been asked to make a failing test pass, or CI green, and the reason it fails is outside the code you can change. A service is unreachable, a credential is not provisioned, the data does not contain what the test needs, the model does not reach the bar, or the test and the spec disagree and nobody has settled which is right. This is the spine of the principles (a null result is a first-class outcome) one level up: a failing test is a null result about the project, and making it pass without meeting it erases that result where CI can no longer see it.

This skill still edits nothing. In this mode it tells you, the agent doing the task, what the honest version of your next edit looks like.

What this does not forbid

This is guidance for one moment, not a block on coding. In the owner's words (#485): "It needs to be practically usable and help keep the code honest about itself, not stop a user being able to code." Changing tests is normal work. All of these are fine; do them, and say what you did:

• **Behaviour you changed on purpose.** A test that fails because the task

changed behaviour (a snapshot after an intended UI change, TDD going from red to green, tests of a feature you removed) is outside this moment: update it to the intended behaviour and say the change was intended.

• **A wrong test gets fixed.** A typo, a wrong expected value, a test that

contradicts a settled spec, a spec that changed with sign-off: change the test, and say what was wrong and whose decision set the new expectation (the spec, the ticket, the owner), never "whatever the code returns now".

• **Stubs while building or prototyping.** A stand-in for a service that

does not exist yet is fine on the terms of P4 — Quarantined fakery: contained and labelled as a mock (as `mock`, where the project uses P6 — Maturity vocabulary), and kept out of real outputs unless the owner opts in. Its test is named as a test of the stub, and is added alongside any test of the real requirement, never in place of it; that test stays, red or deferred as below, and your final message says the requirement is not met yet.

• **Mocks in unit tests.** Mocking your own collaborators to test a unit's

logic is ordinary testing: in a test of that unit, alongside the test that states the requirement, not in place of it.

• **Decided changes.** A threshold or gate moved by a decision, or a test

removed along with the behaviour it tested, is fine when the change says whose decision it was.

One limit on the two stand-in rows (stubs and unit-test mocks): a test never presents a stand-in's result as `real`. When the stand-in sits below the point where the code marks its sources (a stubbed `fetch` or client, fixture files read by the loader), correct code marks its data as real, because it cannot tell. A test of that stand-in checks the logic it tests and makes no claim about provenance: never that the result is real, measured or high-confidence. Only a stand-in labelled at or above the marking point can be asserted `mock`. Nor does the test feed the stand-in data that produces the requirement's expected value, which would make a pass against the stand-in read as the requirement met.

What counts as a decision (a reading of option C, below, which leaves whether a requirement can wait to the owner; confirmed by the owner on #485, 2026-09-29): one the owner, a spec or a ticket made about *this* expectation. A request to make the test pass or CI green is not a decision to change what the test requires, and neither is your own judgment. An explicit instruction that names the new expectation ("lower the bar to 0.80, we accept that for now") is one.

The line, every time: a change is honest when it says why and, where it changes what coun