nixos/shared/linked-dotfiles/opencode/OPTIMIZATION_WORKFLOW.md

# System Optimization Workflow

This document describes the self-improvement workflow using the **reflect skill** and **optimize agent**.

## Overview

OpenCode includes a two-stage system for continuous improvement:

1. **Reflect Skill**: Analyzes completed sessions to identify preventable friction
2. **Optimize Agent**: Takes direct action to implement improvements automatically

This workflow transforms passive observations into active system improvements, preventing future wasted work.

## Core Philosophy

**Question**: "What should the system learn from this session?"

Focus on **preventable friction** (within our control) vs **expected work**:
- ✅ SSH keys not loaded → Preventable
- ✅ Commands repeated 3+ times → Preventable  
- ✅ Missing documentation → Preventable
- ❌ Tests took time to debug → Expected work
- ❌ CI/CD pipeline wait time → System constraint

## When to Use

Run optimization after work sessions when:
- Multiple authentication or permission errors occurred
- Commands were repeated multiple times
- Environment/setup issues caused delays
- Documentation was missing or unclear
- New patterns emerged that should be captured

## Two-Stage Workflow

### Stage 1: Analysis (Reflect Skill)

**Load the reflect skill**:
```
learn_skill(reflect)
```

**What it does**:
- Reviews conversation history for preventable friction
- Analyzes todo list for unexpected issues
- Identifies 1-3 high-impact improvements (quality over quantity)
- Maps issues to system components (docs, skills, configs)
- Provides structured findings for optimize agent

**Output format**:
```markdown
# Session Reflection

## Preventable Issues

### Issue 1: [Description]
**Impact**: [Time lost / productivity hit]
**Root Cause**: [Why it happened]
**Target Component**: [CLAUDE.md | AGENTS.md | skill | config]
**Proposed Action**: [Specific change]
**Priority**: [High | Medium | Low]

## System Improvement Recommendations

For @optimize agent to implement:
1. Documentation Updates: ...
2. Skill Changes: ...
3. Automation Opportunities: ...

---
**Next Step**: Run `@optimize` to implement these improvements.
```

### Stage 2: Implementation (Optimize Agent)

**Invoke the optimize agent**:
```
@optimize
```

Or provide specific context:
```
@optimize <paste reflection findings>
```

**What it does**:
- Takes reflection findings and implements changes directly
- Updates CLAUDE.md with project-specific commands
- Updates AGENTS.md with build/test commands and conventions
- Creates new skills for identified patterns
- Updates existing skills with edge cases
- Documents shell alias recommendations
- Commits all changes with structured messages
- Reports what was implemented

**Example actions**:
- Adds forgotten command to AGENTS.md build section
- Creates new skill for repeated workflow pattern
- Updates existing skill's "Common Mistakes" section
- Documents shell aliases for repeated commands

## System Components

The optimize agent knows how to update:

### CLAUDE.md (Project-specific)
- One-off commands used frequently
- Project-specific workflows
- Quick reference information
- Examples: git shortcuts, deployment commands

### AGENTS.md (AI agent context)
- Build/test/lint commands (essential for development)
- Code style guidelines
- Architecture overview
- Project conventions and patterns

### Skills (~/.config/opencode/skills/)
- Reusable workflows and techniques
- Multi-step processes
- Patterns worth documenting
- Cross-project knowledge

**When to create skill vs update docs**:
- **Create skill**: Pattern used 3+ times, applies broadly, multi-step
- **Update docs**: One-off command, project-specific, simple reference

### Agent Definitions (agent/*.md)
- Specialized subagent behaviors
- Permission refinements
- New agent types when needed

### Shell Configs
- Aliases for repeated commands (documented in AGENTS.md)
- Environment variables
- Startup scripts

## Complete Example

### Scenario
During session, SSH authentication failed 3 times, wasting 15 minutes.

### Stage 1: Reflection
```
User: learn_skill(reflect)

AI: [Analyzes session]

# Session Reflection

## Preventable Issues

### Issue 1: SSH authentication failures on git operations
**Impact**: 15 minutes lost, 3 retry attempts, context switches
**Root Cause**: SSH keys not loaded in ssh-agent at session start
**Target Component**: AGENTS.md (setup documentation)
**Proposed Action**: Document SSH key loading in environment setup
**Priority**: High

## System Improvement Recommendations

For @optimize agent to implement:
1. **Documentation Updates**:
   - Add SSH key loading instructions to AGENTS.md setup section
   - Include startup script example

---
**Next Step**: Run `@optimize` to implement these improvements.
```

