moonwalk

The law this skill runs on: a guard whose reason is lost is a bug waiting to be reintroduced. "The tests pass, cut it" is a false-negative machine for exactly the code that matters most — a guard, threshold, branch, or test exists precisely for the case the suite does not cover (the race, the legacy row, the refusal path, the provider quirk; this repo's own history: PR #11's 7 bot-found bugs the suite passed, the 10-class state-machine checklist). moonwalk is the antidote: point it at an artifact whose reason is NOT in the diff, and it walks backward through git + the PR/incident + private/decisions + ~/.claude memory + docs/build-log/ to recover — with citation — the invariant it encodes, then renders a verdict that gates the cut. It is /raze's missing pre-pass: raze decides the cut (forward), moonwalk recovers the why (backward); they pipeline. Generation is free; knowing what you are about to destroy is the judgment.

Three hard invariants:

• Cite or declare UNKNOWN — never infer. A recovered reason MUST point to a real commit / PR / incident / decision / memory line. If no store yields one, the verdict is UNKNOWN, and UNKNOWN is a first-class, valuable output (Chesterton's fence stands — maximum caution), never a failure to paper over with a plausible guess. The agent's documented blind spot is confident-wrong rationalization of guards; this rule forbids it.
• Read-only except one approved pin. moonwalk investigates; it never edits the artifact (that is /raze's or your lane). Its only write is an approval-gated PIN of a recovered reason to private/decisions, so the excavation amortizes to once-ever. Never auto-writes, never touches code.
• Fires only when the reason is NOT locally visible. Auto-no-op the instant blame's own commit message or a nearby comment already explains it — excavating the self-evident is ceremony. moonwalk is scoped to the blame-dead-end case: a mechanical/moved/renamed line, or a reason that lives in a store git never linked.

/moonwalk <target> (default — recover the why + render the verdict)

Tiered, cheapest-sufficient. Fan the cross-store walk to a scout subagent; only the cited chain + the verdict return to main context (never the raw git/file dumps).

1. Pin the target + the no-op check. Restate the target as one concrete artifact (a file:line, a symbol, a guard/regex, a magic threshold, a config/allowlist key, a test). FIRST ask: is the reason already in the diff, a nearby comment, or the introducing commit message? If yes → STOP, report "self-evident, no excavation needed." Proceed ONLY if the reason is not locally visible.
2. Walk backward, escalating only on a dead-end. Tier 1: git blame then git log --follow -L -M -C to chase the line through moves/renames/reformats to the substantive introducing commit (skip mechanical refactor commits that blame stops at). If its message cites the reason → done. Tier 2 (dead-end): the PR/review thread, the incident or bug it fixed. Tier 3: private/decisions/Decision_NNN, the project's ~/.claude/.../memory/, docs/build-log/. Stop at the first tier that yields a CITED reason. Where stores were never cross-linked, reconstruct the join by correlating time + author + file + keyword — the link nobody wrote.
3. Name the invariant + the untested failure mode. In one line: the invariant the artifact encodes, and the specific failure that reappears if it is removed — the failure the test suite structurally does NOT see. If you cannot cite it, do not invent it (invariant 1).
4. Render the fence verdict — exactly one of three, each with its evidence chain:
   • KNOWN-DEAD — reason recovered AND no longer applies (the constraint/incident is gone). The only verdict that clears the artifact for a /raze cut.
   • KNOWN-LIVE — reason recovered AND still applies. Do NOT cut or alter the invariant; named so you can edit around it.
   • UNKNOWN — no reason recoverable from any store searched (name which). Fence stands; treat with maximum caution.
5. Route + offer to pin. KNOWN-DEAD → hand to /raze (now safe to evaluate as a cut). KNOWN-LIVE / UNKNOWN → block the cut, tell raze/the editor to keep-and-edit-around. Offer to pin the recovered reason to private/decisions (propose-on-approval; write only that one record, explicit git add <path>). Log the verdict + whether it blocked a cut to ~/.claude/moonwalk/recoveries.md (the essentialness metric — see Rules).

/moonwalk audit <file|module>

Read-only. Sweep the file/module for UNKNOWN-provenance constructs — guards, magic numbers/thresholds, # do not/workaround comments, state-machine branches, allowlist entries — that have no traceable reason, running step 2's walk on each (cheapest tier only). Emit the map /raze consumes as its pre-pass: per construct, its verdict (KNOWN-DEAD safe-to-evaluate / KNOWN-LIVE keep / UNKNOWN watch) + the one-line cited reason or the explicit "no source found." Propose and write nothing. The "what here is safe to touch, and what is a live or unknowable fence" preview — mirrors /raze audit.

Rules

• Cite or UNKNOWN, never infer: the cardinal rule. A reason without a citation is not a reason; UNKNOWN is the honest, actionable verdict, never upgraded to KNOWN to look decisive (mirrors /raze's "unknown reason is a reason to keep").
• Read-only except an approved pin: moonwalk never edits the artifact and never auto-writes. The single permitted write is one approval-gated private/decisions record; the report is otherwise the only output.
• Auto-no-op on the self-evident: only fires on the blame-dead-end / through-moves / cross-store case. A moonwalk that runs on code whose reason is in its own commit message is ceremony — say so and stop.
• Tiered, stop at the first cited reason: escalate blame → PR/incident → decision/memory/build-log only on a dead-end (burn-aware; the deep walk is for the genuinely mysterious fence, which is exactly when it pays).
• Lane discipline: moonwalk recovers the WHY (backward); /raze decides the cut (forward); /simplify optimizes survivors; /code-review checks the new edges. moonwalk feeds raze and NEVER cuts. A project fact worth keeping beyond the pin → /burn rent; a preference → /taste; do not write CLAUDE.md or TASTE.md here.
• Trigger by construction, not by memory: the indispensable path is moonwalk as /raze's mandatory pre-pass (no cut proposed without a verdict on the target) and the guarded-edit gate (fires before editing a guard / threshold / state-machine branch / allowlist entry). Standalone invocation is the fallback. (The raze-side hook — a verdict requirement in /raze step 2 — is a one-line follow-up edit to raze.md, not self-executing from here.)
• Essentialness metric (the honesty hook): log each recovery + whether it blocked a cut to ~/.claude/moonwalk/recoveries.md. The grade is reintroductions prevented per month: >0 = paying rent (the cheapest insurance against your most recurrent, most test-invisible bug class); 0 over a month = ceremony, and moonwalk should itself be /raze'd. Its target is driving /raze's add-back rate toward 0.
• Shared-tree safety: ~/.claude/commands/ may live outside git, so the report is the record; pins use explicit git add <path>, never -A, and never rewrite history on a shared branch (parallel-session discipline).

Scope guard: moonwalk answers "why does this exist" (a static artifact's provenance) — NOT "when did this behavior change" (a dynamic bisect needing a runnable reproducer). That bisect is a deliberately separate, un-built function; do not bolt it on. Keeping the blade single-edged is what makes it indispensable.