How do I fix a failing local check?

1. Question
2. Answer
3. Script
4. Tested by
5. See also

This is one branch of the PR monitoring loop. The other branch is addressing review comments.

1. Question

A check failed. How do I find what it was, fix it, and prove the fix?

2. Answer

Read the report. compass check writes build/output/local_checks/report.md. Its Fix these first section names each failing check, the command that reproduces it, the command that fixes it, and the tail of the check's own log:
```
./compass.sh check
sed -n '/## Fix these first/,/## Every check/p' build/output/local_checks/report.md
```
Re-run just the failing check. Every check has an id, printed in the report's Every check table:
```
./compass.sh check --only component-drift
```
Read the full log when the tail is not enough. Each check writes one file, named after its id:
```
less build/output/local_checks/logs/component-drift.log
```
Diagnose by category:
- Drift (component-drift, model-drift, tangle-*) → regenerate the artefacts the check names, then commit them.
- Compilation → fix the source file.
- Test failure → fix or update the failing test, then run ./compass.sh test run -R <name> for a single suite.
- Formatting → clang-format -i on the files the report names.
- Documentation → fix the page or the link; site-page names the page.
- Cross-platform (enum-attributes, exported-types) → the defect is one only MSVC reports; fix the header, no Windows build needed.
Re-run the whole gate and confirm it is green:
```
./compass.sh check
```
If the failure is on main instead. The twelve retired pull-request workflows kept their push to main trigger, so a defect that escaped the runner shows there. Find the run and read the failing step:
```
gh run list --branch main
gh run view <run-id> --log-failed
```
The fix is the same, and the local check then reproduces it: ./compass.sh check --only <id>.

3. Script

compass check and the report it writes. The GitHub fallback is the bare gh CLI.

4. Tested by

The runner's own suite, build/scripts/tests/test_local_checks.py, pins the decision tree: a documentation change must not reach the compiler, a header change must, and a path nobody classified must ask for everything.

5. See also

CI workflows and local checks — the decision tree and the check catalogue.
PR Raise — the skill that runs the gate before raising.
How do I monitor a PR until green? — the surrounding loop.
How do I address PR review comments? — sibling branch.
PR Shepherd.