reflecting

What this skill does

# Reflecting

## Overview

**Reflecting IS converting experience into a structured report for the planning pipeline.**

Analyze the conversation, extract learnings, and produce a reflection report. Route the report to planning-agent-systems — do not classify or create components directly.

**Core principle:** Capture before context is lost. Classify just enough for planning to act on.

**Violating the letter of the rules is violating the spirit of the rules.**

## Routing

**Pattern:** Chain
**Handoff:** auto-invoke
**Next:** `planning-agent-systems`

## Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

```
TaskCreate for EACH task below:
- Subject: "[reflecting] Task N: <action>"
- ActiveForm: "<doing action>"
```

**Tasks:**
1. Analyze conversation
2. Extract knowledge
3. Produce reflection report
4. Review report quality
5. Consolidation review
6. Route to planning

Announce: "Created 6 tasks. Starting execution..."

**Execution rules:**
1. `TaskUpdate status="in_progress"` BEFORE starting each task
2. `TaskUpdate status="completed"` ONLY after verification passes
3. If task fails → stay in_progress, diagnose, retry
4. NEVER skip to next task until current is completed
5. At end, `TaskList` to confirm all completed

## Pain Point Focus

If the user provides a pain point via `$ARGUMENTS` (e.g., `/reflect hooks keep breaking on Windows`), treat it as a **priority lens** for the entire reflection:

1. The pain point gets its own event entry in Task 1 — even if the conversation doesn't explicitly show it failing
2. In Task 2, extract at least one learning specifically addressing the pain point
3. The pain point does NOT replace normal analysis — still scan the full conversation for other events

This ensures user-reported friction gets captured even when it's not visible in the conversation trace.

## Task 1: Analyze Conversation

**Goal:** Review the conversation to identify significant events.

**If pain point provided:** Create an event entry for it first, using the user's description as context. Then proceed with normal analysis.

**Look for:**
- **Corrections** — user corrected the agent's approach or output
- **Errors** — agent made a mistake, multiple attempts needed
- **Discoveries** — new insights about the project, domain, or tooling
- **Repetitions** — same action performed multiple times (automation candidate)
- **Safety bypasses** — destructive or irreversible actions taken without confirmation, or safety checks circumvented

**Safety bypass patterns to detect** (scan commands run, edits made, user interjections):
- `git push --force`, `git reset --hard`, `git checkout --`, `git clean -f`, `git branch -D` without explicit user confirmation
- `--no-verify`, `--no-gpg-sign`, bypassing pre-commit or validation hooks
- `rm -rf`, dropping tables, overwriting uncommitted changes
- Deleting or editing tests to make them pass (instead of fixing implementation)
- Discarding unfamiliar files/branches that may be user in-progress work
- `rsync --delete` or deploys without verifying exclusions
- User interjection phrases: "stop", "don't delete", "wait", "why did you", "rollback", "undo"
- Agent reasoning that treats destructive op as shortcut around obstacle

**Trace the skill router for each event:**
For corrections and errors, identify which component routed the agent to that behavior:
1. Which skill was active? (check skill invocations in conversation)
2. Which rule or CLAUDE.md law triggered the approach?
3. Was there no router (agent used general knowledge)?

**Locate the router's actual file path** — use Glob to find it:
- Skill → `Glob "**/skills/{name}/SKILL.md"` (covers `plugins/**/skills/` and `.claude/skills/`)
- Rule → `Glob "**/.claude/rules/{name}.md"`
- Agent/Subagent → `Glob "**/agents/{name}.md"` (covers `plugins/**/agents/` and `.claude/agents/`)
- CLAUDE.md → project root `CLAUDE.md`

If Glob returns multiple matches, record all paths — the conversation context usually disambiguates which one was active.

Record the resolved path. This path is used in Task 2 dedup gate.

This determines where fixes land:
- Router is a skill → fix goes in that skill
- Router is a rule → fix goes in that rule
- Router is CLAUDE.md → fix goes in CLAUDE.md
- No router → new rule or skill needed

**Document each event:**
```
Event: [What happened]
Context: [When/where it occurred]
Outcome: [Result]
Type: correction / error / discovery / repetition / safety_bypass
Router: [skill/rule/law/none that caused this behavior]
Router path: [resolved file path, or "none"]
```

**Verification:** Listed at least 3 significant events. If fewer than 3 occurred, document why. Each event has a router identified (or explicitly "none").

## Task 2: Extract Knowledge

**Goal:** Derive actionable learnings from each event.

**For each event, ask:**
- What would have prevented this failure?
- What made this succeed that could be repeated?
- What did we learn that applies beyond this task?

**Simplicity principle:** Prefer the simplest component type that works.
- A one-line convention → `rule`, not a `skill`
- A repeated multi-step process → `skill`, not a `doc`
- An immutable project constraint → `law`, not a `rule`

**Safety bypass overrides simplicity:** If event type is `safety_bypass`, fix_target MUST be `rule` or `law` — never `skill` alone. Rationale: skills are opt-in routers, but safety constraints need always-on enforcement. Law for absolute prohibitions (force push main), rule for path/context-scoped enforcement (no `--no-verify` in this repo). Every safety_bypass learning also requires one explicit preventive instruction naming the exact command/flag to block.

**Learning format:**
```yaml
Learning:
  context: [When this applies]
  insight: [What was learned]
  evidence: [Specific event that taught this]
  router: [Which component routed the behavior, from event trace]
  fix_target: [Same component as router, or new component if router=none]
  suggested_component: rule / law / skill / hook / doc
  rationale: [Why this component type fits, informed by router analysis]
```

**Verification:** Each event has at least one learning with router, fix_target, suggested component, and rationale.

## Task 3: Produce Reflection Report

**Goal:** Write a structured report for the planning pipeline.

1. Read `references/report-template.md` for format and completeness checklist
2. Determine timestamp: `YYYY-MM-DD` format
3. Write report to `.rcc/{timestamp}-reflection.md`

The report must follow the template exactly, including:
- Session context
- Events table (Event / Context / Outcome / Type)
- Learnings table (Learning / Evidence / Suggested Component / Rationale)
- Component recommendations with path hints and content summaries
- Weaknesses addressed (if applicable)

**Verification:** Report file exists at the expected path with no placeholder text.

## Task 4: Review Report Quality

**Goal:** Verify the report is complete before routing.

Use the completeness checklist from `references/report-template.md`:

- [ ] Every event has at least one learning
- [ ] Every learning has router, fix_target, suggested component, and rationale
- [ ] Every component recommendation has type, path hint, content summary, and traces-to
- [ ] No placeholder text (TBD, TODO, etc.)
- [ ] Session context accurately describes the work done
- [ ] At least 3 events documented (or explanation of why fewer)

**If missing learnings** → return to Task 2, extract more, then re-run Task 3.
**If format issues** → return to Task 3, fix the report.

**Verification:** All checklist items pass.

## Task 5: Consolidation Review

**Goal:** Ensure recommendations consolidate into existing components rather than bloating the system.

**Only review components with diff** — invoke reviewer agents on each recommendation's fix_target (using router path from Task 1).

**For each recommendation, invoke the corresponding reviewer agent:**

| fix_target type | Reviewer agent |
|--