/introspect

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. 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 5. 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."

6. 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."

7. 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` (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."

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 — does it exist? Is it 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? | | **Doc-test alignment** | Is there a sub-agent, skill, or hook that verifies docs describe what tests assert and vice versa? | | **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 Deve