skills.rest
julien-m
julien-mCOMMUNITY
Explore all skills by this author →
GitHub

spec-doctor

Audits LiveSpec project health by detecting spec drift, missing traceability anchors, and stale mappings.

Updated Mar 11, 2026
Search Tags:#cli#traceability#coherence validation#health audit#spec drift#livespec#spec-doctor
One-click install
npx skills add https://github.com/julien-m/livespec --skill spec-doctor-julien-m
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spec-doctor
Source: https://github.com/julien-m/livespec/tree/main/.agent-sync/skills/spec-doctor
Command: npx skills add https://github.com/julien-m/livespec --skill spec-doctor-julien-m

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Specs and code drift apart over time: implementation maps go stale, mapped files lose their @spec traceability anchors, hooks stop enforcing validation, and visual evidence becomes orphaned. This Skill runs a project-level health audit that surfaces all of these issues in one report. ## Core Features & Use Cases - Project Health Audit: Runs livespec doctor to orchestrate coherence validation and report findings by severity, category, and code. - Traceability Detection: Extracts R3.2 INFO findings listing mapped source or test files missing @spec(FR-xxx) or @spec(AC-xxx) anchors, even when the audit exits 0. - Safe Cleanup: --fix-plan proposes cleanup read-only, while --apply-cleanup refuses destructive deletion of specs, tests, or evidence. - Use Case: Before a release, run the audit in strict mode to promote warnings to errors, then route fixable drift to /spec-fix and focused verification to /spec-check. ## Quick Start Ask the AI to run the spec-doctor health audit on this LiveSpec project and list every missing @spec traceability anchor from the JSON report.

Frequently Asked Questions about spec-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a LiveSpec project for spec drift?▼

Run `livespec doctor` from the project root. It orchestrates coherence validation and reports findings by severity and category, exiting 0 when clean, 1 when drift is found, and 2 when the .specs directory is missing.

How do I find files missing @spec traceability anchors?▼

Run `livespec doctor --format json` and filter findings with code R3.2. These INFO findings list every mapped source or test file lacking the expected @spec(FR-xxx) or @spec(AC-xxx) anchor, even when the overall audit passes.

What is the difference between livespec doctor and livespec validate --coherence?▼

livespec doctor is the project-level health audit that orchestrates the lower-level coherence validator. It adds checks for traceability anchors, stale implementation maps, runner coverage, hooks, lifecycle metadata, and visual evidence orphans.

Does spec-doctor modify files when fixing drift?▼

No by default. The --fix-plan flag is read-only and only proposes cleanup actions, while --apply-cleanup refuses destructive deletion of active specs, tests, or evidence until a future archive contract exists.

Why does livespec doctor exit with code 1?▼

Exit code 1 means the audit found drift: at least one error, or warnings promoted to errors under --strict mode. Inspect the findings list, then run /spec-fix for fixable implementation drift or update runner, hook, or lifecycle metadata.

Related Skills

Explore More Software Engineering Skills→
thewoolleymanthewoolleyman

livespec-seed

Authors the initial livespec specification tree for a new project from a chosen template.

Community
Intermediate
b12consultingb12consulting
2

specs-review

Audit spec-driven documentation health and detect code-spec drift.

Official
Intermediate
Coverage-CreativesCoverage-Creatives

Pre-Commit Hooks

Automate code quality checks with Git hooks, lint-staged, Husky, and Commitlint.

Official
Advanced
anssipanssip
26

openspec-verify-change

Verify implementation alignment with specs, tasks, and design artifacts.

Community
Intermediate