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:

# 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:

git log --oneline -5  # Find commit
git revert <commit-hash>  # Rollback specific change

Query past improvements

git log --grep="optimize:" --oneline
git log --grep="Pattern-ID:" --oneline

Restart for skill changes

After creating/modifying skills, restart OpenCode:

opencode restart

Then verify:

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.