health

name	health
description	Check planning directory integrity. Find and fix corrupted state.
allowed-tools	Read, Write, Bash, Glob, Grep, AskUserQuestion
argument-hint	[--repair]

STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► HEALTH CHECK                               ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:health — Planning Directory Diagnostics

You are running the health skill. Your job is to validate the integrity of the .planning/ directory, report problems, and suggest targeted fixes.

This skill runs inline. It is read-only by default, but offers an optional auto-fix flow for common corruption patterns (see the Auto-Fix section below).

References

• references/questioning.md — Questioning philosophy for diagnostic probing
• references/ui-brand.md — Status symbols, banners, checkpoint boxes

Argument Parsing

Check if the user passed --repair:

• --repair: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.
• No flag: Use the interactive AskUserQuestion flow as described below (default behavior).

---

How Checks Work

Health checks are now CLI-driven via verify health. The check-pattern template (${CLAUDE_SKILL_DIR}/templates/check-pattern.md.tmpl) describes the classification model (PASS/FAIL/WARN/INFO) used by the CLI internally.

Read ${CLAUDE_SKILL_DIR}/templates/output-format.md.tmpl for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.

---

Checks

Run all health checks via the CLI:

pbr-tools verify health

Parse the JSON output. The CLI returns an object with:

• checks: array of { name, status, message, fix_suggestion } for each check
• summary: { passed, failed, warned, total }

For each check result, record the status (PASS/FAIL/WARN/INFO) for display in the output table.

If the CLI fails, display a branded ERROR box: "Failed to run health checks. Run pbr-tools verify health manually to diagnose." and stop.

---

Auto-Fix for Common Corruption Patterns

After running all 10 checks and collecting results, if any of the following auto-fixable issues were found, offer to fix them.

Auto-Fixable Patterns

CRITICAL: Execute each fix immediately when found. Do not defer fixes to a later step.

Pattern	Detection	Fix Action
Missing STATE.md frontmatter	Check 5 finds STATE.md without --- block	Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status)
STATE.md phase_slug mismatch	Check 5/7 finds phase_slug doesn't match current phase directory name	Correct phase_slug to match the actual directory name in .planning/phases/
Missing config.json	Check 1/2 finds no .planning/config.json	Create with default config template (same as /pbr:setup defaults)
Orphaned .active-skill file	Check 10 or general scan finds .planning/.active-skill older than 1 hour	Delete the stale .active-skill file
Empty phases directory	Check 3 finds .planning/phases/ missing	Create the directory: mkdir -p .planning/phases
STATE.md over 150 lines	Check 5 finds STATE.md exceeds 150 lines	Compact the ## Accumulated Context section, keeping only the last 3 entries

Auto-Fix Flow

After displaying health check results, if any auto-fixable issues were detected:

CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.

mkdir -p .planning/backups
cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md

This ensures the user can recover the original STATE.md if the fix produces incorrect results.

1. Count the auto-fixable issues.

   If --repair flag was passed: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."

   Otherwise: Present the choice:

   Use AskUserQuestion: question: "Found {N} auto-fixable issues. How should we handle them?" header: "Fix?" options: - label: "Fix all" description: "Apply all {N} fixes automatically" - label: "Review each" description: "Show each fix and confirm individually" - label: "Skip" description: "Do nothing — just report"

2. If "Fix all" (or --repair): Apply all fixes in order, then display a summary:

   Auto-fix results:
   - Fixed: {description of fix 1}
   - Fixed: {description of fix 2}
   ...
   

3. If "Review each": For each fixable issue, display:

   Issue: {description}
   Fix: {what will be done}
   

   Then ask via AskUserQuestion (yes/no): "Apply this fix?"

   • If yes: apply and display - Fixed: {description}
   • If no: skip and display - Skipped: {description}

4. If "Skip": Do nothing, continue to the rest of the output.

---

Bonus: Recent Decisions

After all checks, look for .planning/logs/decisions.jsonl. If it exists, display the last 5 entries as - {date}: {summary} (phase {N}). If it does not exist, skip silently.

---

Reference: skills/shared/error-reporting.md for branded error output patterns.

Completion

After all checks complete, display the branded result:

If all checks passed (0 failures):

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓                      ║
╚══════════════════════════════════════════════════════════════╝

{N} checks passed, {M} warnings



╔══════════════════════════════════════════════════════════════╗
║  ▶ NEXT UP                                                   ║
╚══════════════════════════════════════════════════════════════╝

**Continue your workflow** — planning directory is healthy

`/pbr:progress`

<sub>`/clear` first → fresh context window</sub>



**Also available:**
- `/pbr:continue` — execute next logical step
- `/pbr:settings` — adjust settings

If failures found:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠                      ║
╚══════════════════════════════════════════════════════════════╝

{N} checks passed, {F} failures, {M} warnings



╔══════════════════════════════════════════════════════════════╗
║  ▶ NEXT UP                                                   ║
╚══════════════════════════════════════════════════════════════╝

**Fix the failures** listed above, then re-run

`/pbr:health`

---

Anti-Patterns

1. DO NOT modify files without user consent — auto-fix requires explicit user approval via AskUserQuestion
2. DO NOT auto-repair anything silently — always present fixes and let the user decide
3. DO NOT skip checks that depend on missing files — report the dependency failure and continue
4. DO NOT treat warnings as failures in the summary count — only count FAIL items
5. DO NOT read full plan/summary contents — frontmatter and existence checks are sufficient
6. DO NOT fail silently — every check must produce an explicit PASS, WARN, or FAIL
7. DO NOT suggest running destructive commands — fixes should be safe, targeted edits