You are performing a self-reflection on the current conversation to capture operational knowledge that would otherwise be lost when context clears.
Captures operational knowledge from conversations to preserve workflows, patterns, and corrections for future sessions.
/plugin marketplace add jezweb/claude-skills/plugin install jezweb-project-workflow-skills-project-workflow@jezweb/claude-skillsYou are performing a self-reflection on the current conversation to capture operational knowledge that would otherwise be lost when context clears.
DO NOT run bash commands to scan files for dates, versions, or "last updated" references. This reflection is about the conversation that just happened - work entirely from what you remember from our session.
DO NOT:
DO:
Extract operational knowledge from this session - workflows discovered, patterns learned, tool sequences, and nuanced approaches that don't belong in commits, planning docs, or progress tracking but would be valuable for future Claude Code sessions.
Key Insight: This captures "how we work" not "what we built" or "what we decided".
/reflect [optional: specific-topic]
If a topic is provided, focus reflection on that area. Otherwise, reflect on the entire session.
| Knowledge Type | Existing Home | /reflect Captures? |
|---|---|---|
| Code changes | Git commits | No - already saved |
| Architecture decisions | Planning docs | No - already saved |
| Progress/next steps | SESSION.md | No - already saved |
| Feature specs | /brief → docs/ | No - use /brief |
| Workflows discovered | ??? | YES |
| Effective sequences | ??? | YES |
| Tool patterns | ??? | YES |
| Nuanced approaches | ??? | YES |
| Corrections (what worked vs didn't) | ??? | YES |
| Educational insights (★ Insight boxes) | ??? | YES |
Review the current conversation and identify:
Workflows Discovered
Patterns Learned
Tool Sequences
Corrections
Discoveries
Rule Candidates
Educational Insights
★ Insight boxes in the conversationIMPORTANT: Rules are the preferred destination for most technical learnings. CLAUDE.md files should only contain personal preferences and high-level workflow guidance - NOT technology-specific corrections.
Route each learning to the most appropriate destination:
| Knowledge Type | Destination | Criteria |
|---|---|---|
| Syntax correction | Rules (project or user) | Claude suggested wrong pattern |
| File-scoped pattern | Rules (project or user) | Applies to specific file types |
| Technology correction | Rules (user-level) | Applies across all projects using this tech |
| Technology pattern | Rules OR skill | Prompt: project-only, user-level rule, or skill? |
| Project workflow | ./CLAUDE.md | Project-specific process/convention |
| Personal preference | ~/.claude/CLAUDE.md | Account IDs, spelling, timezone - NOT tech corrections |
| Skill improvement | ~/.claude/skills/X/SKILL.md | Improves a specific skill |
| Complex process | docs/learnings.md | Multi-step, worth documenting |
| Session context | SESSION.md | Temporary, this session only |
| Repeatable process | Script or command | Will do this again, automate it |
| Educational insight | Skill docs, rules, or ~/.claude/insights/ | Tech-specific → skill; General → insights folder |
Rule Scope Decision:
| Scope | Location | When to Use |
|---|---|---|
| Project-only | .claude/rules/[name].md | Unique to this project's setup |
| User-level (all projects) | ~/.claude/rules/[name].md | Applies to ALL your projects using this tech |
| Skill-bundled | ~/.claude/skills/X/rules/[name].md | Standard correction, ship with skill |
Routing Heuristics (Priority Order):
Correction patterns (Claude suggested wrong syntax) → Rules FIRST
.claude/rules/~/.claude/rules/File-scoped patterns (applies to *.ts, *.css, etc.) → Rules
Technology-specific knowledge → User-level rules or Skill
~/.claude/rules/Personal preferences (spelling, timezone, accounts) → ~/.claude/CLAUDE.md
Project conventions (how this specific project works) → ./CLAUDE.md
If we'll do this again → Script, command, or workflow automation
Anti-Pattern to Avoid: ❌ Adding technology corrections to CLAUDE.md (bloats it, always loaded, not file-scoped) ✅ Adding technology corrections to rules (file-triggered, focused, portable)
Beyond documentation, look for processes worth operationalizing:
Signs a process should become a script/command:
Automation options to suggest:
scripts/do-thing.sh) - For CLI sequencescommands/thing.md) - For Claude Code workflowspackage.json) - For project-specific dev tasks.claude/agents/thing.md) - For autonomous workflows requiring reasoningWhen to suggest a custom agent vs script/command:
| Characteristic | Script/Command | Custom Agent |
|---|---|---|
| Sequential steps only | ✅ | Overkill |
| Requires reasoning/decisions | Use command | ✅ |
| Needs parallel execution | ❌ | ✅ |
| Research/exploration task | Use command | ✅ |
| Benefits from fresh context | ❌ | ✅ |
| Variable inputs, same pattern | Either | ✅ |
Agent indicators (suggest custom agent when):
When suggesting automation:
### Automation Opportunity
**Process**: [What we did repeatedly]
**Frequency**: [How often this happens]
**Complexity**: [Number of steps, error potential]
**Suggestion**: Create [script/command/etc]
**Location**: [Where it would live]
**Benefit**: [Time saved, errors prevented]
Create this automation? [Y/n]
Show the user what was found in this format:
## Session Reflection
### Workflows Discovered
1. **[Name]**: [Description]
→ Proposed destination: [file path]
### Patterns Learned
1. **[Name]**: [Description]
→ Proposed destination: [file path]
### Tool Sequences
1. **[Tools involved]**: [When to use this sequence]
→ Proposed destination: [file path]
### Corrections Made
1. **[What didn't work → What worked]**
→ Proposed destination: [file path]
### Discoveries
1. **[What was found]**: [Why it matters]
→ Proposed destination: [file path]
### Rule Candidates
1. **[Pattern Name]**: [What Claude suggested vs what works]
- Paths: `[file patterns this applies to]`
→ Proposed: `.claude/rules/[name].md`
→ Also update skill? [Yes if technology-wide, otherwise No]
### Educational Insights
1. **[Topic]**: [Insight content]
- Category: [UX/Architecture/Performance/Pattern]
→ Proposed destination: [path]
### Automation Opportunities
1. **[Process name]**: [What we did manually]
- Steps: ~[N] steps
- Frequency: [How often we'd do this]
- Reasoning required: [Yes/No]
→ Suggestion: Create [script/command/agent] at [location]
---
**Proposed Updates:**
- [ ] [File 1]: Add [brief description]
- [ ] [File 2]: Update [brief description]
- [ ] Create docs/learnings.md with [topics]
**Proposed Automation:**
- [ ] Create [scripts/thing.sh]: [Brief description]
- [ ] Add npm script "[name]": [Brief description]
- [ ] Create slash command [/name]: [Brief description]
- [ ] Create custom agent [.claude/agents/name.md]: [Brief description]
Proceed? [Y/n/edit]
If nothing significant found: Report "No significant operational knowledge identified in this session that isn't already captured elsewhere." and ask if user wants to highlight something specific.
After user confirms:
For each rule candidate the user approved:
Create directory if needed:
mkdir -p .claude/rules
Determine file paths to scope the rule:
**/*.css, **/*.tsx, wrangler.jsonc, src/server/**/*.tsGenerate rule file with proper format:
---
paths: "[comma-separated glob patterns]"
---
# [Descriptive Name]
[1-2 sentences explaining why this rule exists]
## [Category Name]
| If Claude suggests... | Use instead... |
|----------------------|----------------|
| `[wrong pattern]` | `[correct pattern]` |
Create file at .claude/rules/[name].md
If user indicated "all projects with this tech":
~/.claude/skills/[skill-name]/~/.claude/skills/[skill-name]/rules/[name].mdAdd to appropriate existing section or create new section:
## [Section Name]
**[Pattern/Workflow Name]**: [Description]
- Step 1: ...
- Step 2: ...
- Why: [Reasoning]
Add to troubleshooting, patterns, or relevant section:
### [Pattern/Tip Name]
[Description of what works]
**Why**: [Explanation]
# Project Learnings
## [Date]: [Topic]
**Context**: [What we were doing]
**Learning**: [What we discovered]
**Application**: [When/how to use this]
---
Add to "Notes" or "Context" section:
**Session Note**: [Brief learning that's relevant to next session]
Create new file with YAML frontmatter:
---
paths: "**/*.tsx", "**/*.jsx", "src/components/**"
---
# [Rule Name]
[Brief context for why this rule exists]
## Corrections
| If Claude suggests... | Use instead... |
|----------------------|----------------|
| `[wrong pattern]` | `[correct pattern]` |
| `[wrong pattern]` | `[correct pattern]` |
## Context
[Optional: Additional explanation if needed]
Discovered: "When creating skills, the effective sequence is: check existing patterns → copy template → fill SKILL.md → test install → verify discovery"
Routing: Add to ~/.claude/CLAUDE.md under Skill Usage Protocol (universal workflow)
Discovered: "Wrangler D1 issues: always check migrations ran on BOTH local AND remote before debugging code"
Routing: Add to ~/.claude/skills/cloudflare-d1/SKILL.md troubleshooting section
Discovered: "For context management: /wrap-session first, then compact, then /continue-session loads just what's needed"
Routing: Add to ~/.claude/CLAUDE.md Session Handoff Protocol section
Discovered: "In this project, auth tokens are validated in middleware before reaching handlers"
Routing: Add to ./CLAUDE.md (project-specific)
Discovered: "Every time we add a new skill, we: copy template, fill SKILL.md, update README, run install script, run check-metadata, test discovery"
Routing: Suggest creating /create-skill slash command or scripts/new-skill.sh
Discovered: "Before releases we always: run gitleaks, check for SESSION.md, verify .gitignore, run npm audit"
Routing: Suggest creating scripts/pre-release-check.sh or /release command
Discovered: "Claude kept suggesting @tailwind base but Tailwind v4 uses @import 'tailwindcss'"
Routing: Create rule with paths **/*.css
./claude/rules/), all your projects (~/.claude/rules/), or update tailwind-v4-shadcn skill?"Discovered: "User prefers Australian English spelling"
Routing: Add to ~/.claude/CLAUDE.md under preferences
Discovered: "Drizzle timestamp mode stores seconds not milliseconds - Date.now() causes dates 55,000 years in future"
Routing: Create ~/.claude/rules/drizzle-timestamps.md with paths **/*.ts, drizzle/**
Discovered: "Lucide dynamic imports get tree-shaken in production - need explicit icon map"
Routing: Create ~/.claude/rules/lucide-tree-shaking.md with paths **/*.tsx
~/.claude/rules/ NOT ~/.claude/CLAUDE.mdDiscovered: "The toolbar pattern (fixed position at bottom) is common for editing overlays because it doesn't obscure content, is always accessible, and provides clear separation"
Routing:
~/.claude/insights/ui-patterns.md or docs/learnings.mdDetection method: Scan conversation for the pattern ★ Insight to extract these automatically.
Discovered: "When auditing skills, we: check official docs, compare patterns, verify versions, check for deprecations, update content. This requires reasoning about accuracy and completeness."
Routing: Suggest creating .claude/agents/skill-auditor.md
Agent template:
---
name: skill-auditor
description: "Skill content auditor. MUST BE USED when auditing skills. Use PROACTIVELY for knowledge validation."
tools: [Read, Grep, Glob, Bash, WebFetch, Write, Edit]
model: sonnet
---
## Goal
Validate skill content against official documentation.
## Process
1. Read skill's SKILL.md
2. Fetch official documentation
3. Compare patterns and versions
4. Report gaps and inaccuracies