check-resolvable

Files (1)

• SKILL.md

SKILL.md (first lines)

# /check-resolvable — Reachability Audit

A thin wrapper around `~/.claude/tools/check-resolvable.py`. The script does the deterministic scan; this skill interprets the result and recommends action.

**Per CLAUDE.md latent-vs-deterministic rule, the audit itself is deterministic** (regex over a fixed text corpus, no LLM judgment). The optional second pass — "which of these orphans actually matter" — is latent and lives in this skill, not the script.

## When to invoke

- Weekly cron via `/loop` or `/schedule`
- Before any CLAUDE.md cleanup or skill refactor
- After adding ≥3 new skills/guides/tools (signal that the routing surface has grown)
- After any workflow-config sync that may have moved files

## Process

### Step 1: Run the deterministic scan

```
python3 ~/.claude/tools/check-resolvable.py --human
```

Add `--list-reachable` to also see what's known-good. Add `--out report.json` to persist the full JSON.

### Step 2: Interpret orphans

For each orphan reported:

- **Genuine orphan** (dead capability) — the file exists but nothing references it; safe to retire or document for removal
- **False positive** (script's pattern missed a reference) — the file IS reachable but the script's regex didn't catch it; flag for adding the reference pattern to `check-resolvable.py`
- **Pending wire-up** (newly added, not yet wired) — the file was just created and hasn't been added to RESOLVER.md or CLAUDE.md yet; add the reference now

### Step 3: Resolve

- Genuine orphans: propose removal (don't delete without user approval per your safety doctrine)
- False positives: edit `check-resolvable.py` to add the missing pattern; re-run
- Pending wire-up: add the routing entry to RESOLVER.md or the trigger to CLAUDE.md; re-run

### Step 4: Report

Summarize:
- Total capabilities counted
- Number reachable vs. orphan, by kind
- Action taken for each orphan (retired / wired / pattern-fixed / left as-is)
- Any pattern-detection gaps in the script that should be fixed

## Limitations of the deterministic scan

The audit catches *file-level* reachability — whether the artifact is referenced. It does NOT catch:

- **Stale references** (a guide is referenced but its content is outdated) — different problem, addressed by quarterly CLAUDE.md health check
- **Logical reachability** (a skill is referenced but the conditions for invocation never fire) — addressed by trigger evals (`~/.claude/tools/skill-trigger-evals.py`)
- **Cross-project references** (project CLAUDE.md files reference user-scope skills) — partial: this scan only walks `~/.claude/`, not per-project COMP files

## Extensions (mode of thinking)

Reachability audits are an instance of the broader principle: **"trust the determinism."** Any time the workflow accumulates capability beyond what a human can mentally enumerate, automated reachability becomes the only way to keep the system honest. Extensions:

1. **Cross-project reachability** — extend the corpus to include every project's CLAUDE.md / MEMORY.md / PLAN.md / ORIENT.md. Catches cases where a project references a skill that no longer exists.
2. **Reverse direction** — instead of "are all capabilities reached?", ask "are all references valid?" (catches typos: CLAUDE.md says `/check-resolveable` but the skill is `/check-resolvable`).
3. **Health over time** — run the audit weekly and log results; surface the *trend* in orphan count. If orphans grow week-over-week despite no removals, something is decaying.
4. **Trigger eval coupling** — pair this with `skill-trigger-evals.py`. Reachability says "this skill is wired in"; trigger evals say "this skill actually fires on the right inputs." Both are needed for a healthy routing layer.

## Sources

- Garry Tan, *Resolvers: The Routing Table for Intelligence* — "First run found 6 unreachable skills. Fifteen percent of the system's capabilities were dark."
- Workflow dialectic review — the binding constraint that this audit must be a script, not an LLM-driven skill.

From griffinhilly/claude-code-synthesis, MIT.

More from griffinhilly/claude-code-synthesis