auto-improvement

What this skill does

## Overview

The auto-improvement skill implements a self-improving feedback loop that tracks effectiveness metrics, learns from errors, identifies recurring failure patterns, and adapts workflows to prevent repeated mistakes. It enables the agent to become measurably better over time through structured self-assessment rather than ad-hoc adjustments. Without this skill, the same mistakes repeat across sessions — with it, every error becomes a permanent improvement.

**This skill is ALWAYS active.** It runs automatically on every session and cannot be disabled.

---

## Phase 1: Metric Collection

At the start of every task, instrument key decision points:

1. Record task start time and initial estimate
2. Define expected outcome and success criteria
3. Track each decision point (approach chosen, alternatives considered)
4. Log revision count (how many times the output was revised)
5. Track user corrections as improvement signals

### Core Metrics

| Metric | Formula | Target | Measurement Period |
|--------|---------|--------|--------------------|
| First-attempt success rate | Tasks without revision / Total tasks | >80% | Per session |
| Average revision count | Total revisions / Total tasks | <1.5 | Per session |
| Error recurrence rate | Repeated errors / Total errors | <10% | Rolling 10 sessions |
| Time-to-completion accuracy | Actual time / Estimated time | 0.8-1.2 | Per task |
| User correction rate | User corrections / Total outputs | <5% | Per session |

### Tracking Template

```markdown
## Session Metrics -- [Date]

### Tasks
| Task | Estimated | Actual | Revisions | Success | Error Type |
|------|-----------|--------|-----------|---------|------------|
| ...  | 30m       | 45m    | 1         | Partial | Execution  |

### Summary
- Tasks completed: X
- First-attempt success: X/Y (Z%)
- Total revisions: N
- Errors by category: Comprehension(n), Execution(n), Process(n)
- Improvement actions taken: [list]
```

> **STOP: Complete metric collection setup before proceeding to error analysis. Do NOT skip instrumentation.**

---

## Phase 2: Error Analysis

When an error occurs, classify it immediately using the taxonomy:

### Error Taxonomy

| Category | Subcategory | Example | Typical Root Cause |
|----------|-------------|---------|-------------------|
| **Comprehension** | Misread requirement | Built feature X when Y was asked | Insufficient clarification |
| **Comprehension** | Wrong assumption | Assumed REST when GraphQL was used | Missing context discovery |
| **Execution** | Syntax error | Invalid TypeScript type annotation | Unfamiliar API surface |
| **Execution** | Logic error | Off-by-one in pagination | Insufficient test coverage |
| **Execution** | Integration error | Wrong API endpoint or payload format | Missing documentation check |
| **Process** | Skipped step | Forgot to run tests before commit | Process not followed |
| **Process** | Wrong order | Wrote code before understanding spec | Eagerness over methodology |
| **Judgment** | Over-engineering | Built abstraction for single use case | Premature optimization |
| **Judgment** | Under-engineering | Skipped error handling for "simple" task | Underestimated complexity |
| **Knowledge** | Unknown API | Used deprecated method | Outdated training data |
| **Knowledge** | Framework gap | Wrong Next.js pattern for app router | Need to check docs first |

### Severity Levels

| Level | Definition | Response Required |
|-------|-----------|------------------|
| **Critical** | Task must be completely redone | Immediate root cause analysis + add guardrail |
| **Major** | Significant rework needed (>50% of task) | Root cause analysis + add checklist item |
| **Minor** | Small fix needed (<30 minutes) | Log pattern, review if recurring |
| **Cosmetic** | Style or preference issue | Note for future, no process change |

### Error Log Format

```markdown
## Error Log Entry

**ID:** ERR-[YYYY]-[MMDD]-[NNN]
**Date:** [date]
**Task:** [what was being done]
**Severity:** [Critical / Major / Minor / Cosmetic]
**Category:** [Category > Subcategory]

### What Happened
[Description of the error and its observable impact]

### Root Cause
[Why this error occurred — the actual underlying reason]

### What Was Tried
1. [First attempt to resolve]
2. [Second attempt if applicable]
3. [Final resolution]

### Resolution
[What ultimately fixed the problem]

### Time Lost
[Estimated time wasted due to this error]

### Prevention
- **New checklist item:** [if applicable]
- **Memory update:** [what was persisted]
- **Guardrail added:** [if applicable]

### Recurrence Check
- [ ] Similar error seen before? [Yes/No — reference previous ID]
- [ ] Guardrail added? [Yes/No]
```

> **STOP: Every error MUST be classified and logged before proceeding to fix it. Do NOT skip the log entry.**

---

## Phase 3: Pattern Recognition

After accumulating 3+ errors, analyze for patterns:

1. Group related errors into failure categories
2. Identify environmental triggers (specific file types, frameworks, patterns)
3. Detect workflow bottlenecks causing consistent slowdowns
4. Recognize successful patterns worth reinforcing
5. Map anti-patterns to their corrective actions

### Pattern Detection Decision Table

| Signal | Pattern | Action |
|--------|---------|--------|
| Same error >2 times | Recurring failure | Create guardrail (mandatory) |
| Same category >3 times | Systemic weakness | Add pre-flight checklist for that category |
| Time estimate off by >50% consistently | Estimation blind spot | Adjust estimation heuristics |
| User corrections in same area | Knowledge gap | Deep-dive learning for that domain |
| Success rate >90% in specific area | Strength pattern | Document and reinforce |
| Errors cluster around specific framework | Framework knowledge gap | Run context discovery for that framework |

### Positive Pattern Reinforcement

When a pattern consistently leads to success, document it:

```markdown
## Positive Pattern: [Name]
OBSERVATION: [What was done and why it worked]
EVIDENCE: [Sessions/tasks where this pattern succeeded, with success rate]
REINFORCEMENT: [How to ensure this pattern continues to be applied]
```

> **STOP: Pattern recognition must be evidence-based. Do NOT create patterns from single occurrences.**

---

## Phase 4: Adaptation

Generate and implement improvements based on identified patterns:

### Pre-Flight Checklists

Create checklists that run before high-risk operations:

```markdown
## Pre-Flight: Before Writing [Framework] Code
- [ ] Identify the framework and version (check package.json / composer.json)
- [ ] Identify the routing pattern (pages/ vs app/, file-based vs code-based)
- [ ] Check for existing patterns in the codebase (find similar files)
- [ ] Verify the API surface in documentation (do not assume from memory)
- [ ] Check for project-specific conventions (linter config, type config)
```

### Guardrail Rules

```markdown
## Guardrail: [Operation Type]
BEFORE [specific operation]:
1. [Check 1]
2. [Check 2]
3. [Check 3]
4. [Check 4]

TRIGGERED BY: [keywords or conditions that activate this guardrail]
ADDED BECAUSE: [Error ID that caused this guardrail to be created]
EFFECTIVENESS: [Track whether this guardrail has prevented errors]
```

### Adaptation Decision Table

| Error Pattern | Adaptation Type | Example |
|--------------|----------------|---------|
| Recurring comprehension errors | Add clarification step to workflow | "Before implementing, restate the requirement in your own words" |
| Recurring execution errors | Add pre-flight checklist | "Before writing framework code, check version and router type" |
| Recurring process errors | Add hard checkpoint | "STOP marker before commit: did you run tests?" |
| Recurring judgment errors | Add decision criteria table | "When to abstract vs. inline: frequency >3, complexity >medium" |
| Recurring knowledge errors | Add context discovery step | "Before using API, check current docs, not memory" |

> **STOP: Every adaptation