141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
---
|
|
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
|