4.5 KiB
| name | description |
|---|---|
| reflect | 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:
# 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
- Review conversation: Scan for error messages, repeated commands, authentication failures
- Check todo list: Identify unexpected tasks added mid-session
- Measure friction: Estimate time on tooling vs implementation
- Filter ruthlessly: Exclude expected work and system constraints
- Focus on 1-3 issues: Quality over quantity
- 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