introspect-reflect

name	introspect-reflect
description	Use at the end of a debugging or tool-dogfooding session (or when the user asks "reflect / retro / what did we learn") to review how the introspect CLI was used, identify gaps, and propose concrete fixes. Repo-local — do not bundle.

Reflect on a debugging trace

Dogfood review. Turn what just happened into structured feedback on introspect itself. This skill exists because the repo builds introspect; every debug trace here is also a usability test of the tool, and the friction should be captured while it's still fresh.

When to invoke

• User asks "reflect on this," "retro this," "what did we learn," or similar.
• A debugging task just concluded and the user hasn't moved on.
• Do not invoke silently mid-task. Reflection is a trace-end activity — running it while debugging is noise.

What to produce

Write a markdown file at docs/analysis/<YYYY-MM-DD>-<slug>.md. Keep it ≤150 lines. Structure:

# <one-sentence summary of the problem debugged>

Date: YYYY-MM-DD

## Flow

<5–10 bullets, chronological. For each step note the tool used: an `introspect` command, a bash workaround (`cat`, `grep`, `tail`), a test-side handler (`page.on`), a file read, etc. Be honest about false starts.>

## Gaps

Categorize each friction point:

- **CLI gap** — introspect doesn't surface this. Proposed fix: `<file path>` — one-line description.
- **Formatter gap** — data is captured but renders badly. Proposed fix: `<file path>` — what to change.
- **Skill gap** — introspect can do this but skills didn't prompt it. Proposed fix: which skill, what to add.
- **Muscle-memory gap** — skill mentions it; it wasn't reached for anyway. No code fix; note as recurring friction.
- **Plugin / types gap** — the captured data itself is missing. Proposed fix: which plugin, what event shape.

## Proposed fixes

<Bullet list, each a concrete path + change type. Do not open PRs — this is backlog.>

## Open questions

<Design questions the reflection surfaced but didn't resolve. One sentence each.>

Honesty rules

• Record actual behavior, not aspirational. If cat .introspect/*/events.ndjson | grep was used, log it. Do not rewrite history to put introspect first.
• Distinguish "tool didn't have the capability" from "I didn't reach for it." Former is a CLI gap (fix code). Latter is a muscle-memory gap (no code fix; recurring note).
• Prefer mechanical fixes over magic. If the proposed fix is "summarize what went wrong" / "detect render loops" / "classify failure mode," push back in the reflection. Favor: new flag, new formatter branch, new skill line. Dismiss: AI-in-the-loop summaries, heuristic classifiers dressed up as general-purpose features.
• Don't propose features the user hasn't validated. If unsure, list under "open questions."

Do not

• Open a PR.
• Run introspect skills install or touch packages/cli/skills/*. Bundled skills are a different surface; reflection feeds ideas back to those skills separately.
• Duplicate content from a previous reflection unless the same friction recurred (if so, flag it as recurring — that's signal).

After writing

• Print the file path.
• Summarise the top 2–3 proposed fixes in one short paragraph, so the user has something actionable without re-reading the file.