explain-state

---
name: explain-state
description: >
  Summarize what nyann currently sees in this repo: stack detection,
  active profile, branching strategy, hook status, CLAUDE.md, and
  recent commits.
  TRIGGER when the user says "what does nyann think is set up here",
  "show nyann state", "explain the setup", "what's the current
  config", "what's the active profile", "describe this repo's
  nyann setup", "what's wired up", "show me the repo state",
  "/nyann:explain-state".
  Do NOT trigger on "what does this repo do" (that's a docs intent —
  route to CLAUDE.md / README), "is this repo healthy" (that's the
  `doctor` skill), or "what's in the X profile" (that's
  `inspect-profile`).
---

# explain-state

Read-only. Never mutates. Wraps `bin/explain-state.sh`.

## 1. Invoke

```
bin/explain-state.sh --target <cwd> [--json] [--profile <name>]
```

- **No args** → human-readable table, easy to read back to the user.
- **`--json`** → machine-readable JSON when the user wants to pipe
  it or you need structured fields for a follow-up operation.
- **`--profile <name>`** → override profile inference when the user
  names one explicitly.

## 2. Read the output aloud

The JSON has six blocks. When the user asks a general "what's the
state", summarize the highlights rather than dumping the whole
structure:

- **stack** → "Detected `<primary_language>`" + framework + package
  manager. Call out `confidence < 0.5` as "weak detection — might
  be worth confirming".
- **profile** → "Active profile: `<name>` (source: `<starter|user|
  team|unknown>`)". When source is `unknown`, say "couldn't infer the
  profile; CLAUDE.md doesn't reference one".
- **branching** → "Strategy: `<strategy>`; base branches: `<list>`".
  If null, profile isn't resolved.
- **hooks** → "Husky: `<bool>` / pre-commit.com: `<bool>` / nyann core
  hooks: `<bool>`". These are presence signals only — they tell you
  whether something's wired, not whether it's healthy. For health,
  route to `doctor`.
- **claude_md** → "CLAUDE.md present, `<bytes>` bytes, router markers
  `<bool>`". Mention the 3 KB soft / 8 KB hard budget if bytes > 3072.
- **recent_commits** → Mention the count; read back the 1-2 most
  recent subjects.

## 3. Follow-up routing

The whole point of explain-state is to help the user decide what to
do next. Offer one or two next steps based on what's present:

- Stack but no profile → suggest `bootstrap-project` with a matching
  profile name.
- Profile but no hooks wired → suggest re-running `/nyann:retrofit`
  to install the hook bundle.
- CLAUDE.md missing router markers → note it can be regenerated via
  `/nyann:retrofit`.
- Everything present and clean → "Looks set up. Want a deeper audit?
  Run `doctor` for drift checks."

## 4. When the profile field shows `(unknown)`

CLAUDE.md wasn't generated by nyann (or the marker block has been
removed). Don't treat this as a bug — some users intentionally hand-
curate CLAUDE.md. Ask whether they want to re-bootstrap or leave it
manually-maintained.

## When to hand off

- "Is it healthy?" / "What's drifted?" → `doctor` skill.
- "What does `nextjs-prototype` do?" → `inspect-profile`.
- "Set this up with the right profile" → `bootstrap-project`.
- "I want to change the branching strategy" → edit the profile (or
  pick a different one) and re-bootstrap.