ArcadeAI Explain
Translate safeword's dense artifacts and current state into plain English — what this is, why it matters, what to do next. Read-only. It reads the artifact or state; it never changes it.
The one rule
Obey SAFEWORD.md "Talking to the user": lead with the answer, front-load the
load-bearing words, end with a **Next:** line. Strip safeword's internal
vocabulary — no "phase / gate / sizing / propose-and-converge / done_when /
verdict." If you must name one, define it in the same breath. Write for a
teammate with zero safeword context.
Pick the target
/explain takes an optional target:
- No target → current state: "where am I, what's next" (the default).
- A ticket id or slug → that ticket: what it builds, why, where it stands.
- A gate-block or verdict → what it's asking for and how to clear it.
Code diffs and PRs are out of scope — base Claude already explains those well.
Default — current state ("catch me up")
Gather the durable trail safeword already keeps, then narrate it. Run:
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
NS_ROOT="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR")"
# What you're on now: the last re-entry line names the current ticket + Next
tail -3 "$NS_ROOT/re-entry.md" 2> /dev/null
# Fallback when re-entry is empty: in_progress tickets (not epics)
for f in "$NS_ROOT"/tickets/*/ticket.md; do
[ -f "$f" ] || continue
grep -q "^status: in_progress" "$f" && ! grep -q "^type: epic" "$f" && echo "$f"
done
# What landed recently
git log --oneline -5 2> /dev/null
The last re-entry line is the authoritative "current ticket" — prefer it over the
in_progress scan (a repo can carry many in_progress tickets at once). From that
ticket's ticket.md, read the # H1 goal, the work-log tail, and any unchecked
- [ ] items under done_when (what's left). Then emit ONE brief:
You're on
<slug (ID)>—<one plain line of what it is>. Landed:<recent commits, plainly>. Left to do:<the unchecked items, plainly>. Next:<the next concrete step>.
If no ticket is active, say so plainly and point at the ticket list (INDEX.md)
plus the recent commits. Keep it to a few lines.
A named ticket or artifact
Resolve $NS_ROOT, then read $NS_ROOT/tickets/<id-or-slug>*/ticket.md and translate, in order:
- What it is — the goal in one plain sentence (no "scope / done_when" labels).
- Why it matters — the problem it removes.
- Done looks like — the
done_when, rewritten as observable outcomes. - Where it stands — status in plain words: "not started", "in progress, tests next", "shipped".
End with Next: the immediate action.
A gate-block or verdict
Read the message — the last block shown, or what the user pasted. Say, plainly:
- What happened — which rule fired, in one sentence.
- Why — the reason it exists, one clause.
- How to clear it — the exact next action.
Translate "phase gate / LOC gate / done gate" into the thing the user actually has to do, not the internal name.
Output shape
One scannable brief, not an essay. For an oversized artifact (an epic spec), lead with a one-liner and offer "want the detail on X?" rather than dumping it all.
Summary
/explain makes safeword legible on demand — current state by default, any
artifact on request — without diluting the precise artifacts themselves. It
reads; it never writes.