retro

name	retro
description	Review the current session and propose improvements to CLAUDE.md, hooks, agents, and skills.
user-invocable	true

Session Retrospective Skill

Purpose

Analyze the current session's patterns and propose improvements to the Claude Code configuration (CLAUDE.md, hooks, agents, skills, rules).

Workflow

Step 0: Summarize Session Context

Before launching the agent, compile a session summary to pass as context:

1. List all commits made in this session (run git log --oneline for recent commits)
2. Identify key patterns: files modified, corrections made, repeated instructions, workflows executed
3. Note any rule violations or hook misfires observed

Format as a concise bullet list of session events.

Step 0: Collect Session Metrics

Before launching the agent, gather quantitative metrics:

1. git log --oneline — count commits in this session
2. Count AskUserQuestion invocations in the conversation
3. Count tool permission denials
4. Count plan revisions

Include these metrics in the agent prompt as structured data.

Step 0: Sweep Deflected / Dropped Review Findings

Before launching the agent, sweep the session for review findings that were surfaced but never acted on, so they are not silently lost:

1. security-guidance PreToolUse warnings that were acknowledged but not fixed (the edit went through anyway)
2. code-reviewer / silent-failure-hunter / security-review findings marked out-of-scope, deferred, or "later"
3. ReportFindings items the user deferred, and any "I'll note this for follow-up" the session made but never wrote down

For each surviving finding, capture it into TODO.md (project memory, or ~/.claude/pending-cognify/TODO.md if no project context) with: what the finding was, which reviewer/hook surfaced it, why it was deflected, and a concrete first step to close it. Include these captured items in the agent prompt so the retrospective can decide whether any warrant a rule/hook change.

If the sweep finds nothing, note "no deflected findings this session" and continue.

Step 1: Launch Retrospective Agent

Launch the session-retrospective agent in the background using the Agent tool:

• subagent_type: use the session-retrospective agent definition
• Include the session summary from Step 0 in the agent prompt as context
• Instruct: "Review the current conversation for patterns that could be codified into CLAUDE.md rules, hooks, agents, or skills."

Step 2: Present Findings

When the agent returns, present its findings in two sections:

Section A: Patterns to Reinforce — workflows, rules, or agent invocations that worked well this session. These should be preserved and not accidentally removed in future config changes.

Section B: Improvement Proposals — numbered list where each proposal includes:

1. What: the specific change (e.g., "add a hook that...", "add a rule that...")
2. Where: the target file (e.g., ~/.claude/rules/foo.md, settings.json)
3. Why: the pattern observed in this session that motivates the change

Step 3: User Selection

Use AskUserQuestion to let the user select which proposals to implement (multiSelect).

Step 4: Implement

For each approved proposal, implement the change. Follow existing patterns:

• Hooks: Ruby scripts in cookbooks/claude-code/files/hooks/, registered in settings.json
• Rules: Markdown files in cookbooks/claude-code/files/rules/ with appropriate frontmatter
• Agents: Markdown files in cookbooks/claude-code/files/agents/
• Skills: SKILL.md in cookbooks/claude-code/files/skills/<name>/
• CLAUDE.md: edit source of truth at cookbooks/claude-code/files/CLAUDE.md

After implementation, sync deploy targets and commit.