Reflect

Reflect

Analyze the current conversation to identify what went wrong, then audit the entire relevant subsystem for related weaknesses. A correction is a signal — it reveals not just one mistake but a class of potential failures. Your job is to trace the thread and find everything it connects to.

Workflow

Phase 1: Identify the Correction

Read the full conversation to find every correction the user made — not just the most recent one. Multiple corrections often share root causes. Distill each one:

• What happened — the observable failure
• What should have happened — the expected behavior
• The underlying cause — why the system allowed this to happen (not just "the rule was missing" but "the skill doesn't address this category of concern at all")

Phase 2: Audit the Subsystem

This is where /reflect earns its keep. A correction doesn't exist in isolation — it points to a weakness in a subsystem. Audit the full chain that produced the failure:

1. Map the subsystem. Identify every file involved in the workflow that failed:

   • The skill that governed the agent's behavior
   • The agent definition that dispatched the work
   • The reference documentation the agent relied on
   • Any rules that constrained the orchestrator
   • Any scripts that ran as part of the flow
   • CLAUDE.md if the orchestrator itself was involved

2. Read all of them. Not just the obvious target — read the full subsystem. The correction might point at the skill, but the real gap might be in the agent's chaining rules, or in a reference that's missing a field annotation.

3. Ask diagnostic questions as you read each file:

   • Does this file address the category of concern the correction revealed, or just adjacent ones?
   • Are there similar gaps? If a field was undocumented, are other fields also undocumented?
   • Are instructions ambiguous in ways that could produce different failures of the same kind?
   • Are there implicit assumptions that should be explicit rules?
   • Does the agent know when to do something but not when not to?
   • Are cross-references between files consistent? Does the agent mention capabilities the skill doesn't explain?

Phase 3: Determine Targets

Classify each file as one of:

• Skill (SKILL.md) — agent produced wrong output due to missing or unclear rules
• Agent (.claude/agents/*.md) — delegation, chaining, or agent behavior was wrong
• Reference (references/*.md) — schema documentation was incorrect or incomplete
• Rule (.claude/rules/*.md) — orchestrator's own behavior was wrong
• Script (.claude/scripts/*.js) — hook script has a bug or missing logic
• CLAUDE.md — orchestrator's core instructions need adjustment

Phase 4: Propose Changes

Present findings in two tiers:

Tier 1 — Direct Fix The change that addresses the user's explicit correction. Describe exactly what to change, where, and why.

Tier 2 — Discovered Improvements Issues found during the audit that the user didn't explicitly flag but that the correction revealed. For each:

• What the issue is
• Why the correction made it visible (the connection)
• The proposed change

Both tiers require explicit approval before applying. Present Tier 1 first, then Tier 2 as "While auditing the subsystem, I also found..."

Display format: For every proposal, show the old text and new text as a pair of rendered blockquotes so the user can visually compare them. Do not use inline text or markdown code blocks.

Pre-flight check: Before presenting proposals, verify each one against the project's configuration rules (no world-specific content in generic skills, no examples, preserve existing conventions). If a proposal violates these rules, rework it before presenting — don't rely on the user to catch it.

Phase 5: Apply with Approval

Wait for the user to approve changes. Apply approved edits using the Edit tool — never Write to overwrite entire files. The user may approve Tier 1 but want to discuss Tier 2, or approve some Tier 2 items but not others.

Principles

• One correction, thorough audit. The correction is the starting point, not the boundary. Follow the thread through the full subsystem.
• Precise changes, broad investigation. Read widely but edit narrowly. Each proposed change should be minimal and targeted, even though the investigation spans multiple files.
• Keep it generic. Never encode world-specific content into skills, agents, or references. Frame corrections as universal rules or formats.
• No examples. Use formats with [placeholders] and descriptive rules, never examples — examples introduce bias.
• Preserve existing conventions. Match the style and structure of the file being edited. Read it first.
• Don't drop what works. When rewriting a rule, diff the new text against the old. If the original rule correctly required something, the new version must still require it — even if the framing changes.
• Explain the connection. For every Tier 2 finding, explain how the original correction led you to it. Unrelated improvements don't belong here — save them for a separate conversation.