Skip to main content
command CX Codex

speckit.companion.doctor — Claude Code command: how to install

speckit.companion.doctor audits spec run health by catching incomplete steps, unverified runs, and drift. Read-only, retroactive, and never halts on failures.

MIT ★ 110 updated 2026-11-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/speckit.companion.doctor.md
Open on GitHub

What speckit.companion.doctor does

The command inspects spec execution health using .spec-context.json and existing spec documents. It recomputes checks from scratch instead of trusting previous claims, verifying drift calculations and completion statuses directly against disk state. The tool runs strictly read-only and always exits with code 0. Any failing check is recorded as skipped while the rest proceed.

It catches tasks marked complete without journal entries, pipeline triage discrepancies, step bleed where later stages spill into earlier documents, and steps closed without promised output files or executed checks. With --chat, it parses AI session transcripts to identify retried prompts, repetitive rewrites, and wasted output.

Python 3 must be available in your environment; without python3, the script issues a skip warning and cleanly yields execution without failing the caller.

What it helps with

  • detect unfinished steps and unjournaled tasks in tasks.md
  • recompute drift to flag discrepancies against prior claims
  • identify implement steps closed without executing verification checks
  • audit AI transcripts for loops and redundant file rewrites

Example prompts for the agent

  • Check active spec health using speckit.companion.doctor
  • Run speckit.companion.doctor --all --json
  • Audit spec transcript with speckit.companion.doctor --feature-dir specs/001-core --chat

How to install speckit.companion.doctor

Manually: put the files in place

.claude/commands/speckit.companion.doctor.md

Call it with /speckit.companion.doctor. For all projects use ~/.claude/commands/

Questions about speckit.companion.doctor

How to install speckit.companion.doctor in Claude Code?

Save the command file to your repository at .claude/commands/speckit.companion.doctor.md.

What does speckit.companion.doctor do?

It audits spec execution history, discovering step bleed, untracked changes, missing verification tests, and mismatched pipeline statuses.

What happens if Python 3 is missing?

The command requires python3 to run; if not detected, it prints a warning and skips the doctor checks without aborting the host pipeline.

Source text

speckit.companion.doctor.md · MIT
---
description: "Report on a spec's run health — unfinished steps, unjournaled tasks, step bleed, drift you can judge, a step that closed having verified nothing, a step that closed without the file it promised, and why completion did not land (read-only, retroactive, never halts)"
---

# 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:

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

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

```bash
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.
- **built** — whether Companion has caught up with this project's own spec, plan and tasks templates. Spec-kit's override folder and presets reach stock runs at once; Companion follows them from the copy its last pipeline build wrote under `.specify/companion/built/`. A team template with no copy yet, or a copy older than the template it came from, is reported with a note to rebuild. A project with no team template has nothing to judge.
- **agents** — how Spec Kit laid out each agent this project installed (skills or commands, and where), when Companion is installed, any of them missing its commands, which happens because Spec Kit registers an extension for the active integration only, and whether the `specify` CLI is on PATH for headless dispatch and hooks. It is about the project, so a run over many specs reports it once.
- **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.

## The self-trace

Every capture and drift call records itself to `specs/<NNN>/.trace.jsonl` — one line, success or failure, with the reason verbatim. This costs no extra call and adds nothing to any command body; the scripts the pipeline already runs write it from the inside. The file is size-capped, ignores itself on first write, and is read by nothing but this command. Deleting it is safe; a missing trace is a skipped check, never an error.

## Debug mode

Setting `debug: true` in `.specify/companion.yml` is read by the body renderers, but **the renderers are build-time tools and are not part of a release** — so on an installed project this switch currently does nothing. Treat it as a maintainer tool: from a source checkout, `python3 speckit-extension/scripts/build.py --debug` renders the bodies with per-section timing instrumentation, and a plain rebuild removes it again. Never commit an instrumented body.

To instrument a run on an installed project today, attach the instruction as a node hook in your own `.specify/companion.yml` — that mechanism ships and takes effect on the next dispatched command. See the `debug-timing` hook in this repository's own config for the wording.

## Reporting

Report the doctor's output as it stands. Do **not** fix what it finds as part of running it — the doctor reports, and acting on a finding is a separate, deliberate decision. If it finds nothing, say so along with which checks were skipped and why, so "clean" is never mistaken for "did not look".

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
speckit.analyze speckit.analyze runs a read-only pass over spec.md, plan.md and tasks.md, then prints a report on contradictions, duplicates and requirements that no task covers. CX Codex GP ChatGPT ★ 110repo stars speckit.companion.living-sync speckit.companion.living-sync updates living specs to match current working-tree changes in a single pass. Modifies existing spec files without regenerating them from scratch. CX Codex +1 ★ 110repo stars speckit.implement The speckit.implement prompt turns the plan in tasks.md into an ordered implementation run. It is listed for Claude Code and Codex. CX Codex GP ChatGPT ★ 110repo stars publish-all publish-all releases all four project components at once: the spec-kit extension, VS Code extension, Claude Code mod, and Copilot canvas. Runs only if changes are ready and pass QA checks. CX Codex +1 ★ 110repo stars speckit.plan The speckit.plan subagent turns a feature specification into research and design artifacts. Use it when you’re ready to plan implementation. CX Codex +1 ★ 110repo stars speckit.taskstoissues speckit.taskstoissues turns the task list from tasks.md into numbered GitHub issues while keeping dependency order. Handy when the plan is already broken into tasks but the tracker is empty. CX Codex +1 ★ 110repo stars submit-catalog-update submit-catalog-update is a Claude Code skill that generates and files an Extension Submission issue for the companion extension in spec-kit. It is used for minor and major version updates. CX Codex +1 ★ 110repo stars feature-clip feature-clip builds SpecKit Companion looping clips through capture, composition, rendering, and media sync for the site and documentation. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open