/nimbalyst-coach

description: Audit this project and your recent sessions, then recommend extensions, features, and agent-instruction changes that would make Nimbalyst work better for you

/planning:nimbalyst-coach Command

Read this project and the user's recent AI sessions, compare both against the catalog below, and report where they are working *around* Nimbalyst instead of *with* it. **Read-only until the report is finished**, then offer the instruction edits for approval.

Argument: `[current | workstream | <count> | <time-window> | all]`

• none -> project scan + the 15 most recent non-archived sessions
• `current` -> project scan + this session only; label every finding as a one-session observation
• `workstream` -> the current workstream's sessions, or this session if it has no workstream
• `20` / `3d` / `1w` -> that many sessions or that window, capped at 30
• `all` -> workspace-wide, still capped at 30

Always exclude this coaching session from the evidence.

The rule that matters most

**Every finding in the evidence tier cites something real** -- a session title, a user quote, a file that exists, a count from a scan. If you cannot cite it, it belongs in the "may not be using" tail, clearly marked as *unused, no evidence*, or nowhere at all. Padding the evidence tier with plausible-sounding best practice is how this command loses the user's trust on its first run, and they only run it once.

Second rule: **never propose something the user already wrote.** Step 1 exists entirely to prevent that.

Step 1 -- read what already exists

Before forming any finding, read the harness that is already here:

• `CLAUDE.md`, `AGENTS.md` at the workspace root, and any `@`-imported files they reference
• `.claude/rules/*.md`, `.claude/commands/*.md`, `.claude/settings.json` (hooks, `permissions.allow`)
• `.mcp.json`, `.nimbalyst/trackers/*.yaml`, `.gitignore`
• the user-level config root -- `CLAUDE_CONFIG_DIR` if set, else `~/.claude` -- for a global `CLAUDE.md`

Treat generated exports under `.agents/skills/.nimbalyst-generated/` as read-only output, never a target.

For each catalog row you later match, decide which is true:

• **not covered** -> a real finding, propose the text
• **covered and followed** -> at most a line in "Already working"
• **covered but ignored in N sessions** -> report *that*, and suggest moving it earlier or making it more specific. Do not propose adding it again.

Step 2 -- census the project

Bounded counts only. Do not read source files.

• File-type counts (e.g. via `git ls-files` then group by extension), top-level layout, package manifests
• Project shape: iOS/Xcode, Electron, Cloudflare Worker, Python/data, monorepo, docs-only
• `TODO`/`FIXME` counts if you need the tech-debt row

Step 3 -- read the install and the settings

• `extensions_list` -> installed extensions with `enabled`, plus registry extensions not installed, plus `registryAvailable`
• `settings_get_overview` -> sync enablement for this project, `issueKeyPrefix`, `agentPermissionMode`, auth state, feature flags

If `registryAvailable` is false, say so in one line and skip the install recommendations. Do not guess at extension names from memory.

Step 4 -- gather session evidence

`list_recent_sessions` (`includeArchived: false`) for the inventory: phase, tags, status, provider, workstream. **The phase and tag distribution is a finding on its own** -- if 20 of 25 sessions have no phase, that is the kanban going unused, and it needs no transcript reading at all.

Then `get_session_coaching_signals` per session, in parallel. It returns JSON: `turnCount`, `userPrompts` (the user's own words, machine-authored prompts already filtered out), `toolUsage` (normalized names with counts), `filesEdited` (deduped), `linkedTrackerItemIds`, `phase`, `tags`, `workstreamId`, `truncated`.

`userPrompts` is the richest signal here. The assistant side of the transcript is **not** available -- never write a finding that quotes what the agent said.

Step 5 -- detect the tier

Check whether you have a SELECT-capable database tool (`database_query`, or the sqlite-browser extension's query tool).

• **Core tier (always)** -- everything above. Covers extensions, harness structure, phase/tag/workstream, user-frustration, tracker links, and tool usage across the reviewed sessions.
• **Enhanced tier (only with SQL)** -- two extra rows: `session_commits` for commit attribution, and `tool_usage_counters` for *project-lifetime* "never once invoked" (the signals tool only sees the reviewed window).

No SQL tool means one honest line in the header and those two rows omitted. Never guess to fill the gap.

Step 6 -- match against the catalog

Filter by what is installed, what the project actually is, and what Step 1 already covers. A row only fires when its signal is genuinely present.

Working habits (from session evidence)

| Practice | Signal | Observable via | | --- | --- | --- | | Keep session phase current | Sessions with no phase; `planning` sessions that edited files | Core -- inventory | | Tag sessions `committed` / `uncommitted` | No commit-state tags anywhere | Core -- inventory | | Use workstreams / sibling sessions | Long sessions spanning unrelated areas; no `workstreamId` anywhere | Core -- inventory + filesEdited | | Read logs directly instead of asking the user | User prompts like "check the logs yourself"; pasted log blobs | Core -- userPrompts | | Query the database instead of asking | User prompts pasting query results | Core -- userPrompts | | Use interactive prompts for questions | User prompts that are terse answers ("option 2", "the first one") | Core -- userPrompts | | Use the commit proposal widget | "propose a commit" with no commit-proposal tool in `toolUsage` | Core -- userPrompts + toolUsage | | Record decisions as `decision` items | Sessions that edited files with no `linkedTrackerItemIds` | Core -- signals | | File tech debt instead of TODO comments | `TODO`/`FIXME` in edited file