Skill: ivangdavila/reflection (version 1.1.0)

--- name: Self Reflection slug: reflection version: 1.1.0 homepage: https://clawic.com/skills/reflection description: Learns when to stop and review. Self-critiques before showing you, fewer revision rounds. metadata: {"clawdbot":{"emoji":"🪞","requires":{"bins":[]},"os":["linux","darwin","win32"],"configPaths":["~/reflection/"]}} changelog: Major rewrite. Visual workflow, pattern detection system, proactive lesson injection, and multi-trigger architecture. --- Agents repeat mistakes. Not because they're incapable — because they forget. This skill changes that. Your agent pauses before delivering, catches its own blind spots, and remembers lessons for next time. ## When to Use User needs quality assurance beyond "looks good to me." Agent handles pre-delivery evaluation, post-mistake analysis, pattern detection across sessions, and proactive lesson surfacing before repeating errors. ## How It Works ``` ┌──────────────────────────────────────────────┐ │ SELF REFLECTION LOOP │ └──────────────────────────────────────────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ PRE │ │ POST │ │PATTERN │ │DELIVERY │ │ MISTAKE │ │DETECTED │ └────┬────┘ └────┬─────┘ └────┬────┘ │ │ │ │ "Before I send │ "User corrected │ Same mistake │ this, let me │ me. Why?" │ 3 times... │ double-check" │ │ │ │ │ └───────────────────┴────────────────────┘ │ ▼ ┌─────────────────┐ │ 7-DIMENSION │ │ EVALUATION │ │ (30 seconds) │ └────────┬────────┘ │ ┌───────────────┴───────────────┐ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ ALL CLEAR │ │ ISSUE FOUND │ │ Deliver │ │ Fix first │ └─────────────┘ └──────┬──────┘ │ ▼ ┌─────────────────┐ │ LOG LESSON │ │ Miss → Root │ │ → Prevention │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ INJECT NEXT │ │ TIME │ │ "Before we │ │ proceed..." │ └─────────────────┘ ``` ## The Three Triggers ### 1. 🔍 Pre-Delivery Before sending important work, pause. 30 seconds. Quick scan of 7 dimensions. **When:** Code, architecture, strategy, any deliverable the user will act on. ### 2. ❌ Post-Mistake User corrected you. That's data. Capture it before the session ends. **When:** User says "actually...", "no, that's wrong", "I meant...", frustration signals. ### 3. 🔄 Pattern Detection Same category appearing 3+ times? That's not coincidence — it's a blind spot. **When:** After logging 5 reflections, weekly review, or heartbeat trigger. ## Architecture Memory lives in `~/reflection/`. See `memory-template.md` for setup. ``` ~/reflection/ ├── memory.md # Status + preferences + stats ├── reflections.md # Log (most recent first) ├── patterns.md # Detected patterns └── archive/ # Monthly archives ``` ## Quick Reference | Topic | File | |-------|------| | Setup process | `setup.md` | | Memory template | `memory-template.md` | | Evaluation dimensions | `dimensions.md` | | Reflection prompts | `prompts.md` | ## Core Rules ### 1. Check Lessons Before Acting Before significant work, scan `~/reflection/patterns.md`. Surface relevant lessons: > "Before we proceed — I have a lesson from past work on [topic]: [summary]." ### 2. Use 7-Dimension Evaluation | # | Dimension | Question | |---|-----------|----------| | 1 | Correctness | Does it solve the stated problem? | | 2 | Completeness | Edge cases covered? Assumptions stated? | | 3 | Clarity | Immediately understandable? | | 4 | Robustness | What could break this? | | 5 | Efficiency | Unnecessary complexity? | | 6 | Alignment | What user actually wants? | | 7 | Pride | Would I sign my name on this? | If any dimension scores below 7/10 → fix before delivering. ### 3. Log Every Correction When user corrects you: 1. STOP and acknowledge 2. Analyze root cause 3. Log to `~/reflection/reflections.md`: ``` ## YYYY-MM-DD | [category] **Miss:** What went wrong **Root:** Why (5 whys) **Fix:** Prevention rule ``` ### 4. Detect Patterns (After 5 Reflections) - Same category 3+ times → create prevention rule - Same mistake twice → escalate to pattern - Improvement trend → document what worked ### 5. Categories for Every Reflection Default: `technical`, `communication`, `assumptions`, `process`, `scope` ### 6. Archive Monthly Move processed reflections to `~/reflection/archive/YYYY-MM.md`. Keep `reflections.md` lean. ### 7. Track Streaks Days since repeated mistake. Resets on pattern recurrence. Celebrate milestones. ## Pattern Lifecycle ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ EMERGING │ ──▶ │ ACTIVE │ ──▶ │ MONITORING │ ──▶ │ RESOLVED │ │ 2 similar │ │ 3+ times │ │ Prevention │ │ 30 days │ │ reflections │ │ → create │ │ in place │ │ clean │ └──────────────┘ │ rule │ └──────────────┘ └──────────────┘ └──────────────┘ ``` Patterns in `~/reflection/patterns.md`: ```markdown ## [Pattern Name] category: technical frequency: 4 occurrences status: active | monitoring | resolved **Pattern:** What keeps happening **Root:** Why this pattern exists **Prevention:** Rule to break it **Last seen:** YYYY-MM-DD **Streak:** X days without recurrence ``` ## The "Inject Next Time" Superpower The skill's real value: surfacing lessons BEFORE you repeat mistakes. **How it works:** 1. Before starting work, identify task domain 2. Check `~/reflection/patterns.md` for active patterns 3. If relevant pattern exists → mention it naturally **Example:** > "Before we build this API — I have a lesson about timeout handling from a previous project. Let me make sure to include proper error timeouts this time." ## Setup On first use, read `setup.md` for integration guidelines. Creates memory files in `~/reflection/` (user is informed where data is stored if they ask). ## Common Traps | Trap | Consequence | |------|-------------| | Reflecting without logging | Lesson lost with session | | Vague root causes | "Made mistake" doesn't prevent recurrence | | No prevention rule | Same mistake WILL happen again | | Ignoring patterns | Individual mistakes are noise; patterns are signal | | Over-reflecting | 30 seconds pre-delivery, not 5 minutes | ## Related Skills Install with `clawhub install <slug>` if user confirms: - `memory` — persistent memory patterns - `decide` — decision-making autonomy - `learning` — adaptive learning system ## Feedback - If useful: `clawhub star reflection` - Stay updated: `clawhub sync`

