ssot-doctor

SSOT Doctor

Find where SSOT/ is wrong, missing, contradictory, or hard to use, and say exactly how far your check went. The model you check against is memory-model.md.

1. Agree on the scope

If SSOT/README.md has no ssot_format: 3 (usually a v2 layout), review read-only and offer migration with $ssot-bootstrap. Do not write to it.

The scope is the whole SSOT, one area or file, a catch-up from a given commit, or mining one area's protected rules (follow ../ssot-bootstrap/references/mining.md, with separate agents). State it in your report. Findings, and any statement that something is healthy, cover only that scope.

2. Run the mechanical check

From the repository root, run python3 <this skill's directory>/assets/scripts/ssot-check.py SSOT. It reports errors (a missing entry point, broken links or heading anchors, a malformed invariants register, a confirmed invariant changed without a new dated source) and warnings (oversized files, v2 leftovers, and mentioned files that git says were removed or moved). It cannot tell whether a statement is true or readable. That part is your review; the removal warnings are a good place to start. Exit code 3 means the run was incomplete: the checker crashed or could not examine part of the tree. That is never a pass, and any errors it did list are still real. Errors in files outside your scope do not stop the review of your scope. Report them separately.

3. Review the scope

• Truth. In each document, pick the statements a future task would act on, such as contracts, state ownership, commands, defaults, and "planned" labels, and check each against the code, configuration, and tests; a fresh helper that did not write them checks best. Look hardest at two kinds: statements with "all", "only", "every", "never", or "always", which often miss an exception; and statements taken from a design document, an ADR, or a code comment, which may describe intent the code does not implement. Fix or qualify each one that does not hold, and label unbuilt intent as planned. Start with areas that changed recently in git log.
• Consistency. Look for one fact stated two different ways, and for superseded decisions still presented as current.
• Invariants. Every row links to an explanation inside SSOT/. No rule changed meaning or status without a recorded user decision. Each candidate meets the admission rule in memory-model §5; candidates are not a backlog for the user to confirm.
• What does not belong. Flag restated code, proof of a single task, edit history, and status about the documents themselves.
• Usefulness to a newcomer. If you can start a helper with a fresh context, give it three to five real tasks for this repository. Include at least one normal path, one failure or recovery case, and one boundary judgment ("may I change X?"). The helper starts from SSOT/README.md and reads only SSOT/. Then check its key answers against the code, configuration, and confirmed decisions: an answer that matches a wrong document is a finding about the document. Report which tasks you used. If no helper is available, say that this check was your own reading.