session-reflect

Analyze the current session's work to extract reusable knowledge for the playbook system (ACE pattern). Produces structured output for the playbook-curator sub-agent to apply.

<quick_start> Run at the end of a session before creating a handoff:

1. Reviews work completed in the session
2. Identifies what strategies were helpful vs harmful
3. Extracts new learnings for the playbook
4. Outputs structured JSON for playbook-curator

This skill does NOT modify playbook files directly. It outputs proposals for review. </quick_start>

Gather Session Context Understand what was accomplished this session. Review git log for recent commits in this session Review any task lists or progress tracking Identify major accomplishments and issues encountered

<step_2>

Load Current Playbook Read existing playbook files to avoid duplicates and find bullets to update. Find playbook directory: look for .ai-agents/playbook/ in project root or parent directories Read all JSON files: strategies.json, pitfalls.json, code-patterns.json, decisions.json If hierarchical (root + project levels exist), load both levels

<step_3>

Identify Helpful Bullets Used Review which existing playbook bullets were applied during this session. Which strategies from the playbook were explicitly followed? Which pitfalls were successfully avoided? Which code patterns were reused? Which past decisions guided current work? List of bullet IDs that were helpful this session

<step_4>

Identify Harmful or Outdated Bullets Identify any playbook bullets that caused issues or are now outdated. Did any strategy recommendations lead to problems? Were any pitfall warnings inaccurate or misleading? Did any code patterns fail or need modification? Did any past decisions prove incorrect in hindsight? List of bullet IDs that were harmful or need revision

<step_5>

Extract New Learnings Identify new knowledge gained this session. New approaches that worked well and should be reused Must be generalizable beyond this specific task Must be actionable guidance, not just observations Mistakes encountered that should be avoided in future Must describe both the mistake AND how to avoid it Must be a pattern that could recur, not a one-off error Reusable code snippets or patterns Must be generic enough to apply to multiple situations Should include context for when to use the pattern Significant decisions made with rationale Must be architectural or strategic, not trivial Must include rationale that helps future sessions understand why

<step_6>

Generate Reflection Output Produce structured JSON output for the playbook-curator. ```json { "session_id": "NNN", "timestamp": "ISO-8601", "bullets_used": { "helpful": ["strat-00007"], "harmful": [], "neutral": [] }, "new_bullets": { "strategies": [ { "content": "Description of strategy", "context": "category", "rationale": "Why this is valuable" } ], "pitfalls": [ { "content": "Description of pitfall and how to avoid", "context": "category", "rationale": "Why this matters" } ], "code_patterns": [ { "content": "Description of pattern", "snippet": "code here", "context": "category", "rationale": "When to use this" } ], "decisions": [ { "content": "Decision and rationale", "context": "category", "expected_outcome": "What we expect to happen" } ] }, "summary": "Brief summary of session learnings" } ```

Iterative refinement: If the initial extraction seems incomplete or low-quality, review your own output and refine up to 3 iterations before finalizing. </output_format> </step_6>

<step_7>

Present Reflection for Review Present the reflection output to the user for review before curator processing. Display the structured JSON output Highlight any harmful bullets that need attention Summarize count of new bullets proposed Ask user if they want to proceed with /playbook-update

<step_8>

Offer to Create Linear Issues for Discovered Work If the reflection identified actionable improvements, bugs, or tech debt that require code changes, offer to create Linear issues. Review the new_bullets output — filter for items that represent actionable code work (not just knowledge). Look for pitfalls that need fixing, strategies that imply missing features, or decisions that require implementation. If actionable items exist (at least 1), present them and ask: "Create Linear issues for [N] discovered items? (y/n)" If user declines or no actionable items: skip to completion If user accepts: 1. Resolve Linear team (same pattern as /add-to-todos): check CLAUDE.md → list_teams → auto-select or ask 2. Ensure "discovered" label exists: check via list_issue_labels, create with create_issue_label if missing (name: "discovered", color: "#FF6B35") 3. For each actionable item, create a Linear issue via create_issue: - **title**: Action verb + component (3-8 words) - **team**: Resolved team - **state**: "Backlog" - **labels**: ["discovered"] - **description**: Markdown formatted: ``` **Discovery:** [What was found]

   **Context:** [From which playbook category — strategy/pitfall/pattern/decision]

   **Rationale:** [Why this needs action]

   ---
   *Discovered during /session-reflect (Session [N])*
   ```

4. Report created issues: "Created [N] Linear issues: [LINEAR_ID_1], [LINEAR_ID_2], ..." </step_8>

<playbook_format> Playbooks use JSON files with this bullet format:

{
  "id": "strat-00001",
  "helpful": 5,
  "harmful": 0,
  "content": "Strategy description",
  "context": "category",
  "created_session": 1,
  "last_used_session": 10
}

ID prefixes by type:

• strategies: strat-NNNNN
• pitfalls: pitfall-NNNNN
• code-patterns: code-NNNNN
• decisions: dec-NNNNN

Files: strategies.json, pitfalls.json, code-patterns.json, decisions.json Each file has: {"_schema": {"version": "1.0"}, "bullets": [...]} </playbook_format>

<success_criteria> Session context is fully loaded and understood Existing playbook bullets are checked for relevance Helpful bullets are identified with specific usage context Harmful or outdated bullets are flagged for review New learnings are extracted and categorized correctly Output JSON is valid and complete User has opportunity to review before curator processes </success_criteria>

<integration_notes> This skill outputs JSON but does NOT modify playbook files After reflection, run /playbook-update to apply changes via curator Works with hierarchical playbooks (root + project) or single-level </integration_notes>