From 59b88fbdbdde658b801f1f5b53898de16c033fd7 Mon Sep 17 00:00:00 2001
From: Ori Nachum <ori.nachum@gmail.com>
Date: Sun, 12 Apr 2026 00:36:44 +0300
Subject: [PATCH 1/2] Add /guide:introspect skill for Introspective Development
 (closes #40)

New skill that audits lifecycle coverage, finds gaps in tooling and docs,
and auto-fixes what it finds. Supports three trigger levels (off/remind/auto)
with natural language toggle and config persistence across plugin updates.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json               |   2 +-
 .claude-plugin/plugin.json                    |   2 +-
 CLAUDE.md                                     |   6 +-
 hooks/scripts/migrate-data.sh                 |   2 +-
 hooks/scripts/track-prompt.sh                 |   2 +
 hooks/scripts/track-stop.sh                   |   9 +-
 .../expert/introspective-development.md       | 132 ++++++++++
 skills/game-mode/SKILL.md                     |  10 +-
 skills/introspect/SKILL.md                    | 225 ++++++++++++++++++
 skills/level-up/SKILL.md                      |   4 +
 tests/helpers/setup.sh                        |   3 +-
 tests/migrate-data.bats                       |   8 +-
 tests/track-prompt.bats                       |  12 +-
 tests/track-stop.bats                         |   2 +-
 14 files changed, 400 insertions(+), 19 deletions(-)
 create mode 100644 skills/ask/references/expert/introspective-development.md
 create mode 100644 skills/introspect/SKILL.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index c36ebd3..1e2a4bd 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
                   "name": "guide",
                   "source": "./",
                   "description": "Claude Code guide — interactive onboarding walkthrough and Q&A on setup, best practices, automation, and effective workflows",
-                  "version": "2.16.0",
+                  "version": "2.17.0",
                   "license": "CC-BY-4.0",
                   "keywords": ["onboarding", "guide", "tutorial", "best-practices", "automation", "workflows", "migration"]
           }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 49193e0..df6923a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "guide",
   "description": "A Claude Code guide — skills for interactive onboarding and Q&A on setup, best practices, automation, and effective workflows",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "author": {
     "name": "Ori Nachum"
   },
diff --git a/CLAUDE.md b/CLAUDE.md
index 57ee72b..511ba97 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,10 +6,11 @@ This file tells Claude Code (and other AI agents) how to work with this reposito
 
 ## What This Repo Is
 
-A Claude Code guide, packaged as a plugin. There are five skills:
+A Claude Code guide, packaged as a plugin. There are seven skills:
 
 - **`/guide:onboard`** — Interactive getting-started walkthrough for new users
 - **`/guide:ask`** — Q&A skill backed by comprehensive reference documentation in `skills/ask/references/`
+- **`/guide:introspect`** — Introspective Development — audit lifecycle coverage, find gaps, and improve your development environment
 - **`/guide:game-mode`** — Gamified usage tracker that rewards feature breadth and depth with a level system
 - **`/guide:level-up`** — Feature roadmap and personalized next-step coaching
 - **`/guide:migrate-to-claude`** — Smart migration from other AI coding assistants (Cursor, Windsurf, Copilot, Codex, etc.) to Claude Code
@@ -111,6 +112,7 @@ claude-code-guide/
 │   │           │   ├── agent-sdk.md
 │   │           │   ├── hooks-http.md
 │   │           │   ├── ongoing-work.md
+│   │           │   ├── introspective-development.md
 │   │           │   ├── sub-agents.md
 │   │           │   └── team-mode.md
 │   │           ├── daily-workflow.md ...... Story walkthrough
@@ -123,6 +125,8 @@ claude-code-guide/
 │   │           ├── sub-agents-in-monolith.md
 │   │           ├── automated-briefings.md
 │   │           └── migrating-from-other-tools.md
+│   ├── introspect/
+│   │   └── SKILL.md ...................... Introspective Development — audit and improve your project
 │   ├── game-mode/
 │   │   └── SKILL.md ...................... Gamified usage tracker with levels
 │   ├── level-up/
diff --git a/hooks/scripts/migrate-data.sh b/hooks/scripts/migrate-data.sh
index 24d5e59..07c7d99 100755
--- a/hooks/scripts/migrate-data.sh
+++ b/hooks/scripts/migrate-data.sh
@@ -37,7 +37,7 @@ fi
 command -v jq >/dev/null 2>&1 || exit 0
 
 # Define expected feature categories
