runbooks

Runbooks

This skill explains the runbook system for accumulating learnings.

Overview

Each agent has a companion runbook that accumulates learnings from past features:

• Patterns that worked
• Anti-patterns discovered
• Common mistakes
• Service-specific guidance

Location

Runbooks live in service repositories:

.claude/skills/runbooks/
├── product-discovery/
│   └── RUNBOOK.md
├── api-dev/
│   └── RUNBOOK.md
├── code-reviewer/
│   └── RUNBOOK.md
└── ...

Runbook Structure

# [Agent Name] Runbook

Last updated: YYYY-MM-DD

## Patterns That Work

### [Pattern Name]

**Context**: When to use this pattern

**Pattern**: What to do

**Example**:
```go
// Code example

Learned from: [Feature/PR reference]

Anti-Patterns

[Anti-Pattern Name]

Problem: What went wrong

Why it's bad: Impact

Instead: What to do instead

Learned from: [Feature/PR reference]

Service-Specific Notes

[Topic]

[Service-specific guidance for this agent's work]

Common Mistakes

• [Mistake 1]: [How to avoid]
• [Mistake 2]: [How to avoid]

## Updating Runbooks

After completing a feature or resolving an issue:

1. Identify reusable learnings
2. Categorize (pattern, anti-pattern, note)
3. Document with context
4. Reference the source (PR, issue)

## Agent Integration

Agents read their runbook during context discovery:

```markdown
## Context Discovery

...
5. Read your runbook at `.claude/skills/runbooks/{agent-name}/RUNBOOK.md` if it exists

Automatic Learning Integration

Runbooks are automatically updated by the learning engine:

1. code-reviewer logs findings to .claude/review-findings.jsonl with pattern names
2. Agents log session learnings to .claude/session-learnings.jsonl
3. /evolve command analyzes findings, calculates confidence, detects trends
4. Auto-promotion adds high-confidence patterns to runbooks

Auto-Promotion Criteria

Patterns are automatically promoted when:

• Occurrence count >= 3
• Confidence score >= 0.6
• Pattern has a clear description
• Pattern is not already promoted

Auto-Generated Entry Format

### {Pattern Name} (Auto-generated)

**Confidence**: 0.85 | **Occurrences**: 7 | **Trend**: stable

**Context**: When this pattern appears

**Anti-Pattern**: What to avoid

**Instead**: What to do

**Learned from**: PR #123, PR #145, PR #167

*Auto-generated by learning engine on 2025-01-15*

Manual vs Auto-Generated

• Manual entries: Added by humans, take precedence
• Auto-generated entries: Added by /evolve, marked with "(Auto-generated)"
• Conflicts: Manual entries are preserved; auto entries update statistics only

Commands

Command	Purpose
/evolve	Analyze findings and update runbooks
/patterns	View pattern statistics
/trends	View pattern trends and alerts

See learning-engine/SKILL.md for full documentation.

Cross-Agent Learning

Some learnings apply to multiple agents. These should be:

1. Documented in each relevant runbook
2. OR extracted to a shared skill

Example Entry

### Use sync.Once for Storage Initialization

**Context**: When creating REST storage handlers

**Pattern**: Use sync.Once to lazily initialize storage backends

**Example**:
```go
type REST struct {
    store     storage.Interface
    storeOnce sync.Once
}

func (r *REST) getStore() storage.Interface {
    r.storeOnce.Do(func() {
        r.store = newStorageBackend()
    })
    return r.store
}

Learned from: PR #123 - Race condition in storage initialization