/analyze-sessions

name: analyze-sessions
description: Audit recent AI coding sessions to find repeated mistakes, speed losses, and missed Nimbalyst tool usage — then propose harness improvements

/analyze-sessions Command

Audit recent Nimbalyst AI coding sessions and propose improvements to the **agent harness**: the rules, memory, agent-mistakes log, and CLAUDE.md guidance that shape how future sessions behave. The goal is to make subsequent sessions get the right answer faster and avoid repeating known failures.

**Read-only by default.** Produce a structured report, then use `PromptForUserInput` to let the user pick which suggested changes to apply.

Usage

`/analyze-sessions [<time-period>|<count>|all]`

• **No argument (default)** — analyze the **current session**. If the current session is part of a workstream, analyze **every session in that workstream** instead.
• `1d`, `3d`, `1w` — sessions active within the time window
• A bare number (e.g. `20`) — most recent N sessions across the workspace
• `all` — explicitly request workspace-wide scan (capped at 30 most recent)

The default is intentionally narrow: most of the time the user runs this right after finishing a piece of work, and the most actionable signal is in the session they just finished (or the parallel sessions on the same workstream).

What to look for

Three categories. The point is to find **patterns**, not to grade individual sessions.

1. Repeated mistakes

A mistake the agent makes once is a log entry. A mistake repeated across multiple sessions is a missing rule. Look for:

• The same correction from the user ("don't do X", "stop doing Y") across more than one session
• Repeated tool misuse (wrong tool reached for, same tool used incorrectly)
• Repeated misreadings of the codebase (wrong file, wrong abstraction, wrong assumption)
• Things already in `.claude/agent-mistakes.md` or `MEMORY.md` that the agent did again anyway

For each repeated mistake, decide whether it needs:

• A new entry in `.claude/agent-mistakes.md` (one-off but notable)
• A new rule file in `.claude/rules/` (recurring, deserves a permanent rule)
• A new memory entry under `/Users/ghinkle/.claude/projects/-Users-ghinkle-sources-stravu-editor/memory/` (feedback type, with **Why:** and **How to apply:**)
• An update to an existing rule/memory (the rule was written but didn't catch this variant)

2. Speed losses — where the right answer took too long

Where did the agent burn turns or tokens without progress? Look for:

• **Multi-turn corrections** — the user had to say "no, the other way" more than once before the agent landed the fix. Was there a signal earlier in the conversation the agent should have picked up?
• **Wide-then-narrow exploration** — the agent grepped/read 20+ files when a single targeted read would have worked. Was there context (a doc, a CLAUDE.md section, a tracker item) that pointed at the right file directly?
• **Premature implementation** — the agent started editing before understanding the constraint, then had to revert. Should `/investigate` have been invoked?
• **Stale context** — the agent referenced functions, files, or APIs that no longer exist. Is there a memory entry that's gone stale?
• **Unnecessary planning** — the agent wrote a long plan for a one-line fix. Is there a heuristic for when to skip `/design`?
• **Redundant verification** — the agent re-read or re-ran the same thing across multiple turns instead of trusting earlier output.

3. Underused Nimbalyst tools

The agent has a rich MCP toolset that frequently goes untouched when it would have helped. Check whether sessions used these where appropriate:

| Tool | Should have been used when… | | --- | --- | | `mcp__nimbalyst-extension-dev__database_query` | Agent asked the user to share DB state, or hand-rolled a guess at row contents | | `mcp__nimbalyst-extension-dev__get_main_process_logs` / `get_renderer_debug_logs` | Agent asked the user to paste logs, or speculated about runtime behavior without checking | | `mcp__nimbalyst-extension-dev__renderer_eval` | Agent wanted to know runtime DOM/state and asked the user to inspect manually | | `mcp__nimbalyst-extension-dev__restart_nimbalyst` | Agent asked the user to restart after a main-process change (still requires explicit user approval, but the agent should at least offer) | | `mcp__nimbalyst-extension-dev__extension_build` / `extension_install` / `extension_reload` / `extension_test_run` | Agent was iterating on an extension and asked the user to rebuild/reinstall manually | | `mcp__nimbalyst-extension-dev__extension_test_ai_tool` / `extension_test_open_file` | Agent wrote an extension tool but never exercised it | | `mcp__nimbalyst-extension-dev__get_environment_info` | Agent made code changes without verifying dev-mode is running (CLAUDE.md says to check this first) | | `mcp__nimbalyst-mcp__capture_editor_screenshot` | Agent described a UI state in prose instead of showing it | | `mcp__nimbalyst-mcp__display_to_user` | Agent presented tabular numeric data as a markdown table instead of a chart | | `mcp__nimbalyst-mcp__developer_git_commit_proposal` | User said "propose a commit" / "commit this" and the agent ran `git commit` instead | | `mcp__nimbalyst-session-context__get_session_summary` | Agent re-derived context the prior session already produced | | `mcp__nimbalyst-mcp__AskUserQuestion` / `PromptForUserInput` | Agent buried a blocking question in chat instead of using the interactive widget |

These are *suggestions*, not commands the agent must run unprompted — but if a session would have been measurably faster with one of them, that's a harness gap.

Step 1 — Determine scope

Resolve the inventory based on the argument (or lack thereof):

**No argument (default)**: 1. Call `mcp__nimbalyst-session-context__get_session_summary` with no `sessionId` to identify the **current** session. Note its `workstreamId` (or equivalent grouping field) if present. 2. If the current session belongs to