Diagnosing a bootstrapped repository

Report first, repair second, and only with approval. Drift is usually a deliberate edit, and silently reverting someone's deliberate edit is worse than the drift.

This skill assumes .bootstrap/manifest.json exists — it is what lets every check below tell "a file this tool wrote" from "a file somebody else wrote". Without that baseline every finding is a guess: use project-adopt instead.

An adopted repository is held to the adoption standard. verify.py reads the adopt: block of bootstrap.yaml, so a missing kb/, an unlinted pre-existing note, and a team composed of the project's own subagents are all expected rather than broken. Do not propose repairing an adoption into the shape a founding would have produced — that is the parallel-structure failure arriving late.

1. Structural check

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/verify.py

How to read the three categories:

• error — something is broken or missing. Worth fixing.
• warning — a convention has slipped. Worth raising, and worth asking about rather than assuming.
• note — a generated file has been edited since generation. Expected, and usually correct. Never "fix" a note without being asked to.

2. Environment check

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/preflight.py

Tools that were installed and have stopped resolving are the interesting result here. A tool the user never wanted is not a finding.

3. Template drift

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py --config bootstrap.yaml --dry-run

This compares the repository against the current templates. Three outcomes:

• updated — the template improved and the local file is untouched. Safe to apply.
• drifted — the local file was edited. Show the user the difference and let them decide; the local edit is more likely to be right than the template.
• conflict — a file exists that this tool never generated. Leave it alone.

Never pass --force on your own judgement. It discards the user's edits, and the only person who can weigh that trade is the user.

4. Report

One message, in this order:

1. What is broken (errors), with what each one blocks.
2. What has slipped (warnings), with the convention it slipped from.
3. What is safely upgradable, and what changed in the template.
4. What you are deliberately not touching, and why.

Then propose the repairs as a numbered list and let the user pick. Do not apply them as a batch on a single yes unless the user says so explicitly.

The failure signal worth naming

If the knowledge base has not been written to in weeks while the code has moved, that is the finding that matters — more than any frontmatter error. An unread, unwritten knowledge base is pure overhead, and the honest recommendation may be to simplify the structure rather than repair it.

Say that plainly when you see it. A doctor that only ever recommends more structure is not diagnosing anything.