nixos/shared/linked-dotfiles/opencode/skills/reflect/SKILL.md

name	description
reflect	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:

# 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).