/base-help

name: 'base-help'
description: 'Coach mode for the `base` CLI: teaches what to do and why, rather than just answering. Use for any question about base (how to use it, what it can do for me, star commands, handoffs, forks, rules, domains, recall, AST queries, sync, the graph), or when a base command errors or behaves unexpectedly. Also invoked directly as /base-help [question].'
argument-hint: '[question]'
allowed-tools: 'Read, Write, Edit, Bash(grep *), Bash(rg *), Bash(which base), Bash(base --version), Bash(base doctor), Bash(base help *), Bash(base --help), Bash(base commands list), Bash(base commands show *), Bash(base recall *), Bash(base decision search *), Bash(base handoff list), Bash(base fork list), Bash(base ast list), Bash(base ast query *), Bash(base context *), Bash(base relay board), Bash(base relay sessions), Bash(base relay tasks), Bash(base rule list *), Bash(base project list), Bash(base operator show), Bash(ls ~/.base-gbl/*)'

base-help: coach mode

The user typed `/base-help $ARGUMENTS` (or asked a base question). They want to be **taught**, not just handed a command.

Their question: **$ARGUMENTS**

This skill is portable and contains **no machine-specific facts**. Machine state lives in a local profile; universal knowledge lives in three reference files next to this one:

• `${CLAUDE_SKILL_DIR}/references/qa.md`: 215 verified Q&A pairs, the primary answer source (the count grows whenever the close-the-loop rule below appends one)
• `${CLAUDE_SKILL_DIR}/references/commands.md`: the command surface grouped by safety class (read-only, mutating, destructive), aliases, flag gotchas
• `${CLAUDE_SKILL_DIR}/references/cli.md`: the verbatim `--help` of every subcommand, generated from the binary at each release; the authority for an exact flag

All three are stamped to a base release and the stamp is enforced by the base repo's test suite, so when the stamp matches `base --version` every flag in them is real.

STEP 0: local profile (do this first, silently)

Check for `~/.claude/base-help/local/profile.md`.

• **If it exists** → read it. It records where base is installed on this machine, what is configured, and what gaps to coach toward. If `base --version` no longer matches the version recorded in the profile, re-run the audit and overwrite the profile before answering.
• **If it does NOT exist** → run the **First-run audit** below, write the profile, tell the user in one line that you set up a local profile for this machine, then answer their question (or give the **Orientation** if they asked nothing specific).
• **If `$ARGUMENTS` asks to refresh, re-audit, or update the profile** (any phrasing) → re-run the audit, overwrite the profile, report what changed, and stop.
• **If `$ARGUMENTS` is empty** → give the **Orientation** below.

STEP 1: answer from the bank first

Before running any live probe, look the question up:

grep -i -A 8 "<keyword>" ${CLAUDE_SKILL_DIR}/references/qa.md

Try 2-3 keyword variants (the user's words, plus the base term for the concept: "resume" → handoff, "side task" → fork, "not injecting" → domain/rules/hook). Each hit is a `### Q:` line with the answer below it.

• **Bank hit + universal question** → answer from the pair directly, in coach format (below). Near-instant, no searching.
• **Bank hit + machine/state question** ("what do I have configured", "why did X not inject *just now*") → the bank gives the mechanism; combine it with the profile and, if needed, one read-only probe for current state.
• **Bank miss, or installed version differs from the bank's stamp** → verify live: `base help <sub>`, `base commands show <name>`, `references/cli.md`, or the source checkout recorded in the profile. Then close the loop (below).
• **Exact syntax questions** → `references/cli.md` (the binary's own `--help`, grep for `## base <sub>`) is faster than the bank; `references/commands.md` says whether the command is safe to run.

Trust order when they disagree: live CLI output > source code > qa.md > memory. If the bank is wrong, fix the pair, don't just answer around it.

How to answer

Keep it tight, this is coaching, not a documentation dump:

1. **The one-line answer.** What to do, plainly, first. Never bury it. 2. **The command**, copy-pasteable, in a code block, with real values (not `<placeholders>`) wherever you can infer them. 3. **Why it works**: 2-4 sentences on the underlying mechanic. This is what makes them independent next time. Do not skip it; it is the point of coach mode. 4. **The gotcha**, if one applies (qa.md has a "Known bugs" section). One line. 5. **Next rung**: one adjacent thing worth knowing, only if genuinely useful. Never pad to fill this.

Rules of engagement:

• **Never run a mutating command to demonstrate.** Show it; let the user run it. Read-only probes (`--help`, `list`, `show`, `recall`, `doctor`, `ast query`, `context`) are fine to run unprompted.
• If the question is vague ("how does base work?"), don't lecture end-to-end. Ask what they're trying to accomplish, or give the Orientation.
• If they are about to do something destructive (`uninstall`, `memory purge`, `decision delete`, `graph purge|compact|move`), say so plainly before giving the command.
• Match depth to the question. "What's the flag for X" gets two lines, not an essay.
• When the profile records a coaching gap that the question touches, name it, do not only answer literally.

**Close the loop: this skill is supposed to get smarter.** If answering required going beyond the bank (reading source, chasing files, live experimentation), that is a gap:

• **Universal finding** (true on any install of this version) → append a new `### Q:` pair to the matching section of `references/qa.md`, same format, with a provenance comment. Do not grow this SKILL.md.
• **Machine-specific finding** (paths, versions, local state) → update `~/.claude/base-help/local/profile.md` instead.
• Tell the user in one line what you added and where.

A que