doctor

name

doctor

description

Verify a repo meets the kampus-pipeline prerequisites before its first triage / report / write-code / ship-it run, and print a tiered pass/fail checklist with the exact fix command for each gap. The role `ctx doctor` plays for context-mode — turns "did I wire this up right?" from tribal knowledge into one checkable command. Trigger on "doctor", "preflight", "is this repo set up for the pipeline", "check pipeline prerequisites", "verify pipeline setup", "/doctor", or when adopting the pipeline in a foreign repo.

doctor

You verify that the target repo is ready to run the pipeline and hand back a checklist — you do not fix anything. Every gap is reported with the exact command that closes it; applying it is the operator's call (and most fixes mutate the repo — label creation, auth scopes — which is theirs to authorize).

The pipeline is repo-agnostic (ADR 0062): an adopter installs the plugin and it operates on their issues. Several skills hard-depend on environment the host repo must already provide — labels, gh auth, a CI signal — but nothing verifies that up front, so a first run otherwise fails deep inside a gh api call (e.g. labeling with a status:needs-triage that doesn't exist) instead of failing fast with a clear "this repo isn't set up" message. Worst case it half-applies: an issue gets created, then the label step errors, leaving an untracked issue outside the queue. This skill closes that window.

Running it

Resolve nothing by hand — the helper resolves the target repo itself (the standard CLAUDE_PIPELINE_REPO-else-current snippet) and runs every check:

claude-plugins/kampus-pipeline/skills/doctor/doctor.sh

It prints a tiered checklist and exits 0 only when every Tier-1 and Tier-2 check passed (Tier-3 gaps warn, never fail). Relay its output to the operator verbatim — the per-line ↳ fix: commands are the load-bearing part — then stop. Do not run the fix commands yourself.

What it checks

Tier	Check	Why it's here
1 — load-bearing	gh authenticated	every call is gh api; without auth nothing runs
	gh token has the project scope	the org's Projects-classic integration requires it (the reason the suite is REST-only, never GraphQL)
	the 15 required labels exist (status:* spine, type:* class, p* priority)	the intake skills key on them — report applies status:needs-triage, write-code picks status:triaged, etc. A missing one fails a run mid-gh api.
2 — gating	target repo resolves	a skill can't target a repo it can't name
	at least one CI workflow exists	ship-it Step 3 gates on checks-green; with zero checks that gate passes vacuously
3 — optional	@kampus/pipeline-cli resolves on npm	adr / review-plan reach for its decisions-index / epic-ledger tools via pnpm dlx as the published fallback (epic #994); absent → those stages degrade
	a run-evidence producer is defined	ship-it guard 2 runs strict when present, and degrades to checks-green when absent (ADR 0086) — so this is informational, not a failure

The load-bearing pair is auth + labels (Tier 1): get those wrong and the very first report → triage round trips into a raw GitHub API error. The Tier-2 pair keeps ship-it honest; Tier-3 only ever downgrades a single stage.

Conventions

• Read-only. The helper never mutates the repo — it reads state and prints fix commands. The fixes (gh label create …, gh auth refresh -s project) are for a human to run; surfacing them is the whole job.
• One run, one checklist. This is a preflight, not a repair loop — it does not re-check after a fix; the operator re-runs it.
• The required-label set in doctor.sh is the canonical one (name + color + description). If the pipeline's label dimensions change (see ../gh-issue-intake-formats.md §Pipeline labels), update the REQUIRED_LABELS table there so a fresh adopter gets the current set.