# Software: building, checking and delivering code

Load when the output or the work includes software. Most sections are about the ways agents
specifically fail: work that reads as finished and is not, tests that cannot fail, pipelines that
are green while checking nothing, setup that reports success while broken. For every procedure
here, evidence means the command, its exit code and its summary line, verbatim, and the review is
by someone other than the author (`quality.md §Reviewing work`).

## Delivery: review, CI, deploy, rollback

- **Every change is proposed for review** (a pull request, or the project's equivalent) that
  references its work item and states what was verified and how: the test seen to fail without
  it, the measurement before and after. A reproduction is proposed as a reproduction, not a fix.
- **A reproducible build:** installed from the lockfile, from clean.
- **The checks that gate the merge have each been seen to fail** (§Pipelines that can fail), and
  they actually run on the change in question (not skipped by a path filter, not advisory).
- **A release is one action and can be staged:** a small share of people or devices first, the
  critical journeys watched, a pause that triggers itself at a failure threshold set in advance.
- **Rollback is one action, and it has been tried.**
- **Reaching people is its own step** (`product.md §Releasing to people`).

## Setup that runs from cold

A clean environment must install, build and run the tests using only the setup, with no step a
person supplies from memory. Many harnesses snapshot a successful setup and reuse it, so a defect
here is paid for by every future task.

1. **Find out what actually breaks from cold before repairing anything.** Determine the language,
   package manager, test runner and build tool from the manifests present. Read the CI workflow:
   if it passes, it contains a sequence proven to work on a clean machine; start from it, not the
   README. List every external dependency the tests touch. Run the existing setup and record where
   it fails, with the command and its output.
2. **Rules for the setup:**
   - no long-running processes: no dev server, file watcher or foreground daemon; a service the
     tests need is started detached, polled until it accepts connections, and fails loudly with
     its log if it never does (a fixed sleep is not a readiness check);
   - exit codes are true: no `|| true`, no swallowed installer status, `set -euo pipefail` or the
     equivalent; a setup that cannot fail is the same defect as a test that cannot fail;
   - unattended: pass the tool's non-interactive flag rather than piping `yes`;
   - no secrets, and no assumed credentials: detect a missing token and say so in one line;
   - lightweight: install what the tests need; install from the lockfile;
   - install and verify are separate phases, so a failure says which it was.
3. **Repair, run, repeat until the test runner reports results.** "Runs to completion" means the
   runner reported; it does not require every test to pass, and tests are not edited here.
4. **Prove the two silent failures:** make a required install fail and confirm the setup exits
   non-zero; confirm nothing in it blocks.
5. **Report** the baseline failure verbatim, each change with its reason, the final runner summary
   line, and what still cannot run here and why. Write the install and test commands and required
   environment variables where every agent reads them (`autonomy.md §Standing rules for the
   project`).

## Tests that do not need services

A suite that assumes a database, a broker, a seeded staging server or a live API fails with a
connection error partway through, and the agent then reports the failures as "unrelated to our
changes". The change looks reviewed and was never tested.

1. **Run the suite with nothing else running,** and record the exact failure, the count, and
   whether it failed at collection or in tests. Import-time connections fire before any test. Look
   in the test configuration and fixtures (`conftest.py`, `setup.js`, base test classes, factories,
   seeders), `docker-compose` and `.env.test` files, CI service definitions, and any helper that
   opens a socket, reads a URL from the environment, or constructs a client at import time.
2. **Inventory every external dependency:** what it is, which tests touch it, whether a seam exists.
3. **Substitute one dependency at a time,** running the suite after each:
   - fake at the boundary the project already has (a repository class, a client wrapper, an
     interface); patch the library only when there is no seam, and report that as a design finding;
   - an in-memory substitute can lie (SQLite accepts what Postgres rejects): where behaviour
     genuinely differs, keep the test as an integration test with a marker;
   - for third-party APIs, record a real response rather than hand-writing a stub;
   - freeze the clock, seed randomness, block outbound sockets, and let a test that reaches for the
     network fail with a message saying so.
4. **Rules:** never change what a test asserts (a test that can only pass by weakening its assertion
   is left failing and reported); no test is skipped silently, every exclusion has a named marker
   and the service it needs; the default command is the isolated run; the full suite against real
   services stays runnable, with its command documented.
5. **Prove it:** block outbound network or point service URLs at a dead port, and the default suite
   still passes; compare the collected-test count before and after, and reconcile every test that
   stopped running against the marked list exactly.

## Tests that can fail

A test written while looking at the implementation asserts what the code does, so it can never
catch the code doing the wrong thing. Coverage rises, the suite is fast, the change reads as
careful, and the number of real regressions caught is zero.

- **The tells:** a test that mocks the unit under test; an assertion on shape only (`is not None`,
  `toBeDefined`, `status == 200`, `len > 0`) with no value assertion beside it; an expected value
  reconstructed from the implementation's own arithmetic, or captured by running the code; "no
  exception raised" as the only check; fixtures or snapshots captured from the code under test.
- **Choose what to audit from version-control history, not names or comments:** every test file
  added or changed by agent-authored commits or pull requests (for example `git log
  --diff-filter=AM` over the test directory), the fixtures, snapshots and recorded responses added
  with them (a snapshot committed with the code it snapshots is suspect), and every mock or patch
  that substitutes the module under test rather than its dependencies.
- **Take a cold baseline before mutation or edits:** the in-scope suite's collected, passed, failed
  and skipped counts, with skip reasons. A baseline that could not run is a limitation, not green.
- **Prove each test can fail; do not read it and decide.** Mutate the code, not the test: invert a
  condition, return a constant, drop a field, skip a call. For a test that came with a fix, put the
  original defect back as precisely as you can (the inverted condition, the removed guard, the old
  off-by-one), never delete the function. Run that test alone and read its failure: red must be on
  its assertion about the behaviour, not an import, fixture or collection error. One break at a
  time; restore each immediately; at the end the suite is green and the tree is clean of mutations.
- **A test that cannot fail is fixed (rewritten against the requirement, and re-run under the same
  mutation) or deleted; never left.** Coverage going down when a useless test is removed is the
  right direction; report it with its sign.
- **A test that fails once made meaningful is a real defect:** report it and leave it failing.
- **Check what the suite collects,** not what passed: compare the collected count against the test
  functions you can count. Read every skip, mark and condition added, with its reason and whether it
  is still true.
- **A claimed fix with no test is a finding.**
- **Account for the audit:** tests examined, unable to fail meaningfully, rewritten and deleted;
  final suite counts and the coverage change. Do not add unrelated tests or change thresholds to
  compensate for lost coverage after removing misleading tests.

## Pipelines that can fail

A red pipeline is fixed within the hour. One that is green for the wrong reason is never looked at,
and it removes the habit of checking, because everyone believes the check is happening. Absence
looks exactly like success.

- **The mechanical causes, to check one by one:** a test command that matches no files ("no tests
  ran", exit 0); a pipe that reports the last command's status (`checks | tee out.txt`);
  `continue-on-error`, `|| true`, `set +e` or a swallowed exception; a path or `if:` filter that
  stopped matching, so the job never runs; a matrix leg that excludes itself, or a step skipped
  because an earlier one was; a linter with its rules disabled or `--exit-zero`; a job testing a
  stale cached artifact.
- **Method:**
  1. inventory every job and step, and what each claims to check, including reusable and inherited
     workflows, the scripts they call (especially wrappers that aggregate several checks),
     linter, formatter and test-runner configuration (including files that exist only on CI),
     caching and artifact steps, and every condition that decides whether a job runs; read the run
     history for jobs that have never been red, or stopped appearing (the first suspects);
  2. test the setup's own failure path first: if an install fails, does the pipeline stop or reuse
     a cache and pass?
  3. for each step, introduce the defect it exists to catch, one at a time on a throwaway branch
     reverted at once, and record whether the run went red and how long it took;
  4. group the survivors by cause, repair each, and repeat the same defect to see it fail now;
  5. make every step print its coverage (tests collected, files read) and reconcile against what
     exists;
  6. confirm each expected job ran, by name, on the change itself; a badge is a claim about one
     branch's last run;
  7. leave the branch clean of every deliberate defect and green on an unmodified tree.
- **Remove every swallowed exit code, or justify it in a comment on the line that allows it.**
- **Do not add new checks while existing ones are inert;** list the missing ones separately.
- **A check that cannot be made to fail is reported plainly,** with what was tried, not deleted.

## Automations that report their own failure

The failure that matters is not a script that breaks; it is a script that succeeds without doing
anything. It exits 0, the output looks complete, and it is trusted for months. The automation's
real job is a trustworthy answer to whether the work happened.

1. **Find the workflow before automating it:** the commands people actually run, from shell
   history, the Makefile and package scripts, CI files, commit and review history, and onboarding
   docs; how often it runs and what a mistake costs, with sources. Something run twice a year that
   takes a minute may deserve a checklist, or a script for the one step that goes wrong, instead.
2. **Rules:**
   - never put a check on the left of a pipe; run it, capture its status, then act on it;
   - verify each step by its effect (the file exists and is not empty, the row is in the table,
     the service answers, the process is gone), not by its exit code; some tools exit 0 while
     failing;
   - do not truncate output you will decide from (`| head`, `| tail`); write it to a file and read
     the file;
   - ask the system, not an old artifact (the process table over an append-only log);
   - safe to run twice after a partial failure: no duplicates, no double charges, no clobbering;
     a step that cannot be idempotent detects that it already ran;
   - write results as they are produced, so an interruption costs the last item; resumable by
     skipping what the output already holds;
   - the log says what it read ("checked 40 files in src/"), never only "done";
   - say what it will not do, one sentence per case; boring and checkable over clever and total.
3. **Make it fail, and watch:** remove a dependency, a permission, an input, and interrupt it
   halfway; each failure must reach the exit code and the log. Report what you broke and what it did.
4. **Hand it over:** the one command that runs it, what it will not do, and where its log goes.

## Architecture from what runs

The folder structure is a claim about the architecture, and the claim most likely to be stale. A
diagram assembled from names is fluent, confident, and describes the system somebody intended.

- **The tells of a map built from names:** a layer in the diagram that no import crosses; a
  "service" that is one function called from one place; a module named for a concept that holds
  three unrelated things; a dependency arrow that points the way the design intended while the code
  goes the other way.
- **Where to look:** packaging and process definitions (`pyproject.toml`, `package.json`, `go.mod`,
  `Cargo.toml`, `Makefile`, container files) and the CI workflow, often the only honest list of how it
  is invoked; the resolved import graph; everything crossing a process, network, queue or database;
  configuration and environment variables; `git log` over the whole tree for co-change.
- **Find the entry points; do not guess them:** console scripts, `main` functions, server bindings,
  container commands, scheduled jobs, the commands CI runs. Run one and note what it touched.
- **Build the import graph from resolved imports.** A layer boundary is one only when you have shown
  nothing crosses it.
- **The real boundaries are the ones that fail separately:** a process, a network hop, a database,
  a third-party API. Two packages in one process that import each other freely are one component.
- **Use co-change:** files that change in the same commits are one unit of work, whatever folder
  they live in; report where this disagrees with the layout.
- **Look for the coupling nobody intended:** the shared mutable helper, the module everything
  imports, the cycle between two packages documented as independent. Anyone can find the designed
  layers; this is where the value is.
- **Follow the data:** where state lives, who writes it, who reads it. Two components that never call
  each other but write the same table are coupled.
- **Count things:** imports in and out per module, commits per path, places that construct the
  central object.
- **Say how you know, per claim** ("resolved the import", "ran it", "in 14 of 20 commits"), and name
  what could not be established statically (dynamic dispatch, reflection, plugins, configuration
  wiring). Do not draw a diagram the code does not support.
- **A good map predicts:** check it against two recent changes; it should say where they landed and
  what they touched.

## Scoping a vague issue

Given "the login is broken", an agent guesses what broken means and builds on the guess; the work
looks complete and fixes something nobody reported. Scope before fixing, and produce no fix here.

1. **List precisely what the issue does not say** (version, environment, input), and the distinct
   readings its wording allows. Read the report and everything attached to it, the tests and their
   fixtures (how this project already reproduces things), and the recent history of the named area.
   For each ambiguity, record the reading you took, so the next reader can correct you cheaply.
2. **Separate three statements:** what the reporter said, what the software actually does, and what
   it should do. Expected behaviour needs a source (documentation, a test, a type, a specification);
   if none exists, record it as undefined.
3. **Ask the codebase before the reporter:** the tests, types and history resolve most ambiguity.
4. **Confirm a clean baseline, then reproduce,** recording every attempt, including failures. An
   unreproduced report is stated as unreproduced, with exactly what was tried.
5. **Reduce to the smallest reproduction;** the steps you could delete show where the fault is not.
6. **Write a failing test that captures the difference,** confirm it fails for the reported reason
   (change the suspected cause and see the outcome follow it), and that the rest of the suite behaves
   as at baseline.
7. **Record other defects found on the way separately;** do not widen the scope.

## Fixing a bug, failing test first

A fix written before its test is indistinguishable from a coincidence; a test written after is
written against the new code and passes on the old too. The quieter failure is a test that fails
for the wrong reason (an import error, a missing fixture) and is spent as evidence it never earned.

1. **Know which tests are already red,** and name them; run your test alone so its red cannot be
   confused with theirs.
2. **Reproduce by hand from the report's exact input,** using the report and any attached logs,
   inputs or version information. Paraphrasing it into a tidier case fixes a bug nobody had. Find the
   narrowest module that could produce the behaviour by running, not by reading names, and read the
   test file that covers it and its fixtures.
3. **Write the failing test; read the failure line;** it must name the reported behaviour. Record it
   verbatim. Narrow until the test names one behaviour.
4. **Commit the test alone,** before any production change (revert exploratory changes first).
5. **Change the smallest thing that turns it green,** and stop. Split out formatting, refactors and
   version bumps. Never move the assertion to fit the code; if the test was wrong, start again.
6. **Run the full suite;** nothing else moved from green to red.
7. **The revert check:** remove the fix with the test in place; the test must go red again.
8. **Watch for fixes that pass by making the test unreachable** (guarding earlier, returning sooner,
   defaulting a value): confirm the changed path is the one the test executes.
9. **Say where the cause really was** if not where the report pointed, and **look for siblings:** the
   same pattern elsewhere, reported whether fixed or not. A bug that cannot be reproduced is a
   finding: what was tried, on what version, with what data.

## Complete changes, nothing detached

A change that stops halfway is worse than none: it adds a second way of doing the same thing.

- **Every layer in the same change:** the interface and every state it shows, the logic, the data
  and its migration, the configuration, the tests, the documentation, and operations (monitoring,
  backups, runbooks).
- **Everything added is reached** from an entry point a person or device uses.
- **Everything replaced is removed:** the old code path, its tests, flags, configuration,
  dependencies and documentation. Search the whole repository for references to anything renamed
  or removed.
- **Before finishing, check:** every new module is reached; every new configuration key is read;
  every new dependency is imported; no two paths compute the same fact; every feature flag has an
  owner and a removal date; the project's own dead-code and unused-dependency tools report nothing
  new.

## Reviewing an agent's change

Agent-written changes fail differently from human ones: correct style, sensible names, a confident
description, and tests that pass because they assert what the code does. The danger is not that
the code is bad; it is that it reads as finished.

1. **Treat the description as a set of claims:** every claim it makes about itself is checked or
   marked unchecked, never read as a summary. **List the linked issue's requirements** as discrete,
   checkable items; note which files the diff touches and which it does not; read the tests it adds or
   changes, and the CI configuration, to know which checks actually gate the merge.
2. **Baseline:** run the suite on the base commit, so you know what was already failing; then on
   the change, and account for every difference.
3. **For each test the change adds, break the code under it and confirm the test fails;** restore.
   For a change that claims to fix a bug, also apply `§Fixing a bug, failing test first` to the
   claim: compare the test's input with the report's exact input (a tidier input that divides
   evenly can pass on the old code), read the history for a test-only commit (a fix and its test in
   one commit cannot show the order), and name the tests that were already red before the change.
4. **Walk the requirements:** each met, partly met or not addressed, with file and line. Agents
   satisfy the part of a request they understood; the dropped requirement will not announce itself.
5. **Compare each assertion against the issue, not the diff.**
6. **List every weakened or deleted assertion, skip, widened tolerance and suppressed error** (new
   `try`/`except` around the changed path, a swallowed exit, `continue-on-error`, a log where a raise
   used to be), each with the reason given, or a note that none was.
7. **Confirm the check that should catch this runs on this change,** and is not skipped or advisory.
8. **Exercise the change by hand** if it has an interface: run the command, call the endpoint, load
   the page.
9. **Fix nothing unless trivial, and say so;** record unrelated problems separately. State what you
   could not verify.

## Security of agent-written code

An agent asked to make a failure stop finds the shortest route, which is often to remove the thing
objecting. The defect is a check that no longer checks, and the diff looks like work.

- Read the complete in-scope diff and account for every changed file, grouped as code,
  configuration, CI, dependencies, fixtures and documentation where applicable. Trace affected
  inputs, credentials and permissions; reuse the ordinary review's inventory when complete.
- For every new dependency record its exact name, version, resolved source and actual import/use;
  verify manifest and lockfile agreement. Use the project's record format, with none omitted.

- **What to look for:**
  - **a check that cannot fail:** a scanner under `continue-on-error`, an exit discarded with
    `|| true`, an audit only uploaded as an artifact; make each new check find something and
    confirm it turns the build red;
  - **verification switched off:** `verify=False`, `rejectUnauthorized: false`,
    `--no-check-certificate`, `NODE_TLS_REJECT_UNAUTHORIZED=0`, a pinned certificate removed;
  - **credentials in anything the change created:** examples, fixtures and documentation get
    plausible invented values; treat every key-shaped string as real until shown otherwise, and
    check the history as well as the tree;
  - **where each new dependency came from:** check the name character by character against the
    import it satisfies (typosquats), its maintainer and registry, and that the lockfile changed
    consistently with the manifest;
  - **permissions that widened:** `write-all` workflows, broader token scopes, mode 777, opened
    buckets or security groups; compare with what the change needs;
  - **a swallowed exception around an authorisation path** is an authorisation bypass: ask what
    happens to the request when it fires;
  - **injection wherever a string was built:** a query, a shell command, a path or an HTML fragment
    assembled by concatenation or formatting.
- **Report, do not repair** (unless one line, said plainly): each finding with file, line, what an
  attacker gains, and the smallest fix, ordered by that gain. Run the project's scanners and quote
  their output. State what you did not examine.

## Standards to apply

Name the standard when making a conformity claim, with its edition; follow these instructions
either way, since a citation is not an instruction.

- **Security (OWASP ASVS; choose level 1, 2 or 3 by what is at stake).** Write the threat model in
  five lines: what is worth taking or breaking, who could reach it, through which entry points. For
  every entry point (a route, a form, an upload, an argument, a message, a webhook, a device port):
  - who may use it, enforced where the caller cannot bypass it, never only in the client;
  - untrusted input handled as untrusted: nothing typed becomes part of a query, a shell command, a
    template or HTML; no path built from input escapes its directory; nothing deserialised or fetched
    on a stranger's say-so;
  - secrets: none in the repository or its history, the client bundle, logs, errors or diagnostics;
    each scoped to the least it needs, and rotatable;
  - transport: TLS, security headers, a content security policy, cookies flagged, cross-origin access
    no wider than needed;
  - abuse: limits on anything that costs money, sends something to a person, or can be called in a
    loop;
  - try each attack; a defence you reasoned about is not one you tested.
- **Supply chain (SLSA; OpenSSF practices):** a lockfile with hashes; a known-vulnerability scan and
  its result; CI actions pinned to a commit; nothing loaded at runtime from a source you do not
  control; a software bill of materials when the result is distributed; builds that reproduce.
- **Accessibility (WCAG 2.2 AA):** `design.md §Accessible and inclusive`.
- **Product quality (ISO/IEC 25010):** its characteristics (functional suitability, performance
  efficiency, compatibility, interaction capability, reliability, security, maintainability,
  flexibility, safety) are walked as areas in `quality.md §Walk every area`.

## Error paths

Error handling is the least-executed code and the most confidently written. A handler that has
never run is indistinguishable from one that works, until production supplies the difference.

1. **Find every handler,** with file and line and the count: every `try`/`except`, `catch`, `rescue`,
   `recover`, `if err != nil`, and every exit code set or passed on; everything that retries, backs
   off, times out, or is called fallback, default or safe; every boundary where others' failures
   arrive (network, subprocess, files, databases, parsing). What the tests do not cover is the
   finding.
2. **Cause each failure for real:** a host not listening, a revoked permission, a full disk, a
   corrupt file, a killed subprocess, a malformed payload. Make every external dependency fail and
   also go slow: timeouts must be bounded, retries capped and safe to repeat, and there must be a
   degraded mode the person can still use. Record what the caller sees. One you cannot cause is
   marked unreachable, which is itself a finding.
3. **Judge each one:**
   - a handler that catches everything also catches the bug: narrow it, or justify it in a comment;
     a top-level loop that must survive logs the traceback and does not pretend to have handled it;
   - swallow-and-continue returns as if it succeeded, and the failure surfaces three layers away;
   - the direction of failure is written down and safe: an unreadable permission reads as no; an
     unparseable limit means the limit applies;
   - a retry has a cap, a reason more attempts should help, and idempotence; retrying a
     non-idempotent write is a bug however carefully written; ask what happens on the second call,
     concurrently, after a partial write;
   - the message names the thing that failed, the input that caused it, and the next action;
   - exit codes and causes are not laundered: a pipe that takes its last command's status, or a broad
     catch that strips an exception's meaning, both turn a failure into something that looks exactly
     like success.
4. **Fix the wrong ones,** each with a test that asserts what the caller sees (the value, the
   exception, the file left, the exit code), seen to fail before the fix; never a test that the
   handler was called.
5. **Report the denominator:** found, executed, unreachable, wrong.

## Data migrations

A migration run once on a dev database and exiting 0 is the usual whole test, and every property
that causes an outage is invisible under exactly those conditions.

1. **Identify** the pending migrations (both halves, and any backfill they call), the migration tool's
   history table (what has been applied, in what order), the schemas and the application code that
   reads or writes the affected columns, the deployment configuration (whether migrations run before,
   during or after the application rollout, and any statement or lock timeout on the production
   connection: a statement that takes 40 s locally is killed by a 30 s timeout in production), the
   production engine and exact version, and `count(*)` for every table they touch (from production or the closest thing). If a count cannot be obtained, say
   so; the timings do not cover that table.
2. **Build a copy on the same engine and version,** seeded to realistic row counts (filler values are
   fine). Never touch production.
3. **Dump the schema; run forward, timing each statement and recording the lock it takes and for
   how long.** Nine minutes holding nothing is safe; nine seconds with an exclusive lock on the
   busiest table is an outage. Look up the engine- and version-specific behaviour of each statement
   (adding a non-null column, changing a type, validating a constraint, building an index without
   the concurrent option).
4. **Run the rollback; do not read it.** Dump again and diff; the dumps must be identical. Then run
   forward again.
5. **For each new unique or non-null constraint, count the rows that would violate it.**
6. **Interrupt any long backfill partway,** check it is batched and committing, and record what state
   it leaves.
7. **Prove the safe deploy order:** the previous release's code against the new schema, and the
   current code against the old. If both break, split the migration.
8. **A migration already applied anywhere is never edited;** check the history table.
9. **Destroy the copy;** report timings with the row counts they rest on, and what could not be
   measured. If you change the migration, repeat the measurements against the changed version and
   report both sets, identifying versions, data and conditions. Explain any condition that prevents
   a direct comparison.

## Dependencies

1. **Baseline:** install from cold from the lockfile, run the full suite, record versions and result;
   name tests that already fail. Read every ecosystem's manifests and lockfiles, the runtime and tool
   version files (`.nvmrc`, `.python-version`, `rust-toolchain`, base images, CI action versions), the
   changelogs and advisories for what moves (from the local mirror when offline), and the licence the
   product is distributed under.
2. **Stock:** outdated, vulnerable and unused, per ecosystem, including the runtime, base images, CI
   actions and build tools. Remove what nothing imports, as its own change, rather than updating it.
3. **One step per change:** patch and minor updates of one ecosystem together; each major version on
   its own; the runtime on its own. After each: regenerate the lockfile with the package manager
   (never by hand), install from cold with no cache, run the full suite. A step that breaks something
   is reverted, not patched over by the next.
4. **Read every major against the code:** list its breaking changes, search the code for each, and
   change or test each use; where the tests do not cover a changed behaviour, add a test that fails on
   the old behaviour first.
5. **Examine everything new or that changed hands, including transitive dependencies** (what the
   updated packages themselves pulled in, read from the lockfile diff): its licence against the
   product's, maintainer and source, install scripts, and a vulnerability scan. One that fails gets another route: an
   earlier version, a replacement, or the project's own code.
6. **Every pin has a reason and a revisit date;** an old pin with no reason is tried or explained.
7. **A major that cannot be taken yet** is recorded with its blocker and its route, and the rest
   proceeds.
8. **Do this on a cadence** for anything that keeps running (`operations.md §Upkeep`).

## Documentation that matches the code

Documentation rots invisibly: there is no red tick for a stale sentence. The quickstart is the most
important instructions and the least re-run. And documentation written from names and comments
restates the intended behaviour, now in a second place and sounding authoritative.

1. **Build the claim list:** every checkable statement in the README, guides, docstrings, examples and
   configuration reference, each with its file and line; group by how it will be checked (run this
   command, read this line of code, follow this link).
2. **Run the installation and quickstart from cold,** literally, typing nothing not written down;
   record every deviation you had to make.
3. **Verdict and evidence per claim:** verified (ran it, or the line that proves it), false (ran it and
   it did something else), unverifiable (cannot be checked as written, a finding about the sentence).
   Every unverifiable material claim gets a proposed measurable wording, verification plan or
   removal proposal with the decision it needs. Do not quietly delete a requirement because it
   is difficult to check, or leave an unverifiable promise without a concrete next action.
4. **Suspect first:** every number and name (versions, ports, paths, flags, defaults, timings,
   platforms); intent verbs ("should", "will", "automatically", "simply"); every link and anchor;
   every code block, run in order from the state the document says the reader is in.
5. **Fix the false claims against what the code does.** Where the code looks wrong rather than the
   document, leave the document and report the defect. Do not polish prose you have not checked, and
   do not drop a claim because it is hard to verify. Example output is produced by running the code.
6. **Re-run the suite and the quickstart from cold.** Report examined, verified, false, unverifiable.

Include generated messages and other outward outputs in the claim inventory. Check repeated
policy and values against their authoritative sources (`../SKILL.md §3. Work records`), not just
against other prose that repeats the same claim.

## Translations

A translation is a fork of the documentation with no way to tell it has drifted; a stale one answers
readers fluently with last year's instructions. The deliverable is the text plus the machinery.

1. **Decide the scope:** which pages, which languages, and which are left in the source language on
   purpose, each with its reason. Read the docs build configuration (`mkdocs.yml`, a Docusaurus
   config, `conf.py`, a Jekyll `_config.yml`), any script that assembles the docs before publishing,
   the existing translations (for what has already drifted), and the contribution rules (whether
   translations are wanted, and who reviews them). Find out whether the docs build overlays translations on the source
   (an untranslated page then serves the original) or copies (it then goes missing).
2. **Record the source revision in every translated file,** so staleness is one version-control query.
3. **Ship a staleness check with the translations:** for each file, compare the recorded revision
   with the current source, and report which are behind and by how many changes; run it in CI and see
   it fail by changing a source page.
4. **Never translate what a reader types or a machine reads:** commands, flags, code, paths, package
   names, environment variables, configuration keys, identifiers, and error strings people search for.
5. **Keep the structure exactly:** the same headings, anchors and file names in the language's
   directory; never half-translate a page (a page that switches language two-thirds down reads as
   finished and is not).
6. **Check every link from where the translated file sits,** against the built output; build the docs
   and look at the switcher, navigation, search and a rendered page.
7. **Make it reviewable by someone who does not read the language:** what was mechanical, what is
   prose, what a native reader must check, and anything ambiguous in the source.