checkup — the canonical project checkup ("botte doctor")

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Commands, APIs and runtime behavior described below are conditional examples for a compatible upstream installation; they are not evidence of execution in this package.

The upstream command assembles a documented review sequence and prints a verdict based on the checks that ran. Verify detector availability and evidence; a verdict does not prove complete coverage or an optimal procedure.

python -m skills.checkup.cli            # current dir
python -m skills.checkup.cli <project> --json
python -m skills.checkup.cli . --pr-comment   # Markdown verdict for a PR comment
python -m skills.checkup.cli . --doctor       # + machine scan + ranked top-3 opportunities
python -m skills.checkup.cli . --doctor --fresh   # re-scan for local LLM backends (not cached)

--doctor — the one-verb assembly

--doctor is checkup plus two things it doesn't otherwise do:

• machine scan — is a local LLM backend reachable (LM Studio/Ollama)? via [[llm-backends]] audit(); reads the cached registry unless --fresh.
• ranked top-3 opportunities — fixes from [[fix]] find_fixes(), ranked by estimated token cost (highest first), plus any remaining drift items, capped at 3.

Both feed a one-line verdict: ✅ sain when there's no drift and a local backend is active, or ⚠️ N optimisation(s), ~X tokens d'opportunités otherwise. Pure assembly of existing modules — no new skill, no new report format.

Sequence (cheap → deeper)

1. policy — is .botte/policy.md committed? (shared rules for devs/agents)
2. directives — CLAUDE.md/AGENTS.md health + stale path refs
3. metrics — LOC per component + always-on cost + savings framing
4. infra — hardware/software/MCP cluster tips (+ ASCII diagram)
5. duplication — stdlib AST duplicate-function scan
6. security — taint / data-flow scan ([[fallow-like]] TaintAnalyzer), CWE-tagged; high-severity findings are considered for drift review.
7. docs review — recurring Markdown due/current status from [[docs-steward]]. Never-reviewed bootstrap files are informational; an expired interval or explicitly watched content change becomes drift.
8. knowledge integrity — when a Wiki or second brain is detected, verify its structural maintenance contract and propose reviewable changes. P1/P2 gaps become drift; the audit remains read-only and makes no semantic-cleanliness claim.
9. drift — MCP wired? directives stale/oversized? policy missing? security?

Then points at the deep code audit (secrets/dead-code) for when you want it.

Why

A component update or another dev/agent introduces drift — stale directives, unwired MCP, an oversized CLAUDE.md, a missing policy. /checkup catches all of the configured sequence. Confirm which checks ran and treat any missing evidence or detector as a reported limitation.

On pull requests

--pr-comment prints a verdict-first Markdown comment (carrying a stable marker so a bot can edit it in place), including the security section — so the taint/data-flow section can be reviewed with the rest of the CI output. The 🧦 Botte Checkup (PR) GitHub Action (.github/workflows/botte-pr-checkup.yml) runs this on every PR and can post/update a comment via gh when that separate workflow, dependencies, credentials and permissions are configured. The workflow is not included in this catalog; verify its behavior before reuse.

Related: [[preflight]] (enforces prefer-local every turn), [[infra-advisor]], [[metrics]], [[trends]], [[directives-audit]], [[bootstrap]].