path: dimensions.md
content: # 7-Dimension Evaluation

Use this as a quick checklist before delivering important work. Takes 30 seconds.

## The Dimensions

| # | Dimension | Core Question | Red Flags |
|---|-----------|--------------|-----------|
| 1 | **Correctness** | Does it solve the stated problem? | Solving wrong problem, misread requirements |
| 2 | **Completeness** | Edge cases covered? | Missing null checks, unhappy paths ignored |
| 3 | **Clarity** | Immediately understandable? | Dense code, no comments on complex logic |
| 4 | **Robustness** | What could break this? | No error handling, brittle assumptions |
| 5 | **Efficiency** | Unnecessary complexity? | Over-engineering, premature optimization |
| 6 | **Alignment** | What user actually wants? | Letter vs spirit of request |
| 7 | **Pride** | Would I sign my name? | Gut check on quality |

## Quick Scoring

For each dimension: 1-10 score (10 = excellent)

- **All ≥7** → Clear to deliver
- **Any <7** → Address before delivering
- **Any <5** → Major revision needed

## Common Failure Modes

### Correctness
- Solved the problem I assumed, not the one stated
- Optimized for wrong metric

### Completeness  
- "Happy path only" implementation
- Missing input validation

### Clarity
- Future-me won't understand this
- Magic numbers without explanation

### Robustness
- Works on my machine™
- No timeout, no retry, no fallback

### Efficiency
- 200 lines when 20 would do
- Premature abstraction

### Alignment
- Technically correct, practically useless
- User asked for X, I delivered adjacent Y

### Pride
- "It works" ≠ "It's good"
- Would be embarrassed if someone reviewed this


path: memory-template.md
content: # Memory Template — Self Reflection

Copy this structure to `~/reflection/memory.md` on first activation.

---

```markdown
# Self Reflection — Memory

## Status
- streak_days: 0
- total_reflections: 0
- patterns_active: 0
- patterns_resolved: 0
- last_review: never
- installed: YYYY-MM-DD

## Preferences
- review_day: Sunday
- archive_threshold: 20
- reflection_depth: standard

## Stats by Category
| Category | Count | Last |
|----------|-------|------|
| technical | 0 | - |
| communication | 0 | - |
| assumptions | 0 | - |
| process | 0 | - |
| scope | 0 | - |

## Active Patterns
(Populated when patterns detected)

## Recent Milestones
(Populated as streaks are achieved)
```

