reflect-on-work
Pattern for producing quality reflections after completing work. Required for all agent outputs.
When & Why to Use This Skill
This Claude skill implements a structured reflection framework designed to enhance AI agent reliability and continuous learning. By mandating post-task analysis, it captures critical 'knowledge updates' regarding codebases and conventions while documenting successes and failures. This pattern ensures transparent agent behavior, facilitates system evolution, and provides a data-driven feedback loop for optimizing complex agentic workflows.
Use Cases
- Post-Task Performance Analysis: Automatically evaluates task execution to identify successful strategies and avoidable failures, directly improving the success rate of subsequent tasks.
- Dynamic Knowledge Capture: Records newly discovered codebase structures, architectural decisions, and technical 'gotchas' to maintain an accurate and up-to-date mental model of the project.
- Workflow Pattern Recognition: Detects recurring sequences and coding patterns during development to suggest systemic improvements or the creation of new specialized skills.
- Agent Debugging and Audit Trails: Provides a structured JSON output of the agent's internal reasoning and learning process, making it easier for developers to monitor, troubleshoot, and refine agent behavior.
| name | reflect-on-work |
|---|---|
| description | Pattern for producing quality reflections after completing work. Required for all agent outputs. |
| allowed-tools | Read |
Reflect on Work Skill
Pattern for producing quality reflections.
When to Load This Skill
- You are completing any task
- You need to produce the mandatory reflection fields
- You want to contribute to system evolution
Required Output Fields
EVERY agent output MUST include these fields in compact JSON:
{"knowledge_updates":[{"category":"codebase","content":"What you learned","confidence":"certain"}],"reflection":{"what_worked":["string"],"what_failed":["string"],"patterns_noticed":["string"]}}
Knowledge Updates
Categories
- codebase: Discovered structure, components, data flow
- convention: Coding style, patterns, naming
- decision: Design choice and rationale
- gotcha: Pitfall, workaround, non-obvious behavior
Confidence Levels
- certain: Verified, tested, documented
- likely: Strong evidence but not verified
- uncertain: Observed but needs confirmation
Examples
{"knowledge_updates":[{"category":"convention","content":"Project uses barrel exports in each directory","confidence":"certain"},{"category":"gotcha","content":"Must call init() before using AuthService","confidence":"certain"},{"category":"codebase","content":"API routes follow /api/v1/{resource} pattern","confidence":"likely"}]}
Reflection Fields
what_worked
- Strategies that succeeded
- Tools that helped
- Approaches worth repeating
what_failed
- Strategies that didn't work
- Time wasted on wrong approaches
- Issues encountered
patterns_noticed
- Repeated sequences (skill candidates)
- Common patterns in codebase
- Workflow improvements
Example
{"reflection":{"what_worked":["Parallel explorers found context quickly","Starting with types helped structure code"],"what_failed":["Initial approach missed edge case","Spent time on wrong file before exploring"],"patterns_noticed":["Error handling always uses Result type","Tests colocated with source files"]}}
Complete Output Example
Minimal valid output with reflection:
{"task_id":"task-001","status":"pre_complete","files_modified":[],"knowledge_updates":[],"reflection":{"what_worked":[],"what_failed":[],"patterns_noticed":[]}}
Full output with content:
{"task_id":"task-001","status":"pre_complete","files_modified":[{"path":"src/auth.ts","change_type":"modified","summary":"Added login function"}],"knowledge_updates":[{"category":"convention","content":"Auth uses JWT tokens","confidence":"certain"}],"reflection":{"what_worked":["Found existing patterns quickly"],"what_failed":["Initial test approach was wrong"],"patterns_noticed":["All services use dependency injection"]}}
Principles
- Be honest - Report failures, they're valuable
- Be specific - Actionable insights, not vague
- Be brief - Concise, not exhaustive
- Use compact JSON - Single line, no formatting