-EXPECTED='["shell","editing","reading","search","agents","skills","plugins","web","planning","mcp","notebooks","loop","btw","tasks","worktrees"]'
+EXPECTED='["shell","editing","reading","search","agents","skills","plugins","web","planning","mcp","notebooks","loop","btw","tasks","worktrees","introspection"]'
 
 # Add missing fields and categories, preserve all existing data
 # Intentionally does not touch pluginVersion or migrations — those are
diff --git a/hooks/scripts/track-prompt.sh b/hooks/scripts/track-prompt.sh
index ddc787e..a52f73a 100755
--- a/hooks/scripts/track-prompt.sh
+++ b/hooks/scripts/track-prompt.sh
@@ -40,6 +40,8 @@ if echo "$PROMPT" | grep -qE '^\s*/[a-zA-Z]'; then
       CATEGORY="loop" ;;
     btw)
       CATEGORY="btw" ;;
+    guide:introspect)
+      CATEGORY="introspection" ;;
     guide:*)
       exit 0 ;;  # Our own plugin skills — skip
     help|clear|compact|cost|doctor|init|login|logout|status|model|config|\
diff --git a/hooks/scripts/track-stop.sh b/hooks/scripts/track-stop.sh
index ad9ebdd..9870389 100755
--- a/hooks/scripts/track-stop.sh
+++ b/hooks/scripts/track-stop.sh
@@ -74,7 +74,7 @@ is_fibonacci "$SESSION" || exit 0
 eval "$(jq -r '
   def multiplier:
     if . == "shell" or . == "editing" or . == "reading" or . == "search" or . == "btw" then 1
-    elif . == "agents" or . == "worktrees" then 100
+    elif . == "agents" or . == "worktrees" or . == "introspection" then 100
     else 10
     end;
 
@@ -116,7 +116,7 @@ dep_met() {
 
 # Level gating: levels 1-2 see intermediate only; 3+ see intermediate + expert
 if [ "$LEVEL" -ge 3 ]; then
-  CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks agents worktrees"
+  CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks agents worktrees introspection"
 else
   CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks"
 fi
@@ -141,7 +141,7 @@ if [ -n "$ELIGIBLE" ]; then
   WEIGHTED=""
   for feat in $ELIGIBLE; do
     case "$feat" in
-      agents|worktrees) WEIGHTED="$WEIGHTED $feat $feat $feat" ;;
+      agents|worktrees|introspection) WEIGHTED="$WEIGHTED $feat $feat $feat" ;;
       *)      WEIGHTED="$WEIGHTED $feat" ;;
     esac
   done
@@ -163,6 +163,7 @@ if [ -n "$ELIGIBLE" ]; then
     agents)    TIP="Sub Agents — delegate complex tasks to run in parallel" ;;
     tasks)     TIP="Task Management — use TaskCreate to break work into tracked steps" ;;
     worktrees) TIP="Worktrees — use isolation: 'worktree' in agents for parallel git work" ;;
+    introspection) TIP="Introspect — run /guide:introspect after a task to find friction and improve your setup" ;;
     *)         TIP="$PICK" ;;
   esac
 
@@ -173,5 +174,5 @@ if [ -n "$ELIGIBLE" ]; then
 
   echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | Try: ${TIP} (/guide:level-up for more)"
 else
-  echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | ${UNIQUE}/15 features (/guide:level-up)"
+  echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | ${UNIQUE}/16 features (/guide:level-up)"
 fi
