cartographer

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cartographer Skill

Cartographer audits the persistent instruction layer of the current project and reports findings in the conversation. The automated SessionStart path handles periodic background audits; this skill is for on-demand use.

## Setup

```bash
set -uo pipefail
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
source "$PLUGIN_ROOT/scripts/lib/onlooker-project-key.sh"
source "$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh"
source "$PLUGIN_ROOT/scripts/lib/cartographer-events.sh"
source "$PLUGIN_ROOT/scripts/lib/cartographer-collect.sh"
source "$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh"
```

Load config and resolve project context:

```bash
REPO_ROOT=$(onlooker_project_repo_root "$(pwd)")
cartographer_config_load "$REPO_ROOT"

PROJECT_KEY=$(onlooker_project_key "$(pwd)")
CARTOGRAPHER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}/cartographer/$PROJECT_KEY"
mkdir -p "$CARTOGRAPHER_DIR"
```

## Invocation Modes

### `/cartographer` — full audit

Runs all phases in the foreground. Acquires the audit lock (non-blocking).

```bash
LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"

if ! cartographer_lock_acquire "$LOCK_FILE"; then
  echo "An audit is already in progress."
  echo "Run \`/cartographer --status\` to follow it, or \`/cartographer --force\` to restart."
  exit 0
fi

export CARTOGRAPHER_DIR CARTOGRAPHER_TRIGGER="manual" ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}"
bash "$PLUGIN_ROOT/scripts/run-audit.sh"
cartographer_lock_release "$LOCK_FILE"
```

After the audit completes, read findings and render them to the conversation grouped by severity (see Rendering section).

### `/cartographer --verbose` — all findings

Shows ALL known findings (new + previously seen) from `$CARTOGRAPHER_DIR/findings/`, including ones already resolved — that is what makes this the verbose view. Resolved findings are tagged so "did my fix take?" is answerable here. Does NOT re-emit bus events — renders to in-conversation output only.

```bash
echo "## Known Cartographer Findings"
echo ""
for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
  [[ -f "$f" ]] || continue
  jq -r '(if .resolved == true then "[RESOLVED] " else "" end) as $r |
    "\($r)**[\(.severity | ascii_upcase)]** \(.type) — \(.description)\n  Files: \(.file_a // "n/a") / \(.file_b // "n/a")\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null
done
```

### `/cartographer --status` — audit status

Reports the running state and last completion time. No LLM calls.

```bash
echo "## Cartographer Status"
if cartographer_lock_is_held "$CARTOGRAPHER_DIR/audit.lock"; then
  pid=$(cat "$CARTOGRAPHER_DIR/audit.lock" 2>/dev/null)
  echo "Audit running (PID $pid)"
else
  echo "No audit in progress"
fi

if [[ -f "$CARTOGRAPHER_DIR/last_audit_at" ]]; then
  ts=$(cat "$CARTOGRAPHER_DIR/last_audit_at")
  echo "Last completed: $(date -r "$ts" 2>/dev/null || date -d "@$ts" 2>/dev/null || echo "$ts")"
fi

runs=$(ls "$CARTOGRAPHER_DIR/runs/" 2>/dev/null | wc -l | tr -d ' ')
total=$(ls "$CARTOGRAPHER_DIR/findings/" 2>/dev/null | wc -l | tr -d ' ')
open=$(cat "$CARTOGRAPHER_DIR/findings/"*.json 2>/dev/null \
  | jq -s '[.[] | select(.resolved != true)] | length' 2>/dev/null || echo 0)
echo "Open findings: $open"
echo "Total findings on disk: $total (includes resolved)"
echo "Audit runs recorded: $runs"
```

### `/cartographer --force` — force restart

Kills the running audit (if any) and starts fresh.

```bash
LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
if cartographer_lock_is_held "$LOCK_FILE"; then
  pid=$(cat "$LOCK_FILE" 2>/dev/null)
  if [[ -n "$pid" ]]; then
    kill "$pid" 2>/dev/null || true
    sleep 1
  fi
  rm -f "$LOCK_FILE"
fi
# Then proceed as a normal full audit
```

### `/cartographer --type=<type>` — single finding type

Narrows the audit to one finding type: `contradiction`, `dead_rule`, `stale_ref`, `scope_collision`, or `undocumented_entity`. Export `CARTOGRAPHER_TYPE_FILTER` before running.

```bash
export CARTOGRAPHER_TYPE_FILTER="stale_ref"
```

Analyzers that cannot produce the requested type are skipped entirely, so this is cheaper than a full audit — each skipped analyzer is an LLM call not made. Useful for re-checking one class of drift after fixing it without paying for the rest.

One caveat, because the saving is not uniform: `contradiction` and `dead_rule` come out of a single LLM pass, so asking for either runs that pass and discards the other type from the results. Requesting one of those two costs the same as running both; the other three types are genuinely skippable.

From onlooker-community/ecosystem, MIT.

More from onlooker-community/ecosystem