self-reflection

What this skill does

# Self-Reflection

Mine memories and remediations for behavior patterns, surface findings to user, remediate docs with pressure-tested improvements.

**Core loop:** Search -> Report -> User prioritizes -> Brainstorm -> Pressure test -> Apply

## When to Use

- Periodic review of agent behavior patterns
- After series of failures or poor outcomes
- Before major project milestones
- When CLAUDE.md feels stale or incomplete
- To check ReasoningBank health

## When NOT to Use

- Immediate error diagnosis -> use `contextd-workflow` skill
- Recording a single learning -> use `/remember`
- Checkpoint management -> use `contextd-workflow` skill

## Behavioral Taxonomy

Focus on **agent behaviors**, not technical failures:

| Behavior Type | Description | Examples |
|---------------|-------------|----------|
| **rationalized-skip** | Justified skipping required step | "too simple to test", "user implied consent" |
| **overclaimed** | Absolute language inappropriately | "ensures", "guarantees", "production ready" |
| **ignored-instruction** | Didn't follow CLAUDE.md/skill | Skipped contextd search, ignored TDD |
| **assumed-context** | Assumed without verification | Assumed permission, requirements, state |
| **undocumented-decision** | Significant choice without rationale | Changed architecture without comparison |

## Severity Overlay

| Severity | Combination |
|----------|-------------|
| **CRITICAL** | rationalized-skip + destructive/security operation |
| **HIGH** | rationalized-skip + validation skip, ignored-instruction |
| **MEDIUM** | overclaimed, assumed-context |
| **LOW** | undocumented-decision, style issues |

## The Report

For each finding, surface:

1. **Behavior Type** - Which taxonomy category
2. **Severity** - CRITICAL/HIGH/MEDIUM/LOW
3. **Evidence** - Memory/remediation IDs with excerpts
4. **Violated Instruction** - The skill/command/CLAUDE.md section ignored
5. **Suggested Fix** - Target doc and proposed change
6. **Pressure Scenario** - Test case from real failure

## Remediation Flow

```
Present findings
      |
User selects findings to remediate
      |
Generate doc improvements
      |
Generate pressure scenarios (from real failures)
      |
Run batch tests via subagents
      |
  Pass? --No--> Iterate
      | Yes
Create Issue/PR
      |
Apply changes
      |
Close feedback loop:
  memory_feedback(memory_id, helpful=true)
  Tag original memories as remediated
```

## Behavioral Search Queries

```
# Rationalized skips
memory_search("skip OR skipped OR bypass OR ignored")
memory_search("too simple OR trivial OR obvious")

# User feedback indicating ignored instructions
memory_search("why did you OR should have OR forgot to")

# Assumptions without verification
memory_search("assumed OR without checking")

# Overclaiming
memory_search("ensures OR guarantees OR production ready")
```

Filter out technical bugs: Exclude memories with `error:*` tags or stack traces.

## ReasoningBank Health

`--health` flag analyzes:

- **Memory quality**: feedback rate, confidence distribution
- **Tag hygiene**: inconsistent tags needing consolidation
- **Stale content**: old memories without feedback
- **Remediation completeness**: missing fields

## Quick Reference

| Action | Command |
|--------|---------|
| Full report | `/reflect` |
| Health only | `/reflect --health` |
| Apply fixes | `/reflect --apply` |
| Recent only | `/reflect --since=7d` |
| Filter by behavior | `/reflect --behavior=rationalized-skip` |
| Filter by severity | `/reflect --severity=HIGH` |

## Anti-Patterns

| Mistake | Why It Fails |
|---------|--------------|
| Skipping pressure tests | "Fixed" docs don't actually prevent behavior |
| Modifying plugin source | Breaks on update; use includes |
| Auto-applying security fixes | High-stakes changes need review |
| Ignoring frequency | 10 TDD skips is systemic, not minor |
| Absolute claims in fixes | "This prevents X" -> "This helps reduce X" |

---

## Causal Chain Analysis

### Root Cause Tracing

Go beyond symptoms to find root causes:

