Claude Health Check

Trigger

• Keywords: health check, .claude check, config audit, lint .claude, claude health, plugin sync, version drift, upgrade check, doctor

When NOT to Use

• Code review (use /codex-review-fast)
• Doc review (use /codex-review-doc)
• Security review (use /codex-security)

Scope

Workflow

[--scope] → Select modules → Scan → Classify → Report → Fix suggestions
               │                                  │
       ┌───────┴───────┐                     P0/P1/P2
       ▼               ▼                    + fix commands
  Hygiene (C1-C7)  Sync (S1-S3)

Hygiene Module — Checks (7 items)

Check 1: Junk Files

find .claude/ -name ".DS_Store" -o -name "*.zip" -o -name ".tmp*" 2>/dev/null

• Has results → P1: List files, suggest deletion
• No results → ✅

Check 2-3: .gitignore

ls .claude/.gitignore 2>/dev/null || echo "MISSING"

Missing → P1. If exists, read content and compare required items:

Missing any → P2

Check 4: Naming Consistency

# Scan all skill subdirectories
for dir in .claude/skills/*/; do
  if [ -d "${dir}reference" ]; then echo "INCONSISTENT: ${dir}reference"; fi
done

Has reference/ (singular) → P2, suggest renaming to references/

Check 5: README Count Sync

# Count actual items
ls .claude/commands/ 2>/dev/null | wc -l
ls .claude/skills/ 2>/dev/null | wc -l
ls .claude/agents/ 2>/dev/null | wc -l
ls .claude/rules/ 2>/dev/null | wc -l
ls .claude/hooks/*.sh 2>/dev/null | wc -l

Extract counts from README.md, compare. Mismatch → P2

Check 6: Command-Skill Pairing

Scan all skills/*/SKILL.md, exclude these types, then check for corresponding command:

Remaining skills without command → P1

Check 7: Cache Size

du -sh .claude/cache/ 2>/dev/null

• > 50M → P2, suggest cleanup
• ≤ 50M → ✅

Sync Module — Checks (S1-S3)

Only runs when --scope sync or --scope all (default).

S1: Version Check

Plugin version resolution (priority order):

.claude-plugin/plugin.json → package.json → "unknown"

Plugin source location (same as /install-rules Phase 1):

Glob: ~/.claude/plugins/**/sd0x-dev-flow/rules/auto-loop.md
Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/rules/auto-loop.md
Fallback: @rules/auto-loop.md (plugin-relative)

S2: Component Classification

For each managed component (rules, hooks, scripts), compute 3 hashes and classify:

manifest_hash  = manifest[category][filename].hash    # null if missing
local_hash     = git hash-object --no-filters <local-path>  # null if file missing
plugin_hash    = git hash-object --no-filters <plugin-path>  # source of truth

Classification table (read-only diagnostic; maps to install-rules states for delegation):

Managed inventory (hardcoded):

S2.5: Override Safeguard Checks

7 checks for project override files (e.g., auto-loop-project.md):

Policy contradiction detection: For each ## <heading> section the override restates, extract the backticked check commands (/codex-review-fast, /codex-review-doc, /precommit) from the same-heading section of the base auto-loop.md and require the restated section to keep every one of them. A verbatim copy therefore never flags; only a restatement that drops a command its base section carries is P1. (The base's Auto-Trigger table was retired by R3 — code/doc routing now lives in the unheaded terminal-invariant paragraph, which the exact-##-heading override mechanism cannot restate, so routing itself is not overridable and is out of this check's scope.) No restated section → check passes vacuously.

