Cp Skill Health Check

Commonplace Health Check

EXECUTE NOW

Use this skill when a Commonplace KB has missing skills, missing or failing commonplace-* commands, or commands that work in one shell but not in an IDE or agent runtime. It applies both to installed KBs, where shipped content lives under kb/commonplace/, and to the Commonplace source repository, where shipped content lives directly under kb/.

Target symptom: $ARGUMENTS

Do not modify files during diagnosis. Report the evidence and the smallest repair. Apply a repair only when the user asked for one.

Step 1 — Locate the project and classify the layout

From the workspace root, inspect:

pwd
test -f AGENTS.md && echo "AGENTS.md: present" || echo "AGENTS.md: missing"
test -f CLAUDE.md && echo "CLAUDE.md: present" || echo "CLAUDE.md: missing"
test -d kb/commonplace && echo "layout: installed KB" || true
test -f pyproject.toml && test -d src/commonplace && echo "layout: source repo" || true
test -d .agents/skills && echo ".agents/skills: present" || true
test -d .claude/skills && echo ".claude/skills: present" || true

Interpretation:

• Installed KB: kb/commonplace/{notes,reference,instructions}/ exists.
• Source repository: pyproject.toml, src/commonplace/, and top-level kb/{notes,reference,instructions}/ exist.
• Neither: the wrong directory is open or commonplace-init has not run.
• .venv is not a Commonplace layout requirement. A project may still own one for unrelated dependencies.

Step 2 — Check the control plane and skill projections

Read the active root control-plane file and confirm it routes Commonplace commands by bare name. Then inspect the canonical health skill and the runtime projections:

test -f kb/commonplace/instructions/cp-skill-health-check/SKILL.md && echo "installed canonical skill: OK" || true
test -f kb/instructions/cp-skill-health-check/SKILL.md && echo "source canonical skill: OK" || true
test -f .agents/skills/cp-skill-health-check/SKILL.md && echo ".agents projection: OK" || true
test -f .claude/skills/cp-skill-health-check/SKILL.md && echo ".claude projection: OK" || true

If the canonical skill exists but the current runtime cannot discover its projection, commonplace-init may need to be rerun or the runtime may use another skill-discovery surface. Do not repair a Commonplace source checkout with commonplace-init; follow the source repository's AGENTS.md instead.

Step 3 — Check the uv tool installation and command ownership

On Linux/macOS:

command -v uv || true
uv tool list || true
uv tool dir --bin || true
command -v commonplace-init || true
command -v commonplace-validate || true
which -a commonplace-validate 2>/dev/null || true

On native Windows PowerShell:

Get-Command uv -ErrorAction SilentlyContinue
uv tool list
uv tool dir --bin
Get-Command commonplace-init -All -ErrorAction SilentlyContinue
Get-Command commonplace-validate -All -ErrorAction SilentlyContinue

Classify the result:

• uv missing: the installation prerequisite is absent.
• llm-commonplace absent from uv tool list: the user-level tool is not installed.
• Command exists inside uv tool dir --bin but bare-name lookup fails: the tool executable directory is missing from this process's PATH.
• Bare name resolves outside uv tool dir --bin: another install or a project venv shadows the user-level tool. Report every candidate from which -a or Get-Command -All.
• Only some declared commonplace-* commands exist: the tool installation is incomplete or stale after an entry-point metadata change; reinstall it.
• A fresh terminal resolves the command but the IDE or agent does not: the launch class did not inherit the updated user environment. Treat this as runtime environment propagation, not package absence.

Do not use uv tool install --force as the default repair for an executable conflict. First identify which installation owns the conflicting name and remove or reorder the stale owner.

Step 4 — Check legacy project-environment residue

Inspect only; do not delete:

test -f .envrc && sed -n '1,80p' .envrc || true
test -d .venv && echo ".venv exists; determine its owner before cleanup" || true

The exact .envrc generated by older Commonplace releases contained only:

export PATH="$PWD/.venv/bin:$PATH"
export UV_CACHE_DIR="$PWD/.uv-cache"

That exact file is obsolete after the user-level tool works in fresh processes. An edited .envrc must be reviewed manually. A .venv may hold the project's own dependencies; never classify it as removable merely because Commonplace no longer needs it.

Step 5 — Check package and validator health

If this is an installed KB:

commonplace-validate kb/commonplace/reference/commands.md

If this is the Commonplace source repository:

commonplace-validate kb/reference/commands.md
uv run pytest -q

Interpretation:

• Command not found: return to step 3.
• Import or dependency error: reinstall the uv tool. For an editable source install, metadata and dependency changes require uv tool install --reinstall --python ">=3.11" --editable . even though ordinary source edits do not.
• Validator runs: the command package is healthy; focus on skill discovery or launch-environment propagation.
• uv run pytest fails before tests start: the source project's dependency environment is unhealthy. pytest is a development dependency, not part of the Commonplace command tool.

Repair commands

Published install:

uv tool install --python ">=3.11" llm-commonplace
uv tool update-shell

Editable source install, run from the Commonplace checkout:

uv tool install --python ">=3.11" --editable .
uv tool update-shell

After uv tool update-shell, fully restart the shell, IDE, desktop agent, or service being tested. The shell update is durable and is not rerun at every shell start. In CI, configure a job-local uv tool executable directory and append it to $GITHUB_PATH; do not mutate a shell profile.

One uv tool installation supplies one active Commonplace version per OS user. Switching between published and editable sources changes the command implementation for every project under that user.

Step 6 — Report

Use this format:

Commonplace health check:
- Project root: OK / problem
- Layout: installed KB / source repo / problem
- Control-plane file: OK / problem
- Runtime skills: OK / problem
- uv tool installation: OK / problem
- Runtime PATH: OK / problem
- Command ownership: uv tool / conflict / missing
- Validator: OK / problem

Likely cause:
<one or two sentences>

Recommended fix:
<concrete next command or user action>

Evidence:
- <short command result>
- <short command result>

Maintenance observations:
- <legacy .envrc, unrelated .venv requiring owner review, stale skill copies, or "None">

List independent problems in this blocking order:

1. Wrong directory or missing initialized layout.
2. Missing canonical skill or runtime projection.
3. uv or the llm-commonplace tool is missing.
4. uv's tool executable directory is absent from the consuming process's PATH.
5. Another executable shadows the uv tool.
6. Package import, dependency, or validator failure.

Do not claim the installation is fixed unless the failing check passes in the same launch class that originally failed.