From paper-trail
Audit the bibliography registry for consistency via 19 mechanical invariants (I1-I19) covering state validity, slug uniqueness, UID format, PDF path normalization, file presence on disk, sha256 integrity, page-1 validation log coherence, state history monotonicity, attempt numbering, blocked-reason presence, citation reciprocity with SOTAs, PDF duplicates, terminal state escapes, RTFM OCR overdue. Trigger this skill whenever the user wants to audit the registry, fix obvious drift, check invariants, or run a coherence sweep. Use for `/paper-trail:doctor`, `/paper-trail:doctor --fix`, `/paper-trail:doctor --correlate-rtfm`. Triggers : "audit registre", "doctor", "vérifier invariants", "fix drift", "check le registre", "audit registry", "run doctor", "auto-fix invariants", "rapport invariants".
How this skill is triggered — by the user, by Claude, or both
Slash command
/paper-trail:registry-doctorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Wraps the paper-trail worker B's invariant doctor. Runs all 19 checks
Wraps the paper-trail worker B's invariant doctor. Runs all 19 checks (I1-I19) on the registry, reports violations classified by severity (ERROR / WARN / INFO), and offers auto-fix for safe cases.
The doctor is read-only by default. Auto-fixes (--fix) only apply
to invariants whose semantic is mechanically safe : I4 (path prefix
strip), I6 (sha256 recompute), I9 (attempt renumber), I5/I7 semi
(state → needs_reacquisition when PDF missing or page1 log broken).
Never decides anything semantic — that's sota-auditor.
/paper-trail:doctor or /paper-trail:doctor --fixhooks/hooks.json)sota-writer validates that all proposed refs are coherent before
using them in a SOTAThe skill delegates to the worker B Python CLI:
# Run all 19 invariants, severity ≥ info, no fix
python -m pipeline doctor
# Filter to errors only
python -m pipeline doctor --severity error
# Auto-fix safe invariants (I4, I6, I9, I5 semi, I7 semi)
python -m pipeline doctor --fix --severity warn
# JSON output for machine processing
python -m pipeline doctor --json
# Couche 5 — correlate with RTFM indexing failures
python -m pipeline doctor --correlate-rtfm
# Couche 5 (slow) — recompute sha256 on all PDFs to detect drift
python -m pipeline doctor --check-sha
| Inv | Severity | Description | Auto-fix |
|---|---|---|---|
| I1 | ERROR | state is a valid FSM state | no |
| I2 | ERROR | slug is unique across the registry | no |
| I3 | ERROR | uid has a valid prefix (doi:, arxiv:, isbn:, etc.) | no |
| I4 | WARN | pdf_path is properly relative (no 10_SOURCES/ prefix) | yes |
| I5 | ERROR | If state implies PDF, file exists on disk | semi (→ needs_reacquisition) |
| I6 | ERROR | pdf_sha256 is 64 hex chars (recompute if missing) | yes |
| I7 | ERROR | If page1_validated, the log is consistent | semi (→ needs_reacquisition) |
| I8 | ERROR | state_history is monotonic in at timestamps | no |
| I9 | WARN | acquisition_attempts[].n is strictly 1..N (no gap) | yes |
| I10 | ERROR | If blocked_human:*, blocked_reason is non-empty | no |
| I11 | WARN | Each cited_in[].name exists in vault | no |
| I12 | WARN | Each SOTA citation [[slug]] is declared in cited_in | no |
| I13 | WARN | pdf_sha256 is unique (no duplicates) | no |
| I14 | ERROR | No transition out of sota_cited_confirmed or retracted | no |
| I15 | INFO | awaiting_rtfm_ocr not older than 30 days | no |
| I16 | WARN/ERROR | RTFM failure mirrored (Couche 5, opt-in via --correlate-rtfm) | no |
| I17 | ERROR | PDF format defective (Couche 5, opt-in) | no |
| I18 | ERROR | sha256 drift between YAML and disk (Couche 5, opt-in --check-sha) | no |
| I19 | INFO | PDF image-only without alternative text source tested (Couche 5) | no |
Markdown report by default :
# Pipeline doctor — YYYY-MM-DD
## ERROR (N)
- I5 ref_slug : pdf_path inexistant sur disque
- ...
## WARN (N)
- I4 ref_slug : pdf_path préfixé "10_SOURCES/" (auto-fixable)
- ...
## INFO (N)
- I15 ref_slug : awaiting_rtfm_ocr depuis 47 jours, last check il y a 12j
- ...
Récap : N ERROR / N WARN / N INFO — N auto-fixable(s) avec --fix
JSON format with --json :
{
"violations": [
{"invariant": "I5", "ref_slug": "...", "severity": "ERROR",
"message": "...", "auto_fixable": false},
...
],
"summary": {"error": N, "warn": N, "info": N, "auto_fixable": N}
}
--fix only applies to invariants whose correction is semantically
safe. It NEVER auto-fixes :
blocked_reason empty) — humain must decide the reasonstate_history non-monotonic) — likely a bug, needs investigationFor these, the doctor reports them but the curator (you) handles them.
The plugin's hooks/hooks.json invokes pipeline doctor :
PostToolUse(Write|Edit) on **/refs/*.md → mini-check on the
edited ref (warn-level)SessionEnd → full doctor sweep (error-level)These are non-blocking by default — they emit warnings but don't fail
the session. To skip the SessionEnd doctor, set
RESEARCH_SKIP_END_DOCTOR=1.
User: "lance le doctor"
Skill: python -m pipeline doctor
User: "auto-fix les warn"
Skill: python -m pipeline doctor --fix --severity warn
User: "vérifie les invariants avec RTFM"
Skill: python -m pipeline doctor --correlate-rtfm --severity warn
User: "vérifie l'intégrité des PDFs"
Skill: python -m pipeline doctor --check-sha
sota-auditor, not registry-doctorsota-auditor
or citation-receiptsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub roomi-fields/paper-trail