---

## reflections.md Template

```markdown
# Reflections Log

Most recent first. Archive when >20 entries.

<!-- Template for new entry:
## YYYY-MM-DD | [category]
**Miss:** What went wrong
**Root:** Why it happened
**Fix:** Prevention rule
**Pattern:** new | extends:name | none
-->
```

---

## patterns.md Template

```markdown
# Detected Patterns

## How to Use
- Scan this file before starting work in a domain
- Surface relevant patterns proactively
- Update streak when pattern avoided

<!-- Template for new pattern:
## [Pattern Name]
category: [category]
frequency: X occurrences
status: emerging | active | monitoring | resolved

**Pattern:** What keeps happening
**Root:** Why this pattern exists
**Prevention:** Rule to break it
**Evidence:** Links to reflections
**Last seen:** YYYY-MM-DD
**Streak:** X days since last occurrence
-->
```


path: prompts.md
content: # Reflection Prompts

Use these when stuck or during weekly review.

## Post-Mistake Analysis

1. **What exactly went wrong?** (Be specific, not "I made a mistake")

2. **What was my assumption?** (There's always an assumption)

3. **When did the assumption form?** (Often very early)

4. **What signal did I miss?** (Usually there was one)

5. **What's the smallest rule that prevents this?** (Prevention, not description)

## Pattern Detection Questions

- "Have I seen this category 3+ times recently?"
- "Is this the same mistake with different symptoms?"
- "What connects these seemingly different errors?"
- "If a colleague kept making this mistake, what would I tell them?"

## Pre-Delivery Prompts

- "If this were someone else's work, what would I critique?"
- "What's the most likely thing to go wrong?"
- "Does this match what the user WANTS, not just what they ASKED?"
- "Would I be proud to show this to [respected person]?"

## Weekly Review Prompts

- "Which category is trending up?"
- "Any mistakes that happened twice?"
- "What worked well that should become standard?"
- "What am I NOT reflecting on that I should be?"

## Root Cause Depth Check

"Why?" × 5:

1. Why did this happen?
2. Why was that the case?
3. Why did that occur?
4. Why was that true?
5. Why was that allowed?

Usually by layer 3-4, you hit the real cause.


path: reflections.md
content: # Reflections Log

Most recent first. Archive when >20 entries.

<!-- Template for new entry:
## YYYY-MM-DD | [category]
**Miss:** What went wrong
**Root:** Why it happened
**Fix:** Prevention rule
**Pattern:** new | extends:name | none
-->


path: setup.md
content: # Setup — Self Reflection

## First Activation

On first use:

1. **Register in workspace memory** — Add to MEMORY.md:
   ```
   ## Self Reflection
   - Installed: YYYY-MM-DD
   - Memory: ~/reflection/
   - Status: active
   ```

2. **Create folder** — `mkdir -p ~/reflection/archive`

3. **Initialize memory** — Copy structure from `memory-template.md` to `~/reflection/memory.md`

4. **Create reflections.md** — Empty file, will populate as lessons are logged

5. **Create patterns.md** — Empty file, will populate when patterns emerge

## Integration Points

### Heartbeat (Optional)
Add to HEARTBEAT.md:
```markdown
## Self Reflection Check
Every heartbeat, quick scan:
1. Pending reflection to log?
2. Pattern threshold reached (5 reflections)?
3. Weekly review due?
If any → handle. Otherwise → continue.
```

### Pre-Delivery Trigger
Before important deliverables, run 7-dimension scan (30 seconds):
- All clear → deliver
- Issue found → fix first, then deliver

## Configuration

No external config required. All state lives in `~/reflection/`.

Optional: Set review cadence in `~/reflection/memory.md`:
```markdown
## Preferences
- review_day: Sunday
- archive_threshold: 20 reflections
```

## Status Fields

Track in `~/reflection/memory.md`:
- `streak_days` — days without repeated mistake
- `total_reflections` — count by category
- `patterns_active` — count of active patterns
- `patterns_resolved` — count of resolved patterns
- `last_review` — date of last weekly review


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)