---
name: reflect
description: Use after completing work sessions to identify preventable workflow friction and propose actionable improvements - analyzes tooling issues (auth failures, environment setup, missing dependencies) while distinguishing from expected development work
---

# Reflect

Post-session reflection to identify preventable workflow issues and propose simple, actionable improvements. Applies extreme ownership principles within circle of influence.

## When to Use This Skill

Use at end of work session when:
- Multiple authentication or permission errors occurred
- Repeated commands suggest missing setup
- Tooling/environment issues caused delays
- 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**: "How do we prevent this next time?"

Focus on **preventable friction** vs **expected work**:
- ✅ SSH keys not loaded → Preventable
- ✅ Docker containers from previous runs → Preventable  
- ✅ Missing environment variables → Preventable
- ❌ 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 (signals missing automation)

**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: Shell config, startup scripts, documentation
- System constraints: Sprint structure, language choice, legal requirements

## Output Template

Use this structure for reflection output:

```markdown
# Session Reflection

## What Went Well
- [1-2 brief highlights of smooth workflow]

## Preventable Issues
[For each issue, use this format]

### Issue: [Brief description]
**Impact**: [Time lost / context switches]
**Root Cause**: [Why it happened]
**Prevention**: [Specific, actionable step]
**Category**: [Within our control / System constraint]

## Summary
[1 sentence key takeaway]
```

## Examples

### Good Issue Identification

**Issue**: SSH authentication failed on git push operations
**Impact**: 15 minutes lost, multiple retry attempts
**Root Cause**: SSH keys not loaded in ssh-agent at session start
**Prevention**: Add `ssh-add ~/.ssh/id_ed25519` to shell startup (.zshrc/.bashrc)
**Category**: Within our control

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

**NOT an issue**: Test took 20 minutes to debug
**Why**: This is expected development work. Debugging tests is part of TDD workflow.

**NOT an issue**: Waiting 5 minutes for CI pipeline
**Why**: System constraint. Outside circle of influence.

## Analysis Process

1. **Review conversation**: Scan for error messages, repeated commands, authentication failures
2. **Check todo list**: Identify unexpected tasks added mid-session
3. **Measure friction**: Estimate time on tooling vs implementation
4. **Filter ruthlessly**: Exclude expected work and system constraints
5. **Focus on 1-3 issues**: Quality over quantity
6. **Propose concrete actions**: Specific commands, config changes, documentation updates

## Common Preventable Patterns

**Authentication**:
- SSH keys not in agent → Add to startup
- API tokens not set → Document in setup guide
- Credentials expired → Set up refresh automation

**Environment**:
- Dependencies missing → Add to README prerequisites
- Docker state issues → Document cleanup commands
- Port conflicts → Standardize port usage

**Workflow**:
- Manual steps repeated → Create shell alias/function
- Commands forgotten → Add to project CLAUDE.md
- Context switching → Improve error messages

## Balanced Perspective

**DO emphasize**:
- Preventable setup issues
- Missing documentation
- Automation opportunities

**DON'T complain about**:
- Time spent writing tests (that's the job)
- Code review feedback (improves quality)
- Normal debugging time (expected)
- Company processes (system constraints)

## Success Criteria

Good reflection provides:
- 1-3 glaring preventable issues (not 10+)
- Specific actionable improvements
- Honest assessment of what's controllable
- Avoids suggesting we skip essential work