speckit.companion.doctor

Pipeline Doctor

Say what actually happened in a run — and where the record, the display, or the run's own claim is at fault. Everything here is recomputed, never read off a prior verdict: a run that claimed it was drift-clean gets checked against a fresh drift computation, not believed.

Read-only. It creates, modifies, and deletes nothing. Never halts — it always exits 0, and a check that crashes becomes that check's skip reason while the rest still run. Retroactive — every core check derives from .spec-context.json and the spec's own documents, so it produces a meaningful verdict on a spec created long before this command existed.

Prerequisites

• Verify Python is available by running python3 --version.
• If python3 is not available, warn the user and skip: [companion] Warning: python3 not detected; skipped doctor. Do not fail the host command.

Execution

Run the doctor from the repository root. With no argument it examines the active spec, resolved the same way every capture call resolves it:

python3 .specify/extensions/companion/scripts/doctor.py

Name a spec explicitly, or sweep every spec in the repository:

python3 .specify/extensions/companion/scripts/doctor.py --feature-dir specs/<NNN>-<slug>
python3 .specify/extensions/companion/scripts/doctor.py --all

Add --json for the machine-readable report (stable top-level keys: checks, findings, bleed, drift, completion, chat), and --chat for the deep transcript audit described below.

What it checks

Each check reports whether it ran, was skipped (always with a reason), or is not applicable. A check that could not look never prints as clean — the summary counts checks, not just findings.

• record — steps that started and never finished, tasks checked off in tasks.md with no journal entry, task finishes clustered into one burst (journaling that was batched, so the per-task durations mean nothing), and steps closed by the wrong author.
• triage — the "status says one thing, the pipeline bar offers another" symptom, resolved into exactly one of two verdicts: records disagree with each other (a capture defect — the stepper is derived from history[], so a missing step-level complete is why it will not advance) or records are consistent (look at the display).
• bleed — where one step did the next step's work: plan content in the spec, a task checklist in the plan, implementation code in the task list, one task list living in two documents, source files committed before implement started, and a pre-implement step that outlasted implement itself.
• drift — re-runs the drift computation and shows its work: which capability, which files, which commits. Every flag is classified real, self-inflicted (the only changes are records the companion writes during a run), suspect baseline (the comparison commit is not an ancestor of HEAD, or the change is a rename git can follow), or unknown (the baseline could not be reached — never reported as clean). A recorded drift-clean claim the recomputation contradicts is reported as a false claim, with both sides and their timestamps.
• completion — when a spec did not land as completed, which of four things happened: the write was refused (with the writer's own reason), it reported success and never arrived, it landed and the display disagrees, or completion was never attempted at all.
• verification — whether the run actually executed anything before implement closed. Running the project's own checks is an instruction with nothing observing it, so a run can write code, tick off a task naming a test, and finish having proven nothing. An implement step that closed with no executed check recorded against the run is reported. A spec that never reached implement reports no record, never a problem.
• artifact — whether each step left behind the file it declared it would write. Every author node names its output in writes:, and the build collects those into a manifest of what a run of this pipeline must produce; a step that quietly stops writing its document otherwise closes exactly like one that wrote it. Reported as a warning, never a gate: the manifest describes the pipeline as built today, and a spec on disk may have been produced by an earlier one. An artifact the size budget is allowed to fold away is not judged, and a step that produced none of what this pipeline declares reports no record — it ran some other pipeline.
• template — whether tasks.md still has the shape it was generated with: user-story phases containing waves, ⟶ Wait join lines and checkpoints intact. A file whose story sections were renamed or flattened is reported with the offending headings named.
• trace — what the run self-trace recorded: capture calls that failed and why, call counts, payload sizes, and how many times each file was rewritten. Calls that could not resolve a spec at all land in the repo-level unattributed log and are reported here too, because a spec whose own trace is clean is not evidence that nothing broke while it was being built. The marker naming calls that succeeded but could not be written to the trace is read before the check decides a spec has no trace evidence — a run that could not write into its spec directory has no trace file at all, and that is precisely the run with something to report.
• chat (only with --chat) — reads the AI session transcript covering the run's recorded time window and explains causes: work tried and failed, work retried, and steps that stopped rather than failed. It surfaces claims the run made that the recomputation contradicts, and quantifies waste — narration, repeated commands, the same file rewritten over and over. Claude-first; on a provider that keeps no transcript it prints one line and exits successfully. The transcript format is not a stable contract, so treat this as a builder's tool, not a product promise.