check-health
Check and repair the health of a Keelokit project's harness — rules without enforcers, enforcers that point nowhere, expired or incomplete exceptions, gaps in docs/context, malformed stories — and add
SKILL.mdskills/check-health/SKILL.md
GitHubDoctor — a rule without a check is a wish
Run
python3 .keelokit/bin/doctor.py
Fix by error type
| Error | Fix |
|---|---|
| MUST rule without an enforcer | Add the test, lint rule, hook or CI job that fails when the rule breaks, then list it in enforced_by. If nothing can check it, it is a SHOULD — downgrade it and say so. |
| Enforcer does not exist | Fix the path/name, or create the missing check. Never delete the rule to go green. |
| Enforced only by review | Acceptable for SHOULD; for MUST, find a computational check or tell the user it is weak. |
| Exception incomplete or expired | Ask the user: renew (new date, reason, approver) or remove it and comply. Never renew on your own. |
| docs/context missing / vague / untracked gap | Missing → /keelokit:plan-intake. Vague → ask for the number or name. Untracked gap → add its row to gaps.md. |
CI-1: a job without timeout-minutes, or a timeout / test timeout / retries raised |
Add the timeout. For a raise: undo it and split the job by kind of test or shard it (docs/ci.md); an exception only with the user's yes |
CI-2: a CI job missing from .keelokit/verify-map.toml, or a step it names that verify.sh lacks |
Add the job to the map with the verify step that runs it, or add the step to scripts/verify.sh; ci_only only for what can't run on a machine |
FMT-1: no eol=lf in .gitattributes, or no format:check |
Add * text=auto eol=lf (then pnpm format once, alone in its commit) and the script |
FLAKY-1: a timeout or retries raised in a test config |
Undo it; reproduce the intermittent failure, fix the race, add its row to docs/escapes.md |
| MIG-1: a migration that sorts before main's last, or two stories of a wave adding migrations | Rename the new one with a later timestamp after rebasing (never edit the applied ones); move one story to a later wave |
| DEBT-1: a ledger row malformed, "decided" without a recommendation, or reading as "known issue / later" | Fix it or decide it with a recommendation; a missing 'Needs the owner' section is added empty |
| Story errors | Fix front matter, file name, or unknown depends_on; remove any status field. |
| Invariant without a class, or a story naming an unknown one | Add class: <class> to the INV-nnn line in domain.md (how does it break? see the plugin's references/invariants.md); fix the story's invariants. A new invariant is a product rule: ask the user. |
Story touches a critical area without integrity, or two stories of one area share a wave |
Add integrity and the invariants it keeps; move one story to a later wave. Never shrink an area to go green. |
A done story touches a critical area without integrity (a warning: the code shipped before the area, or despite it) |
Add integrity and the invariants the code keeps to the story, with a test citing each (INV-1). |
| Done story's invariant not cited by a test (INV-1) | Delegate to the verifier: the test its class calls for, titled with the id. |
| Critical area points at a missing path | The code moved or went away: update .keelokit/critical.toml, don't delete the area unless the code is gone. |
| Escape row incomplete (ESC-1) | Fill in the class and the check that now catches it, or none — <why>. |
No main or origin/main (0 stories done, --scope exits 2) |
Fetch main: git fetch origin main; in CI, fetch-depth: 0 on the job's checkout. Never point the doctor at HEAD: a branch's own Story: trailers aren't done work (INV-005). |
doctor --scope fails |
Files outside touches → add them and re-check the wave, or split the change. Undeclared critical area → integrity + full mode. Acceptance tests edited outside test(<ID>): … → revert the edit; the verifier changes tests, openly. |
House rules (.keelokit/harness/) are inherited: don't edit them in the project. If one is wrong
for everyone, say so — it gets fixed in the Keelokit template and arrives with copier update. If
it is wrong only here, register an exception.
Adding a rule (after an incident or a repeated mistake)
- State it:
[MUST|MUST NOT|SHOULD] <actor> <verb> <object> <measurable qualifier>. - Write the enforcer first and show it failing on the bad case, passing on the good one.
- Add the entry to
.keelokit/rules.local.toml:id,level,rule,why(the incident in one line),enforced_by, andwhenif it only applies when some path exists. - Run the doctor; commit rule and enforcer together.
Profile drift. When the doctor says the repo shows a trait the profile lacks (or lists one
nothing backs), check the evidence, propose the updated kind/traits to the user, and write
.keelokit/profile.toml on their yes. A profile still unknown (an adopted repo) gets diagnosed
the way /keelokit:project-adopt does.
5. If the lesson applies to every product, tell the user it should move to the house rules in
Keelokit.
Registering an exception
Only with the user's explicit approval in chat. Add to .keelokit/exceptions.toml: rule,
reason, approver (the user's name), expires (a date; permanent only if the user says so).