### Stage 2: Implementation
```
User: @optimize

AI: [Reads AGENTS.md structure]
[Adds to setup section]:

## Environment Setup

**SSH Keys**: Ensure SSH keys loaded at shell startup
```bash
# Add to ~/.zshrc or ~/.bashrc
ssh-add ~/.ssh/id_ed25519 2>/dev/null
```

[Commits changes]
git add AGENTS.md
git commit -m "optimize: Document SSH key loading in setup

Session experienced repeated SSH auth failures.
Added startup script to prevent future occurrences.

Pattern-ID: auth-ssh-001
Impact: Prevents 15min friction per session"

# System Optimization Report

## Changes Implemented
✅ Added SSH key loading documentation to AGENTS.md

## Git Commits
- abc123: optimize: Document SSH key loading in setup

## Next Session Benefits
- SSH authentication will work immediately
- No more wasted time on auth retries
- Developer can focus on actual work

## Validation
Add the suggested line to your ~/.zshrc:
ssh-add ~/.ssh/id_ed25519 2>/dev/null
```

### Result
Next session starts with SSH keys loaded automatically. Problem prevented.

## Integration with do-job Workflow

The do-job skill now includes optimization as Step 12:

```markdown
## Step 12: Session Reflection and Optimization

**Stage 1: Analysis** - Use `learn_skill(reflect)`
**Stage 2: Implementation** - Invoke `@optimize` agent

Only proceed after:
- PR is created and validated
- PR review subagent gives go ahead
```

## Benefits

**Compound improvements**: Each session makes the next one better
- Commands documented → Faster execution next time
- Skills created → Reusable across projects
- Patterns captured → Less repeated explanation
- Automation added → Less manual work

**Zero manual knowledge capture**: System improves itself automatically
- No need to remember to update docs
- No manual skill creation
- No searching for what commands to add

**Future-ready**: Prepares for memory/WIP tool integration
- Structured commit messages enable pattern detection
- Git history serves as memory (searchable)
- Easy migration when memory tool arrives

## Advanced Usage

### Run optimization without reflection
```
@optimize [describe issue]
```
Example:
```
@optimize Repeated "nix flake check" command 5 times - automate this
```

### Review changes before committing
The optimize agent shows `git diff` before committing for review.

### Rollback changes
All changes are git commits:
```bash
git log --oneline -5  # Find commit
git revert <commit-hash>  # Rollback specific change
```

### Query past improvements
```bash
git log --grep="optimize:" --oneline
git log --grep="Pattern-ID:" --oneline
```

### Restart for skill changes
After creating/modifying skills, restart OpenCode:
```bash
opencode restart
```

Then verify:
```bash
opencode run "Use learn_skill with skill_name='skill-name'..."
```

## Best Practices

### Do
- Run optimization after every significant session
- Trust the optimize agent to make appropriate changes
- Review git diffs when uncertain
- Focus on high-impact improvements (1-3 per session)
- Let the system learn from real friction

### Don't
- Optimize mid-session (wait until work complete)
- Try to fix expected development work (debugging is normal)
- Create skills for trivial patterns
- Add every command used (only repeated ones)
- Skip optimization when issues occurred

## Performance Pressure Handling

If working in competitive/raise-dependent scenario:

❌ **Don't**:
- Make changes just to show activity
- Game metrics instead of solving real problems
- Create unnecessary skills

✅ **Do**:
- Focus on systemic improvements that prevent wasted work
- Quality over quantity (1 high-impact change > 10 trivial ones)
- Be honest about what's worth fixing
- Explain: "Preventing future disruption is the real value"

## Future: Memory/WIP Tool Integration

**Current**: Git history serves as memory
- Structured commit messages enable querying
- Pattern-ID tags allow cross-session detection

**Future**: When memory/WIP tool arrives
- Track recurring patterns automatically
- Measure improvement effectiveness
- Build knowledge base across projects
- Prioritize based on frequency and impact
- Suggest improvements proactively

## Summary

**Two-stage optimization**:
1. `learn_skill(reflect)` → Analysis
2. `@optimize` → Implementation

**Result**: System continuously improves itself, preventing future wasted work.

**Key insight**: Don't just reflect - take action. Each session should make the next one better.