Override drift detection: First check whether the project file has active content. Two forms count, and the distinction matters because the scaffold ships its ## headings live: a non-empty, non-comment body line under any heading, or a heading that carries its own value (## Plan Review: enabled, ## Git Memory: enabled — for these settings the heading is the value, so there is no body to look for). A bare scaffold heading with nothing but comments beneath it is an empty slot, not an override. The live Precedence: header is preamble material and never activation. A scaffold whose sections are all still commented out is skipped: drift means "the base changed since you wrote your overrides", and there are none, so reporting it on a fresh install is a false positive rather than a finding. Otherwise read the <!-- Based on: <base>.md @ <hash> --> comment and derive the base file from the comment's own filename — git hash-object --no-filters .claude/rules/<base>.md | cut -c1-7. The base must not be hard-coded: R8 distributes testing-project.md alongside auto-loop-project.md, so a fixed auto-loop.md comparand would check a testing override's hash against the wrong rule and report drift that does not exist. If the derived base file is missing, drift is undefined rather than zero — report it through check #3's missing base branch (P1) and do not emit a drift finding. Both checks must cover every shipped override file, not just auto-loop-project.md: an active testing-project.md whose testing.md has been deleted would otherwise fall through both. If the hashes differ, the base has been updated since the override was authored. Uses blob hash for content-level comparison; accepts legacy commit-style hashes (any 7+ hex chars) during backward-compat transition.

S3: Settings Compatibility

Check both settings.json and settings.local.json (precedence: settings.local.json > settings.json). A hook entry in either file satisfies the integrity check.

Settings file precedence: settings.local.json overrides settings.json at runtime. When delegating S3 fixes, use /install-hooks --local if the issue is in settings.local.json.

Legacy path detection:

Grep for: "\.claude/hooks/[^"]+\.sh"  (without leading "$CLAUDE_PROJECT_DIR")
Applied to both: settings.json and settings.local.json

Fix Tiers

Only applies when --fix-safe or --fix is specified alongside sync scope.

Category-specific safe fix delegation:

Why hooks/scripts OUTDATED is report-only in safe tier: /install-hooks and /install-scripts use skip/force semantics (no manifest-aware smart merge). Only /install-rules has 7-state classification for safe auto-update.

S3 settings fix delegation: All settings mutations delegate to /install-hooks (sync module never writes JSON directly).

--fix tier: Delegates all actionable states (including CONFLICT, LEGACY) to /install-* commands which handle interactive resolution.

Argument conflict: --fix and --fix-safe are mutually exclusive. If both specified, error.

Instruction Budget Module

Claude Code adds up every always-loaded instruction file at launch and warns when the sum passes a total limit. The check reproduces that accounting (2.1.281) so the user learns it here first, with the plugin's share separated out. Runs under --scope budget and --scope all (the default), never under --scope hygiene or --scope sync. The script is the plugin install's copy — $CLAUDE_PLUGIN_ROOT when its real path lies outside the audited repository — never a copy inside the audited repository (.claude/scripts/, scripts/), because this check is read-only and the repository controls those files. No plugin install found → skip the module with a note:

REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "instruction budget: skipped — not in a git repository"; exit 0; }
PR="${CLAUDE_PLUGIN_ROOT:-}"
case "$(cd "$PR" 2>/dev/null && pwd -P)/" in "$(cd "$REPO_ROOT" && pwd -P)/"*|/) PR="" ;; esac
[ -n "$PR" ] && [ -r "$PR/scripts/instruction-budget.js" ] \
  && node "$PR/scripts/instruction-budget.js" --root "$REPO_ROOT" --plugin-root "$PR" \
  || echo "instruction budget: skipped — no plugin install outside this repository"

The script is read-only; it never edits or moves a file. A missing script skips the module with a note rather than guessing a total.

Plugin Copies (S4)

Runs with the Sync module (--scope sync and --scope all). Report-only: it lists where copies of this plugin's content come from, so a stale or second copy is seen before it is mistaken for the plugin's current text. It never deletes, moves or edits a copy.

Prompt Audit (manual step)

