Analyze development sessions to improve the toolkit: AGENTS.md, skills, configuration, hooks, and automation. Use when: (1) Ending a significant work session, (2) User says "reflect", "what did we learn", "improve the toolkit", "session review", or "capture learnings", (3) After completing a complex task to document discoveries, (4) When encountering repeated friction, manual steps, or permission denials, (5) Before starting a new major feature to review previous patterns. Outputs direct improvements to files and beads issues for larger work.
/plugin marketplace add gooditworks/ai/plugin install reflect@gooditworks-aiThis skill is limited to using the following tools:
LICENSE.txtreferences/checklist.mdreferences/examples.mdreferences/output-templates.mdscripts/gather_history.pyscripts/gather_permissions.pyscripts/gather_session.pyMeta-improvement skill that analyzes development sessions to enhance the toolkit itself.
python scripts/gather_session.pyhistory/reflections/YYYY-MM-DD-topic.mdVariants:
/reflect — Full 5-phase workflow/reflect quick — Skip to Phase 3, only P0 quick wins/reflect deep — Include cross-session analysis from history/reflections//reflect # Full reflection on current session
/reflect quick # Quick wins only (permissions, small doc fixes)
/reflect deep # Deep analysis with cross-session patterns
┌─────────────────────────────────────────────────────────────────┐
│ Phase 1: Session Analysis (gather what happened) │
├─────────────────────────────────────────────────────────────────┤
│ Phase 2: Pattern Recognition (identify improvements) │
├─────────────────────────────────────────────────────────────────┤
│ Phase 3: Categorize & Prioritize (sort by impact/effort) │
├─────────────────────────────────────────────────────────────────┤
│ Phase 4: Generate Improvements (create outputs) │
├─────────────────────────────────────────────────────────────────┤
│ Phase 5: Persist Learnings (save for future sessions) │
└─────────────────────────────────────────────────────────────────┘
Ask yourself (don't ask user unless needed):
What would have helped at session start?
What manual steps were repeated?
What problems were encountered?
What was discovered?
# Check recent git activity
git log --oneline -20
git diff --stat HEAD~5..HEAD
# Check beads activity
bd list --status=closed --limit=10
bd list --status=open
# Review any test failures encountered
# Review any typecheck issues fixed
Use checklist in references/checklist.md for detailed analysis.
| Pattern | Signal | Improvement Target |
|---|---|---|
| Same bash command approved 3+ times | Permission gap | .claude/settings.json |
| Searched for same pattern multiple times | Documentation gap | AGENTS.md |
| Skill triggered but had missing info | Skill gap | .claude/skills/*/SKILL.md |
| Skill should have triggered but didn't | Description gap | Skill frontmatter |
| Multi-step workflow repeated | Automation candidate | New skill or hook |
| Had to explain same thing to Claude | Context gap | CLAUDE.md or AGENTS.md |
| Workaround used instead of proper fix | Anti-pattern | Beads issue |
Flag these for proper fixes (not toolkit improvements):
as any) added during sessionCreate beads issues for anti-patterns, not documentation.
| Category | Target | Effort | Examples |
|---|---|---|---|
| Permissions | .claude/settings.json | Low | Add approved bash commands |
| Quick Docs | AGENTS.md | Low | Add gotcha, convention, pattern |
| Skill Fix | Existing skill | Medium | Update description, add section |
| New Skill | .claude/skills/ | High | New workflow automation |
| Hook | .claude/settings.json | Medium | Pre/post command automation |
| Tooling | Scripts, MCP | High | New automation scripts |
High Impact
│
┌──────────┼──────────┐
│ DO NOW │ SCHEDULE │
│ (P1) │ (P2) │
Low ──────────┼────────── High Effort
│ QUICK │ BACKLOG │
│ WINS(P0) │ (P3) │
└──────────┼──────────┘
│
Low Impact
See references/output-templates.md for templates.
For P0/P1 improvements, propose edits:
.claude/settings.jsonFor P2/P3 improvements, create beads issues:
# New skill needed
bd create "Create /skill-name skill for [workflow]" -t feature -p 2
# Larger documentation update
bd create "Document [pattern] in AGENTS.md" -t task -p 3
# Tooling improvement
bd create "Add [automation] script" -t feature -p 3
Create reflection summary in history/reflections/:
mkdir -p history/reflections
Filename: YYYY-MM-DD-brief-topic.md
Template:
# Reflection: [Date] - [Brief Topic]
## Session Summary
[1-2 sentences on what was done]
## Discoveries
- [Pattern/convention discovered]
- [Gotcha encountered]
## Improvements Made
- [x] Added X to AGENTS.md
- [x] Updated Y skill
- [ ] Created issue for Z
## Open Questions
- [Things still unclear]
## Patterns to Watch
- [Things that might recur]
When running /reflect deep, also:
history/reflections/# Permission audit - find commands that needed approval
# (Review session mentally, no command available)
# Check what skills exist
ls .claude/skills/
# Check current permissions
cat .claude/settings.json
# Create improvement issue
bd create "Improve: [description]" -t task -p 2
| Friction | Solution |
|---|---|
"I keep having to approve bun test" | Add Bash(bun test:*) to permissions |
| "I had to search for the auth pattern 3 times" | Add Auth section to AGENTS.md |
| "The /start-work skill didn't know about X" | Update skill with X info |
| "I wish there was a skill for Y" | Create new skill for Y |
| "Every session I have to explain Z" | Add Z to CLAUDE.md |
Note when these would have helped:
Create issues for MCP integrations that would add value.
Suggest hooks when you notice patterns like:
"You always run typecheck after editing .ts files"
→ Suggest: PostToolUse hook for Edit on .ts files
"You always check git status before committing"
→ Already should be doing this, but could be a reminder hook
"You always run tests after changing test files"
→ Suggest: PostToolUse hook for Edit on .test.ts files
Hook template:
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit",
"hooks": [{
"type": "command",
"command": "echo 'Consider running typecheck'"
}]
}]
}
}
Session observation: Approved bun test command 5 times during session
Analysis: Same command repeatedly approved = permission gap
Improvement:
// Add to .claude/settings.json permissions.allow
"Bash(bun test:*)"
Priority: P0 (quick win, implement immediately)
Session observation: Searched for "how to add a database migration" 3 times, eventually found the pattern in an old PR
Analysis: Information exists but not discoverable = documentation gap
Improvement:
// Add to AGENTS.md under Database section
### Creating Migrations
1. Run `bun run supabase migration new <name>`
2. Edit the generated SQL file in `packages/supabase/supabase/migrations/`
3. Run `bun run supabase migration up` to apply
4. Run `bun run generate:db` to regenerate TypeScript types
Priority: P1 (implement in session)
Session observation: When user said "let's review what we built today", the reflect skill didn't trigger
Analysis: Trigger phrase not in description = skill description gap
Improvement:
# Add to reflect skill description triggers
"review what we built", "end of session"
Priority: P0 (quick win)
Session observation: Performed the same 5-step PR review process manually 3 times
Analysis: Repeated multi-step workflow = new skill candidate
Improvement:
bd create "Create /review-pr skill for PR reviews" -t feature -p 2 \
--description "Automate the PR review workflow: fetch PR, analyze changes, check tests, suggest improvements"
Priority: P2 (create beads issue)
Copy this checklist to track your reflection progress:
Reflection Progress:
- [ ] Phase 1: Gathered session data (git log, beads, mental review)
- [ ] Phase 2: Identified patterns using Quick Checks table
- [ ] Phase 3: Categorized improvements by priority (P0-P3)
- [ ] Phase 4a: Implemented all P0 quick wins
- [ ] Phase 4b: Implemented P1 improvements (if time)
- [ ] Phase 4c: Created beads issues for P2/P3
- [ ] Phase 5: Saved reflection to history/reflections/
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.