cai-capture-lesson

CAI Capture Lesson

Overview

Performs a session retrospective: reviews the current session's work, classifies learnings, and routes each item to the appropriate CAI document via the relevant cai-add-* skill.

When to Use

• End of a productive session where debugging, design decisions, or new patterns occurred
• Action routing: "failure mode/패턴 발견" triggers this skill
• User explicitly requests a session retrospective
• AI suggests knowledge capture after resolving a non-trivial issue

CRITICAL: This skill requires active session context to function. It reviews what happened in the current conversation. Do NOT invoke in a fresh session with no prior work.

Workflow

1. Session Review

Review the current session's work to identify knowledge worth capturing:

• What problems were encountered? (bugs, errors, unexpected behaviors)
• What solutions were found? (root causes, fixes, workarounds)
• What patterns were established? (new conventions, architectural patterns)
• What decisions were made? (technology choices, design trade-offs)
• What was surprising or non-obvious? (gotchas, counterintuitive behaviors)

2. Classify Learnings

Categorize each identified item:

Classification	Target Document	Routing Skill
Failure mode (bug root cause found)	Issue doc OR agent spec's Failure Modes table (Symptom-Cause-Fix)	Direct write or cai-add-spec
New pattern (reusable approach discovered)	Convention or spec	cai-add-spec
Architecture decision (alternatives compared, one chosen)	ADR	cai-add-decision
Future improvement idea	Roadmap item	cai-add-roadmap

Failure Mode format (for agent spec tables):

Symptom	Cause	Fix
{Observable behavior}	{Root cause}	{Resolution steps}

3. Present to User

For each classified item, present a one-line summary and proposed action:

Session Retrospective:

1. [Failure Mode] Redis connection timeout under load
   → Add to context/issues/redis-connection-timeout.md
   [approve / reject / edit]

2. [Pattern] Retry with exponential backoff for external API calls
   → Add to context/conventions/external-api-retry.md
   [approve / reject / edit]

3. [Decision] Chose message queue over direct HTTP for service communication
   → Create context/decisions/003-message-queue-over-http.md
   [approve / reject / edit]

4. Route Approved Items

For each item the user approves:

Classification	Action
Failure mode → new issue	Create context/issues/{slug}.md with severity, description, and fix
Failure mode → existing agent spec	Append to the Failure Modes table in the relevant agent or spec
New pattern → new convention	Create context/conventions/{topic}.md
New pattern → existing spec	Update the relevant spec via cai-add-spec
Architecture decision	Invoke cai-add-decision skill
Future improvement	Invoke cai-add-roadmap skill

5. Summary

After all approved items are processed, display a summary:

Captured 3 items:
  ✓ context/issues/redis-connection-timeout.md (created)
  ✓ context/conventions/external-api-retry.md (created)
  ✓ context/decisions/003-message-queue-over-http.md (created)

Agent Invocations

This skill primarily routes to other skills rather than directly invoking agents. However, for failure mode items that need to be added to agent spec tables:

• Direct file editing is used (no agent invocation needed for simple table appends)

For items routed to other skills:

• cai-add-decision is invoked for architecture decisions
• cai-add-spec is invoked for pattern documentation in specs
• cai-add-roadmap is invoked for future improvement ideas

Output

Artifact	Path	Format
Issue documents	context/issues/{slug}.md	Markdown with YAML frontmatter (issue type)
Convention documents	context/conventions/{topic}.md	Markdown with YAML frontmatter (convention type)
Decision documents	context/decisions/{NNN}-{slug}.md	Via cai-add-decision
Roadmap documents	context/roadmap/{status}/{slug}.md	Via cai-add-roadmap
Updated spec/agent files	Various	Appended Failure Modes rows or pattern sections

Error Handling

Error	Action
No session context available (fresh session)	Inform user this skill requires an active session with prior work. Suggest reviewing git log instead.
User rejects all proposed items	Acknowledge and end gracefully. No documents created.
Routing to cai-add-decision fails	Fall back to direct ADR creation using the decision format
Target document for failure mode append does not exist	Create a new issue document instead