| name | pactkit-doctor |
| description | Diagnose project health status |
| model | haiku |
PactKit Doctor
Diagnostic tool for project health — config drift, missing files, stale graphs, orphaned specs.
When Invoked
- Init (auto-check): Verify project structure after initialization.
- Standalone diagnostic when project health is in question.
Severity Levels
| Level | Meaning |
|---|
| INFO | Informational, no action required |
| WARN | Potential issue, should be addressed |
| ERROR | Critical mismatch, must be fixed |
Protocol
1. Run Deterministic Checks
Run pactkit doctor to perform automated diagnostics:
- Orphaned/Missing Specs: Cross-references
docs/specs/ vs board + archive.
- Config Drift: Compares
pactkit.yaml items vs deployed files.
- Stale Graphs: Checks
docs/architecture/graphs/*.mmd mtimes vs source files.
2. Structural Health (Manual)
- Run
visualize to check architecture graph generation.
- Run
visualize --mode class for class diagram verification.
- Check
docs/test_cases/ existence.
3. Infrastructure & Data
- Verify
pactkit.yaml exists (at .claude/pactkit.yaml) and is valid.
- Check if
tests/e2e/ is empty.
4. Report
Output a structured health report grouped by category:
| Category | Check Item | Severity | Description |
|---|
| Architecture | Graph Freshness | INFO/WARN | Stale if > 7 days |
| Specs | Orphaned Specs | INFO | Specs without board entries |
| Specs | Missing Specs | WARN | Board stories without specs |
| Config | Drift Detection | ERROR | pactkit.yaml vs deployed |
| Tests | Test Suite | INFO/WARN | Test runner status |
End with overall status: "Health: OK" (no WARN/ERROR) or "Health: NEEDS ATTENTION" (WARN/ERROR found).