Current state
Docs name files, commands, and identifiers that no longer exist, and nothing catches it until a reader wastes time on a dead reference. The justfile's status recipe invokes a hub-cli subcommand the binary does not define, and it still runs green because nothing checks it.
These are lookups rather than judgement calls, so they should fail a check instead of waiting for someone to read carefully. hub already runs scripts/check-banned-terms.sh and scripts/check-lint-inheritance.py from prek, so both the pattern and the wiring exist.
Ideal state
- A check fails when a tracked markdown file names a repo-relative path that does not exist
- It fails when a
just recipe invokes a subcommand the binary does not define
- It reports, without failing, every ADR whose status line claims the decision is implemented, so a human can confirm the code is actually there
- It runs from prek alongside the existing checks, and from
just check
scripts/README.md describes each check, and the description matches what the script does
Open decisions
- Whether to also flag backticked identifiers in
docs/ with no hit anywhere in the source. This would have caught several real cases, but many identifiers legitimately name external things. Measure the false-positive rate against the current docs before committing to it; if it is noisy, leave it to the handoff skill's judgement scans instead
Out of scope
- Anything requiring judgement, which belongs in the handoff skill rather than a script
- Scanning GitHub issue bodies. This runs offline in a pre-commit hook and must not depend on the network
Starting points
scripts/check-lint-inheritance.py — the existing Python check to model, including how it reports failures
prek.toml — where hooks are wired in
justfile — the status recipe naming a subcommand that does not exist
QA plan
- Run the script against hub as it stands — expect it to flag the
just status recipe
- Add a line to a doc naming
docs/does-not-exist.md, run the script — expect a failure naming the file and the line number
- Remove that line, run the script — expect a pass
- Commit a change touching a markdown file — expect the hook to run from prek without being invoked by hand
- Read
scripts/README.md against the script's actual behaviour — expect every described check to exist and every implemented check to be described
Done when
A doc naming a path that does not exist, or a just recipe naming a subcommand that does not exist, fails a check that runs from prek.
Current state
Docs name files, commands, and identifiers that no longer exist, and nothing catches it until a reader wastes time on a dead reference. The
justfile'sstatusrecipe invokes ahub-clisubcommand the binary does not define, and it still runs green because nothing checks it.These are lookups rather than judgement calls, so they should fail a check instead of waiting for someone to read carefully. hub already runs
scripts/check-banned-terms.shandscripts/check-lint-inheritance.pyfrom prek, so both the pattern and the wiring exist.Ideal state
justrecipe invokes a subcommand the binary does not definejust checkscripts/README.mddescribes each check, and the description matches what the script doesOpen decisions
docs/with no hit anywhere in the source. This would have caught several real cases, but many identifiers legitimately name external things. Measure the false-positive rate against the current docs before committing to it; if it is noisy, leave it to the handoff skill's judgement scans insteadOut of scope
Starting points
scripts/check-lint-inheritance.py— the existing Python check to model, including how it reports failuresprek.toml— where hooks are wired injustfile— thestatusrecipe naming a subcommand that does not existQA plan
just statusrecipedocs/does-not-exist.md, run the script — expect a failure naming the file and the line numberscripts/README.mdagainst the script's actual behaviour — expect every described check to exist and every implemented check to be describedDone when
A doc naming a path that does not exist, or a
justrecipe naming a subcommand that does not exist, fails a check that runs from prek.