diff --git a/skills/ask/references/expert/introspective-development.md b/skills/ask/references/expert/introspective-development.md
new file mode 100644
index 0000000..cf2196a
--- /dev/null
+++ b/skills/ask/references/expert/introspective-development.md
@@ -0,0 +1,132 @@
+---
+title: "Introspective Development"
+parent: "Automation"
+nav_order: 8
+permalink: /introspective-development/
+---
+
+# Introspective Development
+
+> **Level: 🌳 Expert** | **Source:** [Claude Code Guide Plugin](https://github.com/OriNachum/claude-code-guide)
+
+[← Back to Automating Your Workflows](../intermediate/automating-your-workflows.md)
+
+Introspective Development is a paradigm where agents and humans examine their own work, their documentation, and their development environment — then act on what they find. The agent asks itself: **"How could I have done it better?"** and encodes the answer as durable improvements.
+
+Documentation is code. NotebookLM is the compiler. Skills are the executable output.
+
+## The Four Dimensions
+
+### 1. Documentation Loop
+
+Work produces documentation — CLAUDE.md updates, skill descriptions, changelogs. That documentation becomes context for the next session. The agent reads what was written, reflects it into new work, and produces more documentation.
+
+```text
+spec → plan → code → changelog → context for the next spec
+```
+
+This is **Natural Language Memory (NLM)** — agents use generated docs as durable memory across sessions. The docs aren't a byproduct of development; they are the development medium.
+
+### 2. Self-Reflection
+
+Examining what worked and what didn't:
+
+- Did the session reveal misunderstandings or repeated corrections?
+- Were there things the agent had to figure out that should have been documented?
+- Did the user correct the agent's approach? That correction should become durable guidance.
+
+Self-reflection feeds the improvement loop — observations become skills, hooks, or CLAUDE.md entries.
+
+### 3. Active Documentation Review
+
+After producing documentation, deliberately review it through different lenses:
+
+- **Audio review** — feed docs into NotebookLM to generate podcast-style overviews, catch gaps and unclear explanations that aren't obvious when reading
+- **AI conversations** — discuss docs with agents: "explain this back to me," "what's missing," "what would confuse a newcomer"
+- **User-story demos** — write scenarios that walk through actual usage, revealing design gaps
+- **Fix-forward cycle** — issues found flow back as tasks: bug fixes, doc rewrites, design improvements
+
+This is the "documentation as code, NotebookLM as compiler" principle. If the compiled output (podcast, overview, summary) sounds wrong, the source docs need fixing.
+
+### 4. Environment Self-Improvement
+
+Working with agents reveals friction — tasks that take more effort than they should, patterns that repeat without automation, context that gets lost between sessions. Act on these observations:
+
+- **Skills** — encode repeated workflows as slash commands
+- **Hooks** — automate event-driven actions (post-tool, pre-commit, session-end)
+- **MCP servers or agent skills** — wire external integrations for tools the agent needs
+- **Sub-agents** — create specialists for tasks that benefit from dedicated context
+- **CLAUDE.md updates** — capture hard-won project knowledge so future sessions start better
+- **Scripts** — reduce cognitive complexity of common tasks
+
+The loop: **work → notice friction → improve the environment → work better → notice new friction**.
+
+## The Development Lifecycle
+
+Introspective Development verifies that a project supports every phase of the development lifecycle:
+
+| Phase | What "supported" means |
+|---|---|
+| **Plan** | Architecture docs exist, planning guidance in CLAUDE.md or a skill |
+| **Implement** | Code is navigable — AGENT.md in key folders, conventions documented, scripts reduce complexity |
+| **Test** | Test suite exists, CI runs it, agent knows how to invoke tests |
+| **PR** | PR workflow documented or scripted — format, checks, reviewers |
+| **Iterate** | Review feedback loop works — agent can read comments, fix, push |
+| **Clear** | Agent knows how to clean up — compact history, archive, close |
+
+Gaps in any phase create friction. Introspection finds those gaps and proposes fixes.
+
+## Using the Introspect Skill
+
+```text
+/guide:introspect                    # Infers focus from context
+/guide:introspect agent skills       # Focus on a specific area
+/guide:introspect auto               # Enable auto-introspection after PRs
+/guide:introspect remind             # Get reminders after PRs instead
+/guide:introspect off                # Manual only
+```
+
+**Focus inference:**
+
+- After recent work (plan completed, PR merged): focuses on that work
+- On a clean project: asks "Cover the whole project?" for a full review
+- With text: uses your text as the focus area
+
+**The process:**
+
+1. **Scan** — read project state (CLAUDE.md, skills, hooks, plugins, sub-agents, MCP/agent skills, scripts, tests, CI, linting, docs, git history)
+2. **Analyze** — evaluate through the four dimensions
+3. **Lifecycle check** — verify each phase is supported
+4. **Report** — present findings in plan mode for your review
+5. **Fix** — apply approved changes (create/update CLAUDE.md, AGENT.md, skill stubs, linting configs)
+
+## Trigger Levels
+
+Control whether introspection runs automatically:
+
+| Level | Behavior |
+|---|---|
+| **off** (default) | You manually run `/guide:introspect` |
+| **remind** | Agent reminds you after PR merge: "Want to introspect?" |
+| **auto** | Agent runs introspection itself after PR merge |
+
+Toggle with `/guide:introspect auto|remind|off` or natural language ("call it automatically", "stop running it by yourself").
+
+The setting persists across plugin updates. After changing the trigger level, restart Claude Code for it to take effect.
+
+## Origin
+
+Introspective Development originated in the [Culture](https://github.com/OriNachum/culture) project as "Reflective Development" — a paradigm where agents develop by reflecting on real work, not by configuration. The concept evolved through several blog posts:
+
+- **Workbench Development** — scoping agents to specific folders for reliable, isolated work
+- **Agentic Folders** — placing AGENT.md in key directories so agents understand context per-folder
+- **Code as Documentation** — skills as live, executable documentation that can't silently rot
+
+The `/guide:introspect` skill packages these ideas into a practical tool any project can use.
+
+## See Also
+
+- [Hooks](../intermediate/hooks.md) — event-driven automation that introspection may suggest adding
+- [Skills](../intermediate/skills.md) — the building blocks introspection creates
+- [Sub Agents](sub-agents.md) — specialists introspection may recommend
+- [Best Practices](../intermediate/best-practices.md) — patterns that reduce the friction introspection finds
diff --git a/skills/game-mode/SKILL.md b/skills/game-mode/SKILL.md
index cc9eb00..258298d 100644
--- a/skills/game-mode/SKILL.md
+++ b/skills/game-mode/SKILL.md
@@ -84,7 +84,8 @@ Present the available commands:
     "loop":      { "count": 0, "lastUsed": null },
     "btw":       { "count": 0, "lastUsed": null },
     "tasks":     { "count": 0, "lastUsed": null },
-    "worktrees": { "count": 0, "lastUsed": null }
+    "worktrees": { "count": 0, "lastUsed": null },
+    "introspection": { "count": 0, "lastUsed": null }
   },
   "tokens": {
     "read": 0,
@@ -98,7 +99,7 @@ Present the available commands:
 ```
 
 1. Tell the user game mode is now active. Mention:
-   - Tool usage is being tracked across 15 feature categories
+   - Tool usage is being tracked across 16 feature categories
    - Use `/guide:game-mode stats` to see their dashboard
    - Use `/guide:game-mode off` to pause tracking
    - Data is stored locally and never transmitted
@@ -125,7 +126,7 @@ Present the available commands:
 |---|---|---|
 | Beginner | x1 | shell, editing, reading, search, btw |
 | Intermediate | x10 | skills, plugins, web, planning, notebooks, mcp, loop, tasks |
-| Expert | x100 | agents, worktrees |
+| Expert | x100 | agents, worktrees, introspection |
 
 1. Compute: `raw_points = sum(feature.count * multiplier)` and `score = sqrt(raw_points)` to 2 decimal places
 1. Count unique features (count > 0)
@@ -163,9 +164,10 @@ Present the available commands:
 |  ⚪ Loop/Schedule    I       0       0   never        |
 |  ⚪ Task Mgmt        I       0       0   never        |
 |  ⚪ Worktrees        E       0       0   never        |
+|  ⚪ Introspection    E       0       0   never        |
 +=======================================================+
 |  Raw: 1053 pts | Score: sqrt(1053) = 32.45            |
-|  Features: 10/15 unlocked                             |
+|  Features: 10/16 unlocked                             |
 |  Tokens: ~12.4K read, ~3.1K write                     |
 |  Next level: Master (score 55+, 10+ features)         |
 |  Migrated: unknown → 2.2.0 (2026-03-09)              |
diff --git a/skills/introspect/SKILL.md b/skills/introspect/SKILL.md
new file mode 100644
index 0000000..1861647
--- /dev/null
+++ b/skills/introspect/SKILL.md
@@ -0,0 +1,225 @@
+---
+description: Introspect your project — audit lifecycle coverage, find gaps, and improve your development environment.
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Introspect
+
+You are the introspection advisor for the guide plugin, implementing the **Introspective Development** paradigm.
+
+Introspective Development has four dimensions:
+
+1. **Documentation Loop** — docs feed back as agent context (are instruction files current?)
+2. **Self-Reflection** — examining what worked, what didn't in recent work
+3. **Active Documentation Review** — are docs consumable, accurate, contradiction-free?
+4. **Environment Self-Improvement** — encoding friction into skills, hooks, MCP servers, agent skills, or CLAUDE.md
+
+## Arguments handling
+
+Parse `$ARGUMENTS` before doing anything else.
+
+### `help`
+
+Present available usage:
+
+| Usage | What it does |
+|---|---|
+| `/guide:introspect` | Introspect your project — infers focus from context |
+| `/guide:introspect [focus text]` | Introspect with a specific focus area |
+| `/guide:introspect auto` | Enable automatic introspection after PR merge |
+| `/guide:introspect remind` | Enable post-PR reminders to introspect |
+| `/guide:introspect off` | Disable automatic introspection |
+| `/guide:introspect help` | Show this help |
+
+Then stop.
+
+### Trigger level toggle
+
+If `$ARGUMENTS` matches any of these patterns, handle the toggle instead of scanning:
+
+**Detecting intent:**
+
+| Pattern | Level |
+|---|---|
+| `auto`, `call it automatically`, `run introspect after PRs`, `enable auto`, `automatically` | `auto` |
+| `remind`, `remind me`, `ask me after PRs`, `semi-auto` | `remind` |
+| `off`, `stop calling`, `don't run it automatically`, `disable`, `manual only` | `off` |
+
+If the intent is unclear, ask the user which level they want.
+
+**Applying the toggle:**
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json` (create the `introspectConfig` key if missing)
+2. Set `introspectConfig.triggerLevel` to the chosen level (`auto`, `remind`, or `off`)
+3. Write the updated game-data.json
+
+4. If level is `auto`:
+   - Edit this file's frontmatter: set `disable-model-invocation: false`
+   - Search the project for a PR review skill: look in `.claude/skills/`, `skills/`, and installed plugins for any skill whose description mentions "PR", "pull request", or "review"
+   - If found: ask the user "Found **[skill name]**. Update it to call `/guide:introspect` after PR merge?"
+   - If not found: ask the user "No PR review skill found. Create one?" AND add to CLAUDE.md: "After merging a PR, run `/guide:introspect` to review what could be improved."
+   - Tell the user: "Restart Claude Code for automatic introspection to take effect."
+
+5. If level is `remind`:
+   - Keep this file's frontmatter as `disable-model-invocation: true`
+   - Same PR skill search as `auto`, but the instruction becomes: "After merging a PR, remind the user: 'Want to introspect? Run `/guide:introspect`'"
+   - Tell the user: "Restart Claude Code for the reminder to take effect."
+
+6. If level is `off`:
+   - Edit this file's frontmatter: set `disable-model-invocation: true`
+   - Tell the user: "Automatic introspection disabled. You can still run `/guide:introspect` manually anytime. Restart Claude Code for the change to take effect."
+
+Then stop.
+
+### Config persistence check
+
+On every invocation (before scanning), check if the saved config matches the current frontmatter:
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json`
+2. If `introspectConfig.triggerLevel` exists and is `auto`, but this file's frontmatter has `disable-model-invocation: true` (e.g., after a plugin update reset it):
+   - Edit this file's frontmatter: set `disable-model-invocation: false`
+   - Inform the user: "Restored your auto-introspect setting after plugin update."
+
+## Introspection flow
+
+If `$ARGUMENTS` is not a toggle command or `help`, proceed with introspection.
+
+### Step 0: Determine focus
+
+Infer the focus from context:
+
+- If `$ARGUMENTS` contains text (not a toggle keyword): use that text as the focus. Examples: "agent skills", "docs", "test coverage", "PR workflow"
+- If the session has recent work (a plan was completed, code was changed, a PR was merged): focus on that work — "Post-work introspection: reviewing recent changes"
+- If neither: ask the user "No recent work detected. Cover the whole project?" If yes, proceed with a full project review.
+
+State the focus clearly before scanning: "Introspecting: **[focus description]**"
+
+### Step 1: Scan (read-only)
+
+Gather project state relevant to the focus. Read what exists, note what's missing.
+
+| Area | What to look for |
+|---|---|
+| **Instruction files** | CLAUDE.md, AGENT.md files — do they exist? Are they current? |
+| **Skills** | `skills/`, `.claude/skills/` — what workflows are encoded? |
+| **Hooks** | `hooks/`, `.claude/hooks/` — what events are automated? |
+| **Plugins** | `.claude-plugin/`, installed plugins — what extensions exist? |
+| **Sub-agents** | `.claude/agents/`, agent definitions — what specialists exist? |
+| **MCP servers / agent skills** | `.mcp.json`, settings — what external integrations are wired? |
+| **Scripts** | Project scripts — do they reduce cognitive complexity of common tasks? |
+| **Tests & CI** | Test suites, CI pipelines, code linting — are quality gates in place? |
+| **Markdown linting** | markdownlint config, `.markdownlint-cli2.yaml` — is doc quality enforced? |
+| **Docs** | README, `docs/`, references — are they fresh, accurate, consumable? |
+| **Git history** | Recent commits — what workflow patterns are visible? |
+
+Do NOT modify any files during the scan. Only read.
+
+### Step 2: Analyze — "How could I have done it better?"
+
+Evaluate findings through the four dimensions of Introspective Development:
+
+#### Dimension 1: Documentation Loop
+
+- Is CLAUDE.md current and accurate?
+- Do skills have descriptions that match what they actually do?
+- Are AGENT.md files present in key directories?
+- Would an agent landing here for the first time know how to navigate?
+
+#### Dimension 2: Self-Reflection
+
+- If this is post-work introspection: did the session reveal misunderstandings, repeated corrections, or wasted effort?
+- Were there things the agent had to figure out that should have been documented?
+- Did the user correct the agent's approach? That correction should become durable guidance.
+
+#### Dimension 3: Active Documentation Review
+
+- Are docs consumable by tools like NotebookLM (documentation as code, NotebookLM as compiler)?
+- Are there gaps, contradictions, or stale information?
+- Is there a linting setup for docs quality?
+
+#### Dimension 4: Environment Self-Improvement
+
+- What repeated friction should become a skill, hook, MCP server, agent skill, or CLAUDE.md entry?
+- Are there scripts that could reduce cognitive complexity of common tasks?
+- Is the agent's environment set up for efficient work?
+
+### Step 3: Lifecycle coverage check
+
+Evaluate whether the project supports each phase of the development lifecycle:
+
+| Phase | What "supported" means |
+|---|---|
+| **Plan** | Architecture docs exist, planning guidance in CLAUDE.md or a skill |
+| **Implement** | Code is navigable — AGENT.md in key folders, conventions documented, scripts reduce complexity |
+| **Test** | Test suite exists, CI runs it, agent knows how to invoke (documented or scripted) |
+| **PR** | PR workflow is documented or scripted — what to include, format, checks |
+| **Iterate** | Review feedback loop works — agent can read comments, fix, push |
+| **Clear** | Agent knows how to clean up — compact history, archive, close |
+
+### Step 4: Report (plan mode)
+
+Enter plan mode. Present findings as a structured report:
+
+```markdown
+## Introspective Development Report
+
+### Focus: [focus description]
+
+### Documentation Loop
+- [x] Finding that passed
+- [ ] Gap or issue found
+
+### Self-Reflection
+- [ ] Pattern that should be encoded as guidance
+
+### Active Documentation Review
+- [x] Finding that passed
+- [ ] Doc quality issue
+
+### Environment Self-Improvement
+- [ ] Friction that should become a skill/hook/MCP/agent skill
+
+### Lifecycle Coverage
+| Phase | Status | Finding |
+|---|---|---|
+| Plan | OK / Gap | Details |
+| Implement | OK / Gap | Details |
+| Test | OK / Gap | Details |
+| PR | OK / Gap | Details |
+| Iterate | OK / Gap | Details |
+| Clear | OK / Gap | Details |
+
+### Proposed Fixes
+1. Specific fix with rationale
+2. Another fix
+```
+
+Wait for the user to review. They may:
+
+- Adjust proposed fixes
+- Add guidance for specific areas
+- Remove fixes they don't want
+- Ask questions about findings
+
+### Step 5: Fix (after user exits plan mode)
+
+Apply only the approved fixes. For each fix:
+
+**What you CAN do:**
+
+- Create or update CLAUDE.md sections
+- Create AGENT.md files in key directories
+- Create skill stubs (basic SKILL.md with description — user fills in details)
+- Add or update linting configs
+- Update existing skill descriptions
+- Add instructions to existing PR review skills
+
+**What you do NOT do:**
+
+- Delete files
+- Modify application code
+- Change CI pipelines (suggest only, don't touch)
+- Make changes the user didn't approve in the report
+
+After applying fixes, summarize what was changed.
diff --git a/skills/level-up/SKILL.md b/skills/level-up/SKILL.md
index 4e4f6c8..4191898 100644
--- a/skills/level-up/SKILL.md
+++ b/skills/level-up/SKILL.md
@@ -88,6 +88,7 @@ For each feature, determine its state:
 | tasks | Intermediate | — |
 | agents | Expert | skills + planning |
 | worktrees | Expert | agents |
+| introspection | Expert | — |
 
 Show ALL features in the roadmap, including beginner features. Beginner features are foundational — showing them helps users see their full progression.
 
@@ -122,6 +123,7 @@ Present features grouped by tier with belt emoji, use count, and belt label. Exa
   ────────────────────────────────────────────
   🔒 Sub Agents     (needs: planning)
   🔒 Worktrees      (needs: agents)
+  ⚪ Introspection  (0 uses)     White Belt
 
 ═══════════════════════════════════════════════
   ⚪ White  🟡 Yellow  🟠 Orange  🟢 Green
@@ -159,6 +161,7 @@ Advanced user example with dans:
   ────────────────────────────────────────────
   🟢 Sub Agents     (72 uses)    Green Belt
   🟡 Worktrees      (20 uses)    Yellow Belt
+  🟠 Introspection  (38 uses)    Orange Belt
 
 ═══════════════════════════════════════════════
   ⚪ White  🟡 Yellow  🟠 Orange  🟢 Green
@@ -193,6 +196,7 @@ Present a short, positive recommendation:
 - White Belt: "**Try Planning** ⚪ — structure complex tasks before diving in. Ask Claude to make a plan for your next feature."
 - White Belt: "**Try Task Management** ⚪ — break complex work into tracked steps. Use TaskCreate to organize multi-step implementations."
 - White Belt: "**Try Worktrees** ⚪ — run agents in isolated git worktrees for parallel work without branch conflicts."
+- White Belt: "**Try Introspection** ⚪ — run `/guide:introspect` after a task to find friction and improve your development environment."
 - Yellow Belt: "**Deepen MCP Tools** 🟡 — you've started exploring external integrations. Try connecting a database or API server to unlock more power."
 - All features Green+: "**Level up Sub Agents** 🟢 — your weakest area. Delegate a research task to a sub-agent while you keep working."
 
diff --git a/tests/helpers/setup.sh b/tests/helpers/setup.sh
index 6d5a239..46fa122 100644
--- a/tests/helpers/setup.sh
+++ b/tests/helpers/setup.sh
@@ -19,7 +19,8 @@ GAME_DATA_TEMPLATE='{
     "loop": {"count": 0, "lastUsed": null},
     "btw": {"count": 0, "lastUsed": null},
     "tasks": {"count": 0, "lastUsed": null},
-    "worktrees": {"count": 0, "lastUsed": null}
+    "worktrees": {"count": 0, "lastUsed": null},
+    "introspection": {"count": 0, "lastUsed": null}
   },
   "tokens": {"read": 0, "write": 0, "total": 0},
   "sessionCount": 0,
diff --git a/tests/migrate-data.bats b/tests/migrate-data.bats
index b22d72c..7499f76 100644
--- a/tests/migrate-data.bats
+++ b/tests/migrate-data.bats
@@ -23,13 +23,13 @@ run_migrate() {
   # All 15 categories should exist
   local count
   count="$(jq '.features | keys | length' "$DATA_FILE")"
-  [ "$count" -eq 15 ]
+  [ "$count" -eq 16 ]
 }
 
-@test "All 15 expected categories are present after migration" {
+@test "All 16 expected categories are present after migration" {
   echo '{"enabled": true, "features": {}}' > "$DATA_FILE"
   run_migrate
-  for cat in shell editing reading search agents skills plugins web planning mcp notebooks loop btw tasks worktrees; do
+  for cat in shell editing reading search agents skills plugins web planning mcp notebooks loop btw tasks worktrees introspection; do
     local val
     val="$(jq -r --arg c "$cat" '.features[$c]' "$DATA_FILE")"
     [ "$val" != "null" ]
@@ -143,7 +143,7 @@ run_migrate() {
   echo '{"enabled": true, "features": {}}' > "$DATA_FILE"
   run_migrate
   # Validate each new feature category has count and lastUsed
-  for cat in shell editing reading search agents skills plugins web planning mcp notebooks loop btw tasks worktrees; do
+  for cat in shell editing reading search agents skills plugins web planning mcp notebooks loop btw tasks worktrees introspection; do
     [ "$(jq -r --arg c "$cat" '.features[$c].count' "$DATA_FILE")" = "0" ]
     [ "$(jq -r --arg c "$cat" '.features[$c].lastUsed' "$DATA_FILE")" = "null" ]
   done
diff --git a/tests/track-prompt.bats b/tests/track-prompt.bats
index 5965b0e..e7c492c 100644
--- a/tests/track-prompt.bats
+++ b/tests/track-prompt.bats
@@ -73,7 +73,17 @@ run_hook() {
   [ "$total" -eq 0 ]
 }
 
-# --- Own plugin is skipped ---
+# --- Own plugin is skipped (except introspect) ---
+
+@test "/guide:introspect increments introspection count" {
+  run_hook '{"prompt": "/guide:introspect"}'
+  [ "$(get_count introspection)" -eq 1 ]
+}
+
+@test "/guide:introspect with args increments introspection count" {
+  run_hook '{"prompt": "/guide:introspect agent skills"}'
+  [ "$(get_count introspection)" -eq 1 ]
+}
 
 @test "/guide:ask is skipped (own plugin)" {
   run_hook '{"prompt": "/guide:ask how do hooks work"}'
diff --git a/tests/track-stop.bats b/tests/track-stop.bats
index 0a36233..fecfd0b 100644
--- a/tests/track-stop.bats
+++ b/tests/track-stop.bats
@@ -208,7 +208,7 @@ run_hook() {
 @test "Already-suggested features are not re-suggested" {
   # Suggest all eligible features until none remain
   # Pre-populate suggestedFeatures with all level 1-2 candidates
-  jq '.suggestedFeatures = ["btw","skills","plugins","web","planning","notebooks","mcp","loop","tasks"]' \
+  jq '.suggestedFeatures = ["btw","skills","plugins","web","planning","notebooks","mcp","loop","tasks","introspection"]' \
     "$DATA_FILE" > "${DATA_FILE}.tmp" && mv "${DATA_FILE}.tmp" "$DATA_FILE"
   output="$(run_hook '{"usage": {"input_tokens": 0, "output_tokens": 0}}')"
   # Should show the "features" summary line instead of "Try:"

From 9faa2e00787be68623d42090c78a023495614748 Mon Sep 17 00:00:00 2001
From: Ori Nachum <ori.nachum@gmail.com>
Date: Sun, 12 Apr 2026 00:45:12 +0300
Subject: [PATCH 2/2] Fix review comments: test comment, suggestedFeatures
 list, config persistence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update test comment "All 15" → "All 16" categories (Copilot)
- Remove expert-tier introspection from level 1-2 suggestedFeatures (Copilot)
- Handle missing game-data.json in toggle flow — create dir/file if needed (Qodo)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 skills/introspect/SKILL.md | 9 +++++----
 tests/migrate-data.bats    | 2 +-
 tests/track-stop.bats      | 2 +-
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/skills/introspect/SKILL.md b/skills/introspect/SKILL.md
index 1861647..06101df 100644
--- a/skills/introspect/SKILL.md
+++ b/skills/introspect/SKILL.md
@@ -50,9 +50,10 @@ If the intent is unclear, ask the user which level they want.
 
 **Applying the toggle:**
 
-1. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json` (create the `introspectConfig` key if missing)
-2. Set `introspectConfig.triggerLevel` to the chosen level (`auto`, `remind`, or `off`)
-3. Write the updated game-data.json
+1. Create `${CLAUDE_PLUGIN_ROOT}/.local/` directory if it doesn't exist
+2. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json` — if the file doesn't exist, start with `{}`
+3. Set `.introspectConfig.triggerLevel` to the chosen level (`auto`, `remind`, or `off`)
+4. Write the updated game-data.json
 
 4. If level is `auto`:
    - Edit this file's frontmatter: set `disable-model-invocation: false`
@@ -76,7 +77,7 @@ Then stop.
 
 On every invocation (before scanning), check if the saved config matches the current frontmatter:
 
-1. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json`
+1. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json` (skip this check if the file doesn't exist)
 2. If `introspectConfig.triggerLevel` exists and is `auto`, but this file's frontmatter has `disable-model-invocation: true` (e.g., after a plugin update reset it):
    - Edit this file's frontmatter: set `disable-model-invocation: false`
    - Inform the user: "Restored your auto-introspect setting after plugin update."
diff --git a/tests/migrate-data.bats b/tests/migrate-data.bats
index 7499f76..eb13abc 100644
--- a/tests/migrate-data.bats
+++ b/tests/migrate-data.bats
@@ -20,7 +20,7 @@ run_migrate() {
   # Start with minimal game-data.json — only enabled and empty features
   echo '{"enabled": true, "features": {}}' > "$DATA_FILE"
   run_migrate
-  # All 15 categories should exist
+  # All 16 categories should exist
   local count
   count="$(jq '.features | keys | length' "$DATA_FILE")"
   [ "$count" -eq 16 ]
diff --git a/tests/track-stop.bats b/tests/track-stop.bats
index fecfd0b..0a36233 100644
--- a/tests/track-stop.bats
+++ b/tests/track-stop.bats
@@ -208,7 +208,7 @@ run_hook() {
 @test "Already-suggested features are not re-suggested" {
   # Suggest all eligible features until none remain
   # Pre-populate suggestedFeatures with all level 1-2 candidates
-  jq '.suggestedFeatures = ["btw","skills","plugins","web","planning","notebooks","mcp","loop","tasks","introspection"]' \
+  jq '.suggestedFeatures = ["btw","skills","plugins","web","planning","notebooks","mcp","loop","tasks"]' \
     "$DATA_FILE" > "${DATA_FILE}.tmp" && mv "${DATA_FILE}.tmp" "$DATA_FILE"
   output="$(run_hook '{"usage": {"input_tokens": 0, "output_tokens": 0}}')"
   # Should show the "features" summary line instead of "Try:"