What does PactKit Doctor diagnose?

It checks structural health (graphs and docs), stale architecture graphs, orphaned and missing specs, and configuration drift between pactkit.yaml and deployed files.

When should I expect a HEALTH: NEEDS ATTENTION result?

When any WARN or ERROR severity is reported across categories, indicating actionable issues such as drift, missing specs, or stale graphs.

How do I fix configuration drift?

Address the drift by syncing the configuration with deployed files using pactkit update, after which re-run the health check to confirm resolution.

pactkit-doctor

npx machina-cli add skill pactkit/claude-code-plugin/pactkit-doctor --openclaw

Files (1)

SKILL.md

2.5 KB

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. Structural Health

Run visualize to check architecture graph generation.
Run visualize --mode class for class diagram verification.
Check docs/test_cases/ existence.

2. Stale Architecture Graph Detection

Compare docs/architecture/graphs/*.mmd modification times against newest source file mtime.
If any graph file is older than the newest source file by > 7 days: report WARN.
Suggest: "Run visualize to refresh stale architecture graphs."

3. Orphaned and Missing Specs

Orphaned Specs (INFO): List spec files in docs/specs/ that have no matching entry in docs/product/sprint_board.md or docs/product/archive/.
Missing Specs (WARN): List story IDs found in Sprint Board that have no corresponding docs/specs/{ID}.md file.
Suggest: "Run /project-plan to create missing specs."

4. Configuration Drift Detection

Compare pactkit.yaml against deployed files in .claude/:
- Check if enabled agents match deployed agent files.
- Check if enabled rules match deployed rule files.
- Check if enabled skills match deployed skill directories.
Any mismatch: report ERROR with specific drift details.
Suggest: "Run pactkit update to sync configuration."

5. Infrastructure & Data

Verify .claude/pactkit.yaml exists and is valid.
Check Specs vs Board linkage (every board story should have a spec).
Check if tests/e2e/ is empty.

6. 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).

Source

git clone https://github.com/pactkit/claude-code-plugin/blob/main/pactkit-plugin/skills/pactkit-doctor/SKILL.mdView on GitHub

Overview

PactKit Doctor is a diagnostic tool that evaluates a PactKit project for health issues. It checks for config drift, missing files, stale architecture graphs, and orphaned specs to surface risks before they impact delivery. The resulting report guides maintenance across architecture, specs, config, and tests.

How This Skill Works

When invoked (init auto-check or standalone), it runs a structured set of checks: Structural Health via visualize, stale graph detection by comparing graph timestamps to the newest source file, orphaned and missing specs by cross-referencing docs/specs with the sprint board, and configuration drift by comparing pactkit.yaml against deployed files in .claude. It then outputs a categorized health report and ends with Health: OK or Health: NEEDS ATTENTION.

When to Use It

After project initialization to verify structure and readiness
When you suspect health issues or drift in the project configuration or architecture
If architecture graphs look stale or out of date
When there are discrepancies between specs and the sprint board (orphans or missing specs)
Before deploying or syncing to validate pactkit.yaml against deployed files and ensure drift is resolved

Quick Start

Step 1: Invoke the PactKit Doctor diagnostic to run the health checks.
Step 2: Review the structured report by category (Architecture, Specs, Config, Tests).
Step 3: Act on findings (refresh graphs with visualize, create missing specs, and update config with pactkit update) and re-run as needed.

Best Practices

Run visualize to verify and refresh architecture graphs when prompted by the report
Check docs/test_cases/ existence as part of the Structural Health checks
Triage issues based on severity levels (INFO, WARN, ERROR) and address critical drifts first
Use pactkit update to sync configuration when drift is detected
Keep pactkit.yaml and its deployed counterparts aligned to prevent future drifts

Example Use Cases

Graph Freshness: WARN if a graph file is older than the newest source file by more than 7 days; run visualize to refresh graphs.
Orphaned Specs: INFO reports specs in docs/specs/ with no matching entry in docs/product/sprint_board.md or docs/product/archive/.
Missing Specs: WARN lists Sprint Board stories with no corresponding docs/specs/{ID}.md file; run /project-plan to create missing specs.
Configuration Drift: ERROR shows mismatches between pactkit.yaml and deployed files in .claude; run pactkit update to sync configuration.
Healthy Run: All checks pass and report ends with Health: OK.

Frequently Asked Questions

Add this skill to your agents