Session Retrospective

Table of Contents

• •When to Use
• •Phase 1: Analysis
• •Phase 2: Skill Inventory Review
• •Phase 3: Create Plan
• •Phase 4: Execute with Approval
• •Skill Gap Patterns
• •Refactoring Patterns

When to Use

Run at the end of significant sessions:

• •After debugging a complex issue
• •After implementing a new feature
• •After onboarding to a new area of the codebase
• •When you notice repeated patterns
• •Periodically (weekly/monthly) for skill hygiene

Phase 1: Session Analysis

Review the current session for patterns. Do NOT make changes yet.

1.1 Repeated Commands

What commands did you run more than 3 times?

# Check bash history for patterns
history | grep -E "kubectl|helm|git" | sort | uniq -c | sort -rn | head -20

1.2 Long Debugging Cycles

What took longest to figure out?

• •Did I try multiple approaches before finding the right one?
• •Was there a "trick" that finally worked?
• •Would a checklist have helped?

1.3 Repeated Lookups

What information did you search for repeatedly?

• •API endpoints, configuration keys, command flags
• •Error message meanings
• •"How do I..." questions

1.4 Missing Workflows

Signs of missing workflow:

• •"I wish I had known to do X first"
• •"The order matters: A before B before C"
• •"This only works if Y is configured"

Phase 1b: Commit History Analysis

Analyze recent commit history to identify blind paths and wasted iterations.

1b.1 Review Recent Commits

git log --oneline -30

1b.2 Identify Revert/Fix Chains

Look for patterns that indicate wrong paths were taken:

git log --oneline -50 | grep -iE "revert|fix:|fixup|undo|retry|attempt"

1b.3 Classify Blind Paths

For each revert/fix chain, classify the root cause:

1b.4 Count Wasted Iterations

# Count fix/revert commits vs feature commits in last 30
echo "Feature commits:"
git log --oneline -30 | grep -cvE "fix:|revert|fixup|undo"
echo "Fix/revert commits:"
git log --oneline -30 | grep -ciE "fix:|revert|fixup|undo"

A healthy ratio is 3:1 (feature:fix). Below 2:1 means the agent is taking too many blind paths.

1b.5 Analyze What the Agent Explored

Review the session conversation for:

• •Hypotheses tested: How many guesses before finding the right fix?
• •Commands that returned nothing useful: Ran a command, got no insight, tried another
• •Repeated "let me try another approach": Sign of missing decision guidance
• •Correct exploration: Some unknown paths are expected — the agent should explore options when the situation is genuinely ambiguous

1b.6 Build Skills from Bad Paths

For each blind path identified, determine if a skill can prevent it:

Phase 2: Skill Inventory Review

Review existing skills for refactoring opportunities. Do NOT make changes yet.

2.1 List All Skills

find .claude/skills -name "SKILL.md" | sort

2.2 Check for Duplicates

Look for skills that cover similar ground:

2.3 Best Practices Check

For each skill, verify:

• • Frontmatter has name and description
• • TOC included if over 50 lines
• • Commands are copy-pasteable and tested
• • Troubleshooting section exists
• • Links to related skills are valid
• • No outdated information

2.4 Identify Refactoring Candidates

Common refactoring needs:

• •Merge: k8s:pods and k8s:health have overlapping pod checks
• •Split: A skill covers both Kind and OpenShift but patterns differ
• •Rename: Skill name doesn't match what it actually does
• •Restructure: Category no longer makes sense

Phase 3: Create Plan

Write a plan document for approval. Include all proposed changes.

Plan Template

Create docs/SKILL_RETROSPECTIVE_<date>.md:

# Skill Retrospective Plan - [Date]

## Session Context
[What was the session about?]

## Proposed Changes

### New Skills to Create
| Skill | Reason | Priority |
|-------|--------|----------|
| `category/name` | Gap identified when... | High/Medium/Low |

### Skills to Update
| Skill | Change | Reason |
|-------|--------|--------|
| `category/name` | Add X | Missing from workflow |

### Skills to Refactor
| Action | Skills | Reason |
|--------|--------|--------|
| Merge | `a`, `b` → `c` | Overlapping content |
| Split | `x` → `y`, `z` | Too broad |
| Rename | `old` → `new` | Clarity |

### Skills to Delete
| Skill | Reason |
|-------|--------|
| `category/name` | Superseded by X |

## Questions for Review
- Should X and Y be merged?
- Is category Z still relevant?

## Estimated Effort
- New skills: N
- Updates: M
- Refactors: K

Present Plan

Show the plan to the user and ask:

Here's my retrospective plan. Before I make any changes:

1. •Do these proposed changes make sense?
2. •Should I prioritize any specific items?
3. •Are there changes you'd skip or modify?

Phase 4: Execute with Approval

Only after user approves the plan, execute changes.

4.1 Execute in Order

1. •Refactors first - Prevents creating skills that will be immediately restructured
2. •Updates second - Improve existing before adding new
3. •New skills last - Build on clean foundation

4.2 Checkpoint After Each Major Change

After significant changes, pause and confirm:

Completed: [description]. Continue with next item?

4.3 Final Commit

Commit all changes with comprehensive message:

docs: Session retrospective skill updates

- Created: auth/new-skill
- Updated: k8s:health with pod debugging
- Merged: testing/a + testing/b → testing/combined
- Deleted: obsolete/skill

Based on [session context].

Skill Gap Patterns

Refactoring Patterns

When to Merge Skills

• •Two skills share >50% of commands
• •Users always use them together
• •Distinction is confusing

When to Split Skills

• •Skill has multiple "modes" or use cases
• •Different audiences need different parts
• •Skill is over 200 lines

When to Rename/Move

• •Name doesn't match actual purpose
• •Category has changed
• •Consistency with other skills

When to Delete

• •Superseded by better skill
• •No longer applicable (deprecated tool/pattern)
• •Never actually used

Related Skills

• •skills:write - Template for new skills
• •skills:scan - Full repo audit and gap analysis