```json
{
  "finding_id": "ref_001",
  "behavior": "rationalized-skip",
  "symptom": "Skipped tests before claiming fix complete",
  "causal_chain": [
    {
      "level": 1,
      "cause": "Agent claimed fix without running tests",
      "evidence": ["mem_123", "mem_124"]
    },
    {
      "level": 2,
      "cause": "CLAUDE.md test instruction buried in long section",
      "evidence": ["claude_md_line_245"]
    },
    {
      "level": 3,
      "cause": "No PreToolUse hook enforcing test requirement",
      "evidence": ["hooks.json missing enforcement"]
    }
  ],
  "root_cause": "Missing automated enforcement of test-before-fix policy",
  "fix_target": "hooks.json + CLAUDE.md restructure"
}
```

### Chain Depth Levels

| Level | Description | Fix Location |
|-------|-------------|--------------|
| 1 | Immediate behavior | Agent prompt/skill |
| 2 | Missing guidance | CLAUDE.md/documentation |
| 3 | Missing enforcement | Hooks/automation |
| 4 | Systemic gap | Plugin/skill redesign |

### Multi-Incident Correlation

Find patterns across incidents:

```
causal_correlate(findings: [ref_001, ref_002, ref_003])

Returns:
  shared_root_causes: [
    { cause: "Missing hook enforcement", incidents: [ref_001, ref_002] },
    { cause: "Ambiguous CLAUDE.md section", incidents: [ref_002, ref_003] }
  ]
  recommended_fixes: [
    { target: "hooks.json", impact: "high", fixes_incidents: 2 }
  ]
```

---

## Comparative Benchmarks

### Behavior Metrics Over Time

Track improvement (or regression):

```json
{
  "benchmark_period": "2026-01-01 to 2026-01-28",
  "metrics": {
    "rationalized_skip": {
      "count": 5,
      "previous_period": 12,
      "trend": "improving",
      "change_pct": -58
    },
    "ignored_instruction": {
      "count": 8,
      "previous_period": 6,
      "trend": "regressing",
      "change_pct": +33
    },
    "assumed_context": {
      "count": 3,
      "previous_period": 3,
      "trend": "stable",
      "change_pct": 0
    }
  }
}
```

### Benchmark Categories

| Metric | Target | Good | Warning | Critical |
|--------|--------|------|---------|----------|
| rationalized_skip/week | 0 | < 2 | 2-5 | > 5 |
| ignored_instruction/week | 0 | < 3 | 3-7 | > 7 |
| overclaimed/week | 0 | < 5 | 5-10 | > 10 |
| test_coverage_skip | 0% | < 5% | 5-15% | > 15% |

### Comparative Reports

```
/reflect --benchmark --compare-periods "2026-01" "2025-12"

Output:
  | Behavior | Dec 2025 | Jan 2026 | Change |
  |----------|----------|----------|--------|
  | rationalized-skip | 12 | 5 | -58% |
  | ignored-instruction | 6 | 8 | +33% |

  Top Improvement: Hook enforcement reduced skips
  Top Regression: New skills lack CLAUDE.md entries
```

---

## Behavioral Prediction

### Pattern-Based Prediction

Predict likely future failures based on patterns:

```json
{
  "prediction": {
    "behavior": "rationalized-skip",
    "likelihood": 0.75,
    "conditions": [
      "Complex task with > 5 sub-steps",
      "Time pressure mentioned in prompt",
      "No explicit test requirement in task"
    ],
    "historical_basis": ["mem_101", "mem_102", "mem_103"],
    "prevention": "Add explicit test checkpoint to complex task prompts"
  }
}
```

### Risk Factors

| Factor | Risk Increase | Mitigation |
|--------|---------------|------------|
| Task complexity > 5 steps | +40% skip risk | Explicit checkpoints |
| "Quick fix" language | +60% skip risk | Reject quick-fix framing |
| No acceptance criteria | +50% assumption risk | Require criteria |
| Security-adjacent code | +30% overclaim risk | Require review |

### Predictive Alerts

```json
{
  "alert": "high_risk_task_detected",
  "task_description": "Quick fix for authentication bug",
  "risk_factors": ["quick_fix_language", "security_adjacent"],
  "predicted_behaviors": ["rationalized-skip", "assumed-context"],
  "recommended_guardrails": [
    "Require explicit test plan before starting",
    "Trigger consensus-review before merge"
  ]
}
```

### Inter