---
name: reflect
description: Use after work sessions to analyze preventable friction and guide system improvements - provides framework for identifying issues, then directs to optimize agent for implementation
---

# Reflect

Analyzes completed work sessions to identify preventable workflow friction and system improvement opportunities. Focuses on issues within circle of influence that can be automatically addressed.

## When to Use This Skill

Use at end of work session when:
- Multiple authentication or permission errors occurred
- Repeated commands suggest missing setup or automation
- Tooling/environment issues caused delays
- Pattern emerged that should be captured in skills/docs
- User explicitly requests reflection/retrospective

**When NOT to use:**
- Mid-session (wait until work complete)
- For expected development work (debugging logic, fixing tests)
- For system constraints outside control (CI/CD wait times, language limitations)

## Core Principle

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

Focus on **preventable friction** vs **expected work**:
- ✅ SSH keys not loaded → Preventable (add to shell startup)
- ✅ Commands repeated 3+ times → Preventable (create alias or add to CLAUDE.md)
- ✅ Missing environment setup → Preventable (document in AGENTS.md)
- ❌ Tests took time to debug → Expected work
- ❌ Code review iterations → Expected work
- ❌ CI/CD pipeline wait time → System constraint

## Analysis Framework

Review conversation history and todo list for:

**Tooling Issues** (high-value targets):
- Authentication failures (SSH, API tokens, credentials)
- Permission errors (file access, git operations)
- Environment setup gaps (missing dependencies, config)
- Repeated command patterns (3+ uses signals missing automation)

**Knowledge Gaps** (documentation opportunities):
- Commands not in CLAUDE.md/AGENTS.md
- Skills that should exist but don't
- Skills that need updates (new patterns, edge cases)
- Workflow improvements that should be automated

**System Components**:
- Context files: CLAUDE.md (commands), AGENTS.md (build/test commands, conventions)
- Skills: Reusable workflows and techniques
- Agent definitions: Specialized subagent behaviors
- Shell configs: Aliases, functions, environment variables

**Time Measurement**:
- Tooling friction time vs actual implementation time
- Repeated failures on same issue
- Context switches due to environment problems

**Circle of Influence**:
- Within control: Documentation, skills, shell config, automation
- System constraints: Language limitations, company policies, hardware

## Reflection Output

Produce structured analysis mapping issues to system components:

```markdown
# Session Reflection

## What Went Well
- [1-2 brief highlights]

## Preventable Issues

### Issue 1: [Brief description]
**Impact**: [Time lost / context switches / productivity hit]
**Root Cause**: [Why it happened - missing doc, setup gap, no automation]
**Target Component**: [CLAUDE.md | AGENTS.md | skill | shell config | agent]
**Proposed Action**: [Specific change to make]
**Priority**: [High | Medium | Low]

[Repeat for 1-3 high-value issues max]

## System Improvement Recommendations

For @optimize agent to implement:

1. **Documentation Updates**:
   - Add [command/pattern] to [CLAUDE.md/AGENTS.md]
   - Document [setup step] in [location]

2. **Skill Changes**:
   - Create new skill: [skill-name] for [purpose]
   - Update [existing-skill]: [specific addition]

3. **Automation Opportunities**:
   - Shell alias for [repeated command]
   - Script for [manual process]

## Summary
[1 sentence key takeaway]

---

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

## Analysis Process

1. **Review conversation**: Scan for error messages, repeated commands, authentication failures
2. **Check todo list**: Identify unexpected tasks added mid-session, friction points
3. **Identify patterns**: Commands repeated 3+ times, similar errors, knowledge gaps
4. **Measure friction**: Estimate time on tooling vs implementation
5. **Filter ruthlessly**: Exclude expected work and system constraints
6. **Focus on 1-3 issues**: Quality over quantity - only high-impact improvements
7. **Map to system components**: Where should each fix live?
8. **Provide structured output**: Format for optimize agent to parse and execute

## Common Preventable Patterns

**Authentication**:
- SSH keys not in agent → Add `ssh-add` to shell startup
- API tokens not set → Document in AGENTS.md setup section
- Credentials expired → Document refresh process

**Environment**:
- Dependencies missing → Add to AGENTS.md prerequisites
- Docker state issues → Document cleanup commands in CLAUDE.md
- Port conflicts → Document port usage in AGENTS.md

**Documentation**:
- Commands forgotten → Add to CLAUDE.md commands section
- Build/test commands unclear → Add to AGENTS.md build section
- Setup steps missing → Add to AGENTS.md or README

**Workflow**:
- Manual steps repeated 3+ times → Create shell alias or script
- Pattern used repeatedly → Extract to skill
- Agent behavior needs refinement → Update agent definition

**Skills**:
- Missing skill for common pattern → Create new skill
- Skill missing edge cases → Update existing skill's "Common Mistakes"
- Skill references outdated → Update examples or references

## Distinguishing Analysis from Implementation

**This skill (reflect)**: Provides analysis framework and structured findings
**Optimize agent**: Takes findings and implements changes automatically

**Division of responsibility**:
- Reflect: Identifies what needs to change and where
- Optimize: Makes the actual changes (write files, create skills, update docs)

After reflection, invoke `@optimize` with findings for automatic implementation.

## Examples

### Good Issue Identification

**Issue**: SSH authentication failed on git push operations
**Impact**: 15 minutes lost, 4 retry attempts, context switches
**Root Cause**: SSH keys not loaded in ssh-agent at session start
**Target Component**: Shell config (.zshrc)
**Proposed Action**: Add `ssh-add ~/.ssh/id_ed25519` to .zshrc startup
**Priority**: High

### Pattern Worth Capturing

**Issue**: Repeatedly explaining NixOS build validation workflow
**Impact**: 10 minutes explaining same process 3 times
**Root Cause**: No skill for NixOS-specific workflows
**Target Component**: New skill
**Proposed Action**: Create `nixos-development` skill with build/test patterns
**Priority**: Medium

### Documentation Gap

**Issue**: Forgot test command, had to search through project
**Impact**: 5 minutes searching for command each time used
**Root Cause**: Test command not in AGENTS.md
**Target Component**: AGENTS.md
**Proposed Action**: Add `nix flake check` to build commands section
**Priority**: High

### Non-Issue (Don't Report)

**NOT an issue**: Debugging Nix configuration took 30 minutes
**Why**: This is expected development work. Learning and debugging configs is part of NixOS development.

**NOT an issue**: Waiting for large rebuild
**Why**: System constraint. Build time is inherent to Nix architecture.

## Balanced Perspective

**DO emphasize**:
- Preventable setup issues
- Missing documentation
- Automation opportunities
- Knowledge capture (skills, patterns)
- System improvements

**DON'T complain about**:
- Time spent on actual work (that's the job)
- Normal debugging and learning
- Inherent tool characteristics
- Company processes (system constraints)

## Integration with Optimize Agent

After reflection analysis:

1. Review reflection findings
2. Invoke `@optimize` to implement improvements
3. Optimize agent will:
   - Update CLAUDE.md/AGENTS.md with commands/docs
   - Create or update skills based on patterns
   - Create shell aliases for repeated commands
   - Generate git commits with changes
   - Report what was implemented

This two-stage process:
- **Reflect**: Analysis and identification (passive, focused)
- **Optimize**: Implementation and automation (active, powerful)

## Success Criteria

Good reflection provides:
- 1-3 high-impact preventable issues (not 10+ minor ones)
- Clear mapping to system components (where to make changes)
- Specific actionable improvements (not vague suggestions)
- Honest assessment of circle of influence
- Structured format for optimize agent to parse
- Avoids suggesting we skip essential work

## Future Memory Integration

When memory/WIP tool becomes available, reflection will:
- Track recurring patterns across sessions
- Build knowledge base of improvements
- Measure effectiveness of past changes
- Detect cross-project patterns
- Prioritize based on frequency and impact

For now, git history serves as memory (search past reflection commits).