Claude Code 2.1.283 and later audit instruction files for outdated or conflicting content with /doctor prompt-audit [path] (alias /checkup prompt-audit). It covers CLAUDE.md, CLAUDE.local.md and AGENTS.md plus the rules and skills under .claude/ and ~/.claude/, reports findings with proposed edits, and changes nothing until asked. This skill does not run it: it is the host's command, and the report names it as the manual next step. Its findings on this plugin's content are handled by owner:

Output

# .claude/ Health Check Report

## Hygiene Summary (C1-C7)

| Item | Status | Notes |
|------|--------|-------|
| Junk files | ✅/⛔ | ... |
| .gitignore | ✅/⛔ | ... |
| Naming consistency | ✅/⛔ | ... |
| README count | ✅/⛔ | ... |
| Command-Skill | ✅/⛔ | ... |
| Cache size | ✅/⛔ | ... |

## Sync Summary (S1-S3)

### S1: Version
| Check | Status | Detail |
|-------|--------|--------|
| Manifest | ✅/⛔ | Found / Missing |
| Plugin version | ✅/⛔ | 2.0.3 == 2.0.3 / 1.8.12 → 2.0.3 |
| Manifest keys | ✅/⛔ | Complete / Missing: hook_scripts, scripts |

### S2: Component Status
| File | Category | Status | Action |
|------|----------|--------|--------|
| auto-loop.md | Rules | OUTDATED | `/install-rules auto-loop` |
| security.md | Rules | OK | — |
| stop-guard.sh | Hooks | MISSING | `/install-hooks stop-guard` |
| ... | ... | ... | ... |

### S3: Settings Compatibility
| Check | Status | Detail |
|-------|--------|--------|
| Hook paths | ✅/⛔ | Modern / Legacy found |
| Retired guard mode | ✅/⚠️ | absent / STOP_GUARD_MODE found (dead config) |
| Entry integrity | ✅/⛔ | All matched / N missing |
| Orphan entries | ✅/⛔ | None / N orphans |

## Budget Summary (B1-B3)
| Check | Status | Detail |
|-------|--------|--------|
| B1 Total | ✅/⚠️ | 89,472 / 150,000 chars; plugin share 89,472 |
| B2 Per-file | ✅/⚠️ | None over / .claude/rules/big.md (152,000) |
| B3 Lessons in rules/ | ✅/⚠️ | None / .claude/rules/lessons.md → move to .claude/sd0x-dev-flow-lessons.md |

## Plugin Copies (S4)

| Origin | Version | Note |
|--------|---------|------|
| Local install | 5.0.0 | from `.sd0x/install-state.json` |
| Marketplace plugin | 5.0.0 / not checked | |
| claude.ai synced skills | — | names shared with plugin skills, or none |

Next step (manual): `/doctor prompt-audit` — findings on plugin-shipped content are report-only.

## Statistics

| Category | Count |
|----------|-------|
| Commands | N |
| Skills | N |
| Rules | N (installed) / N (managed) |
| Hooks | N |

## Issues

### P1
- [Issue] → [Fix recommendation / command]

### P2
- [Issue] → [Fix recommendation]

## Gate
✅ All Pass / ⛔ N issues need fixing

Verification

• Hygiene: All 7 checks executed (when scope includes hygiene)
• Sync: S1-S3 checks executed (when scope includes sync)
• Budget: B1-B3 reported, or the skip note printed (when scope is budget or all)
• Each check has clear ✅/⛔ status
• P1 issues have specific fix commands
• S2 classification covers every file in the managed inventory above (29 today: 13 rules, 7 hooks, 9 scripts)
• Fix delegation uses targeted file names (not --all)

References

• references/best-practices.md — Best practices for .claude/ directory structure

Examples

Input: /claude-health
Action: Scan hygiene (7 items) + sync (S1-S3) → Generate consolidated report

Input: /claude-health --scope sync
Action: Scan S1-S3 only → Report version drift + component status

Input: /claude-health --fix-safe
Action: Scan all → Auto-fix safe items → Delegate to /install-* → Report

Input: Is my plugin up to date?
Action: Trigger sync check → Report version + component drift