fix: use agent reasoning for playbook selection (not keyword matching)

**Step 1b (Load Playbooks):** - Agent reads playbook index - Agent reads story requirements - Agent DECIDES which playbooks are relevant - Loads only applicable playbooks (0-3 max) **Step 12 (Extract Learnings):** - Agent self-reflects on implementation - What went well? What went wrong? - What patterns emerged? What mistakes made? - Agent decides which playbooks to update - Specific, evidence-based learnings only **Why Better:** - Agent understands context (not dumb keyword match) - Can connect concepts (charge creation = billing) - Won't load irrelevant playbooks - Won't miss relevant playbooks with different terminology **Example:** Story: 'Create charge model with state machine' Agent sees: billing-playbook (charge creation), state-machine-playbook (transitions) Agent decides: Load both (relevant) Agent skips: queue-playbook (not needed), auth-playbook (not applicable) Much smarter than: story contains 'charge' → load all playbooks with 'charge'.
2026-01-26 10:16:42 -05:00 · 2026-01-26 10:16:42 -05:00 · 645c8b4822
parent 981d6f75b0
commit 645c8b4822
2 changed files with 587 additions and 528 deletions
--- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/steps/step-01b-load-playbooks.md
+++ b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/steps/step-01b-load-playbooks.md
@ -1,297 +1,355 @@
-# Step 1b: Load Applicable Playbooks (Automated Learning)
+# Step 1b: Load Applicable Playbooks (Agent Reasoning)
-**Goal:** Automatically load relevant playbooks and learnings before implementation starts
+**Goal:** Agent reads playbook index, understands story requirements, decides which playbooks to load
 ---
-## What This Step Does
+## Process
-Before writing any code, check if previous work has created playbooks/patterns that apply to this story. This creates a **positive feedback loop** where agents get smarter with each story.
+### 1. Read Playbook Index
---
+**Load the playbook manifest:**
 ## Execution
 ### 1. Analyze Story for Keywords
 **Extract topics from story:**
 ```bash
-story_file="{story_file}"
+playbook_index="{project-root}/docs/playbooks/index.md"
-# Extract keywords from:
+if [ ! -f "$playbook_index" ]; then
-# - Story title
+  echo "📚 No playbook index found - skipping (will create after first story)"
-# - Task descriptions
+  exit 0
 # - Technical Requirements section
 # - Architecture Compliance section
 keywords=$(grep -E "^### Task|^## Technical|^## Architecture" "$story_file" | \
  grep -oiE "(prisma|stripe|auth|cron|queue|state machine|billing|payment|migration|api|database|email|notification|cache|redis|s3)" | \
  sort -u | tr '\n' ',' | sed 's/,$//')
 echo "📚 Story keywords: $keywords"
 ```
 **Common keyword categories:**
 - **Technology:** Database ORM, payment processor, cache, storage, infrastructure
 - **Domain:** Business logic areas (determined by your project)
 - **Pattern:** Architecture patterns (state machine, cron, queue, api, etc.)
 ### 2. Check for Existing Playbooks
 **Search playbook directory:**
 ```bash
 playbook_dir="{project-root}/docs/playbooks"
 if [ ! -d "$playbook_dir" ]; then
  echo "📚 No playbooks directory found - will create after implementation"
  playbooks_loaded=0
  skip_to_step_2=true
 fi
 # For each keyword, check if playbook exists
 applicable_playbooks=()
 for keyword in $(echo "$keywords" | tr ',' ' '); do
  playbook_file="${playbook_dir}/${keyword}-playbook.md"
  if [ -f "$playbook_file" ]; then
    echo "✅ Found playbook: ${keyword}-playbook.md"
    applicable_playbooks+=("$playbook_file")
  fi
 done
 echo "📚 Applicable playbooks: ${#applicable_playbooks[@]}"
 ```
-### 3. Load Playbooks (If Found)
+**Index format:**
 **For each applicable playbook:**
 ```
 Read playbook file
 Extract sections:
  - ## Best Practices
  - ## Common Pitfalls
  - ## Code Patterns
  - ## Lessons Learned
  - ## Do's and Don'ts
 Store in context for use during implementation
 ```
 **Example:**
 ```markdown
-📚 Loaded: {technology}-playbook.md
+# Playbook Index
-Best Practices:
+## Available Playbooks
 - {Practice learned from previous implementations}
 - {Pattern that worked successfully}
 - {Standard established across stories}
-Common Pitfalls:
+### billing-playbook.md
- {Mistake that was made and fixed}
+**Topics:** Charge creation, payment processing, idempotency, Stripe integration
- {Issue encountered and resolved}
+**Stories:** 18-1, 18-3, 19-4
- {Edge case discovered}
+**Patterns:** 8 code patterns, 5 pitfalls documented
 **Last Updated:** 2026-01-26
-Code Patterns:
+### state-machine-playbook.md
- {Reusable pattern with code example}
+**Topics:** State transitions, validation rules, invalid state handling
- {Configuration approach}
+**Stories:** 18-1, 17-8, 6-1
- {Testing strategy}
+**Patterns:** 4 code patterns, 3 pitfalls documented
 **Last Updated:** 2026-01-25
 ### database-migration-playbook.md
 **Topics:** Prisma migrations, enum handling, transaction splitting, year validation
 **Stories:** 18-1, 17-5, 17-1
 **Patterns:** 6 code patterns, 8 pitfalls documented
 **Last Updated:** 2026-01-26
 ```
-### 4. Request Additional Context (If Needed)
+### 2. Read Story Requirements
-**If no playbooks found but keywords detected:**
+**Understand what this story is about:**
 ```
 🔍 No existing playbooks for: {keywords}
 Checking for project-level guidance...
 ```
 **Use /get-playbook to request specific guidance:**
 ```bash
-# For each keyword without playbook
+# Read from story file:
-for keyword in $keywords_without_playbooks; do
+# - Story description (user story)
-  echo "📖 Requesting playbook: $keyword"
+# - Acceptance criteria (what to build)
 # - Tasks section (how to build it)
 # - Technical Requirements (constraints)
-  # Invoke /get-playbook with keyword
+story_description=$(sed -n '/^## Story/,/^##/p' "$story_file" | head -20)
-  # This searches docs/, pulls from project context, creates on-demand playbook
+tasks=$(sed -n '/^## Tasks/,/^##/p' "$story_file" | head -50)
 technical_reqs=$(sed -n '/^## Technical Requirements/,/^##/p' "$story_file" | head -30)
 ```
-  # If guidance found, cache for future use
+### 3. Agent Decides Which Playbooks to Load
 **Reasoning prompt to agent:**
 ```
 You are about to implement Story {story_key}.
 Story Description:
 {story_description}
 Tasks Overview:
 {first 10 tasks from story}
 Technical Requirements:
 {technical_requirements}
 ---
 Available Playbooks:
 1. billing-playbook.md
   Topics: Charge creation, payment processing, idempotency, Stripe integration
   Patterns: 8 | Pitfalls: 5
 2. state-machine-playbook.md
   Topics: State transitions, validation rules, invalid state handling
   Patterns: 4 | Pitfalls: 3
 3. database-migration-playbook.md
   Topics: Prisma migrations, enum handling, transaction splitting
   Patterns: 6 | Pitfalls: 8
 4. queue-playbook.md
   Topics: SQS integration, message processing, retry logic
   Patterns: 5 | Pitfalls: 4
 ---
 QUESTION: Which playbooks (if any) are relevant to this story's implementation?
 Consider:
 - What technologies will you use? (database, payment, queue, etc.)
 - What patterns are needed? (state machine, cron, idempotency, etc.)
 - What challenges might you face? (migrations, async processing, etc.)
 Respond with:
 - Playbook filenames to load (0-3 playbooks maximum)
 - Brief reason why each is relevant
 Example response:
 "Load: billing-playbook.md (story involves charge creation), state-machine-playbook.md (implementing status transitions)"
 ```
 ### 4. Load Selected Playbooks
 **Based on agent's decision:**
 ```bash
 # Agent responded: "Load billing-playbook.md, state-machine-playbook.md"
 for playbook in $selected_playbooks; do
  playbook_path="${playbook_dir}/${playbook}"
  echo "📖 Loading: $playbook"
  # Read playbook file
  # Extract and present:
  # - Top 5 Best Practices
  # - Top 3 Common Pitfalls
  # - Most recent Code Pattern
  # (Not entire file - keep it focused)
  echo "✅ Loaded: $playbook"
 done
 ```
-### 5. Display Loaded Context
+### 5. Present to Agent
-**Output to agent:**
+**Concise, actionable format:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📚 APPLICABLE LEARNINGS LOADED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Story: {story_key}
 Keywords: {keywords}
 Playbooks Loaded: {count}
 1. prisma-playbook.md - Database schema best practices
 2. state-machine-playbook.md - State transition patterns
 3. billing-playbook.md - Payment processing learnings
 Key Guidance:
 ✅ Use 2026 in migration names (not 2025)
 ✅ Split enum add + use into 2 migrations
 ✅ Test state transitions exhaustively
 ✅ Idempotency keys for all charges
 ✅ Never hardcode payment amounts
 These learnings come from previous story implementations.
 Use them to avoid repeating past mistakes.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 ---
 ## Integration Points
 **This step runs:**
 - After Step 1 (Init) - story file loaded
 - Before Step 2 (Gap Analysis) - context ready
 - Before Step 3 (Write Tests) - patterns available
 - Before Step 4 (Implement) - guidance active
 **Feeds into:**
 - Step 2: Gap analysis sees playbook patterns
 - Step 3: Test patterns from playbooks
 - Step 4: Implementation follows playbook best practices
 - Step 7: Code review compares against playbook standards
 ---
 ## File Structure
 ```
 docs/
  playbooks/
    prisma-playbook.md        # Prisma best practices
    stripe-playbook.md        # Stripe integration patterns
    auth-playbook.md          # Authentication learnings
    state-machine-playbook.md # State machine patterns
    cron-playbook.md          # Cron job patterns
    billing-playbook.md       # Billing/payment learnings
    migration-playbook.md     # Database migration rules
 ```
 ---
 ## Playbook Template
 ```markdown
-# {Technology/Domain} Playbook
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📚 APPLICABLE PLAYBOOKS LOADED (2)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-**Last Updated:** {date}
+**1. billing-playbook.md**
 **Source Stories:** {story-keys that contributed learnings}
-## Best Practices
+🎯 Top Practices:
 - Generate idempotency keys: `charge-{agreementId}-{period}-{type}`
 - Use Decimal for money: `amount Decimal @db.Decimal(10, 2)`
 - Validate before creating: Check agreement exists, amount > 0
-1. {Practice from successful implementations}
+⚠️ Pitfalls to Avoid:
-2. {Pattern that worked well}
+- Don't create duplicate charges (use idempotency key unique constraint)
-3. {Standard we always follow}
+- Don't hardcode amounts (pull from agreement.monthlyRent)
-## Common Pitfalls
+💡 Recent Pattern (Story 18-1):
 ❌ {Mistake that was made}
 ✅ {How to avoid it}
 ❌ {Another mistake}
 ✅ {Correct approach}
 ## Code Patterns
 **Pattern: {Name}**
 ```typescript
-// Code example from actual implementation
+export async function createCharge(input: CreateChargeInput) {
-// Story: {story-key}
+  const idempotencyKey = generateIdempotencyKey(...)
  // Check for existing charge first
  const existing = await prisma.charge.findUnique({
    where: { idempotencyKey }
  })
  if (existing) return existing
  // Create new charge
  return prisma.charge.create({...})
 }
 ```
-**When to use:** {Context}
+**2. state-machine-playbook.md**
 **When NOT to use:** {Anti-pattern}
-## Lessons Learned
+🎯 Top Practices:
 - Define STATE_TRANSITIONS map with all valid paths
 - Validate before transition: `if (!isValidTransition()) throw error`
 - Log all state changes for audit trail
-**Story {story-key}:**
+⚠️ Pitfalls to Avoid:
- Learned: {Insight}
+- Don't allow arbitrary transitions (use validation map)
- Applied: {How we changed approach}
+- Don't forget to update related entities (e.g., space status)
 - Result: {Outcome}
-## Do's and Don'ts
+💡 Recent Pattern (Story 17-8):
 ```typescript
 const STATE_TRANSITIONS = {
  ACTIVE: ['TERMINATING', 'TERMINATED'],
  TERMINATING: ['TERMINATED'],
  // ...
 }
-**DO:**
+function isValidTransition(from, to) {
- {Positive practice}
+  return STATE_TRANSITIONS[from]?.includes(to) ?? false
- {What works}
+}
 ```
-**DON'T:**
+Apply these learnings to Story {story_key}.
- {What to avoid}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 - {Anti-pattern}
 ## References
 - Story implementations: {list of story-keys}
 - Architecture docs: {relevant docs}
 - External resources: {links}
 ```
 ---
-## Benefits
+## Why This is Better Than Keyword Matching
-**Positive Feedback Loop:**
+**Keyword Matching (Dumb):**
-1. Story 18-1 implements Prisma migration → Learns "use 2026 in names"
+```
-2. Story 18-1 complete → Extracts pattern → Saves to prisma-playbook.md
+Story mentions "billing" → Load billing-playbook.md
-3. Story 18-2 starts → Loads prisma-playbook.md → Applies learning
+Story mentions "payment" → Load payment-playbook.md
-4. Story 18-2 implements correctly first time (no year mistake)
+```
 - Doesn't understand context
 - Might load irrelevant playbooks
 - Might miss relevant playbooks (different words, same concept)
-**Cumulative Intelligence:**
+**Agent Reasoning (Smart):**
- Epic 1: Creates foundational playbooks
+```
- Epic 2: Builds on Epic 1 playbooks, adds new learnings
+Agent reads: "Create charge model with state machine"
- Epic 18: Has 17 epics worth of learnings available
+Agent sees playbooks: billing, state-machine, queue, auth
- Gets smarter with every story
+Agent decides: "This is about billing + state transitions"
-
+Agent loads: billing-playbook.md, state-machine-playbook.md
-**Prevents Repeated Mistakes:**
+Agent skips: queue-playbook.md (not relevant), auth-playbook.md (not needed)
- Migration year mistakes (happened multiple times)
+```
- Enum transaction limitations (PostgreSQL gotcha)
+- Understands what the story is actually about
- Story file naming inconsistencies (just experienced!)
+- Makes intelligent decisions
- Missing checkbox updates (just fixed!)
+- Loads only relevant playbooks
 - Can connect concepts (charge creation = billing)
 ---
-## Auto-Load Triggers
+## Step 12: Extract Learnings (Self-Reflection)
-**Automatic playbook loading based on story content:**
+### Agent Self-Reflection Prompt
-| Story Contains | Auto-Load Playbooks |
+**After implementation completes, ask agent:**
 |----------------|---------------------|
 | Database ORM keywords | database-orm-playbook.md, migration-playbook.md |
 | Payment keywords | payment-playbook.md, billing-playbook.md |
 | Auth keywords | auth-playbook.md, security-playbook.md |
 | Scheduling keywords | cron-playbook.md, scheduling-playbook.md |
 | Queue/async keywords | queue-playbook.md, async-playbook.md |
 | State machine keywords | state-machine-playbook.md |
 | Email/notification keywords | email-playbook.md, notification-playbook.md |
-**Note:** Playbook names are derived from keywords found in your story files.
+```
-The system adapts to your project's technology stack.
+You just completed Story {story_key}.
 Implementation Summary:
 - Files created: {file_list}
 - Tests written: {test_count}
 - Code review findings: {issue_count} issues (all fixed)
 - Commit: {commit_hash}
 ---
-## Next Step
+SELF-REFLECTION:
-When complete, continue to Step 2 (Pre-Gap Analysis) with loaded playbooks in context.
+1. What went well during this implementation?
   - What patterns or approaches worked effectively?
   - What code is worth reusing in future stories?
-**Next:** `{workflow_path}/steps/step-02-pre-gap-analysis.md`
+2. What problems did you encounter?
   - What mistakes did you make?
   - What errors occurred?
   - How did you fix them?
 3. What would you do differently next time?
   - What prevention checks would catch these issues earlier?
   - What validation would help?
 4. Which playbooks should be updated?
   - Look at the technologies/patterns you used
   - Which playbooks (if any) helped you?
   - Which playbooks should exist but don't?
 Respond with:
 - Patterns to add/update (with code examples)
 - Pitfalls to document (with prevention)
 - Playbooks to create/update (by name)
 ```
 ### Based on Agent Response, Update Playbooks
 **Agent responds:**
 ```
 Went well:
 - Idempotency key pattern prevented duplicate charges
 - State machine validation caught invalid transitions
 Problems:
 - Initially forgot to update space status on agreement termination
 - Enum transaction error (tried to add + use in one migration)
 Do differently:
 - Add checklist: "After state change, check related entities"
 - Always split enum additions into separate migrations
 Playbooks to update:
 - billing-playbook.md: Add idempotency pattern
 - state-machine-playbook.md: Add "check related entities" reminder
 - database-migration-playbook.md: Add enum transaction pitfall
 ```
 **Then execute updates:**
 ```bash
 # For each playbook to update
 # 1. Read current playbook
 # 2. Append new entry to appropriate section
 # 3. Update frontmatter (source_stories, pattern_count, last_updated)
 # 4. Write updated playbook
 # 5. Commit with message: "docs: update {playbook} from Story {story_key} learnings"
 ```
 ---
 ## Playbook Index Maintenance
 **Auto-update index when playbooks change:**
 ```bash
 # After Step 12 updates playbooks, regenerate index
 cat > docs/playbooks/index.md <<EOF
 # Playbook Index
 Last Updated: $(date +%Y-%m-%d)
 Total Playbooks: $(ls -1 docs/playbooks/*-playbook.md | wc -l | tr -d ' ')
 ## Available Playbooks
 EOF
 # For each playbook
 for playbook in docs/playbooks/*-playbook.md; do
  basename=$(basename "$playbook")
  # Extract frontmatter
  topics=$(grep "^keywords:" "$playbook" | cut -d: -f2)
  stories=$(grep "^source_stories:" "$playbook" | cut -d: -f2)
  pattern_count=$(grep "^pattern_count:" "$playbook" | cut -d: -f2)
  last_updated=$(grep "^last_updated:" "$playbook" | cut -d: -f2)
  # Generate index entry
  cat >> docs/playbooks/index.md <<ENTRY
 ### $basename
 **Topics:** $topics
 **Stories:** $stories
 **Patterns:** $pattern_count patterns documented
 **Last Updated:** $last_updated
 ENTRY
 done
 git add docs/playbooks/index.md
 git commit -m "docs: update playbook index (${playbook_count} playbooks)"
 ```
 ---
 **Key Difference:** Agent READS index, UNDERSTANDS story, DECIDES which playbooks are relevant. Not dumb keyword matching.
--- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/steps/step-12-extract-learnings.md
+++ b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/steps/step-12-extract-learnings.md
@ -1,254 +1,276 @@
-# Step 12: Extract Learnings & Update Playbooks (Automated Feedback Loop)
+# Step 12: Extract Learnings & Update Playbooks (Agent Self-Reflection)
-**Goal:** Extract patterns from completed implementation and save to playbooks for future stories
+**Goal:** Agent reflects on what was learned during implementation and updates playbooks for future stories
 ---
-## What This Step Does
+## Process
-After successful implementation, analyze what was built and extract:
+### 1. Verify Story Quality (Skip if Low Quality)
 - Patterns that worked well
 - Mistakes that were made and fixed
 - Code examples worth reusing
 - Best practices discovered
-Save these to playbooks so future stories benefit from this learning.
+**Only extract from successful, clean implementations:**
---
+```bash
 story_file="{story_file}"
-## Execution
+# Check task completion
 checked_tasks=$(grep -c "^- \[x\]" "$story_file" || echo "0")
 total_tasks=$(grep -c "^- \[[x ]\]" "$story_file" || echo "0")
-### 1. Analyze Implementation
+if [ "$total_tasks" -eq 0 ]; then
  echo "⏭️  No tasks in story - skipping learning extraction"
  exit 0
 fi
-**Review what was built:**
+completion_pct=$((checked_tasks * 100 / total_tasks))
 if [ "$completion_pct" -lt 80 ]; then
  echo "⏭️  Story only $completion_pct% complete - skipping extraction"
  echo "    (Only extract learnings from successful implementations)"
  exit 0
 fi
 echo "✅ Story completion: $completion_pct% - proceeding with extraction"
 ```
 ### 2. Gather Implementation Context
 **Collect facts about what was built:**
 ```bash
 story_key="{story_key}"
 # Get commit for this story
-commit_hash=$(git log --oneline --grep="$story_key" -i | head -1 | cut -d' ' -f1)
+commit_hash=$(git log --oneline --all --grep="$story_key" -i | head -1 | awk '{print $1}')
 if [ -z "$commit_hash" ]; then
-  echo "⚠️ No commit found for $story_key - skipping learning extraction"
+  echo "⚠️ No commit found for $story_key - skipping"
  exit 0
 fi
-# Get files changed
+# Extract implementation details
 files_changed=$(git diff-tree --no-commit-id --name-only -r "$commit_hash")
 file_count=$(echo "$files_changed" | wc -l | tr -d ' ')
 commit_message=$(git show --no-patch --format="%s" "$commit_hash")
-echo "📊 Analyzing implementation:"
+# Check for code review
-echo "  Story: $story_key"
+review_file="{sprint_artifacts}/review-${story_key}.md"
-echo "  Commit: $commit_hash"
+has_review=false
-echo "  Files: $(echo "$files_changed" | wc -l | tr -d ' ')"
+critical_issues=0
-```
+high_issues=0
 ### 2. Extract Applicable Keywords
 **From story file and code:**
 ```bash
 # Extract from story title, tasks, and file paths
 keywords=$(cat "{story_file}" | \
  grep -oiE "(prisma|stripe|auth|cron|queue|state.machine|billing|payment|migration|api|database|email|notification|terraform|sqs)" | \
  sort -u)
 # Also extract from file paths
 tech_keywords=$(echo "$files_changed" | \
  grep -oiE "(billing|payment|auth|email|queue|cron|migration)" | \
  sort -u)
 all_keywords=$(echo -e "$keywords\n$tech_keywords" | sort -u | tr '\n' ',' | sed 's/,$//')
 echo "🔑 Keywords for playbook matching: $all_keywords"
 ```
 ### 3. Check Code Review Findings
 **If code review was executed, extract learnings:**
 ```bash
 review_file="docs/sprint-artifacts/review-${story_key}.md"
 if [ -f "$review_file" ]; then
-  echo "📝 Code review exists - extracting learnings"
+  has_review=true
-
+  critical_issues=$(grep -c "CRITICAL" "$review_file" || echo "0")
-  # Extract issues that were fixed
+  high_issues=$(grep -c "HIGH" "$review_file" || echo "0")
  critical_issues=$(grep -A 3 "CRITICAL" "$review_file" || echo "none")
  high_issues=$(grep -A 3 "HIGH" "$review_file" || echo "none")
  # These become "Common Pitfalls" in playbooks
 fi
 echo "📊 Implementation Context:"
 echo "  Commit: $commit_hash"
 echo "  Files: $file_count"
 echo "  Code Review: $has_review ($critical_issues critical, $high_issues high)"
 ```
-### 4. Identify Reusable Patterns
+### 3. Agent Self-Reflection
-**Parse code for patterns worth saving:**
+**Present context and ask agent to reflect:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🤔 STORY COMPLETION SELF-REFLECTION
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 You just completed Story {story_key} ({completion_pct}% complete).
 Implementation Summary:
 - Files created/modified: {file_count} files
 - Commit: {commit_hash}
 - Commit message: {commit_message}
 - Code review: {critical_issues} critical, {high_issues} high issues (all fixed)
 Files Changed:
 {files_changed}
 ---
 SELF-REFLECTION QUESTIONS:
 1. **What Patterns Emerged?**
   - Did you create any reusable functions/utilities?
   - Are there code patterns worth documenting for future stories?
   - What file structures or naming conventions worked well?
 2. **What Mistakes Were Made?**
   - What errors did you encounter during implementation?
   - What did code review catch?
   - What would have prevented these issues?
 3. **What Was Learned?**
   - What surprised you about this implementation?
   - What assumptions were wrong?
   - What would you do differently next time?
 4. **Technology/Domain Insights?**
   - What technologies were used? (database ORM, payment API, queue, etc.)
   - What business domain? (billing, auth, notification, etc.)
   - What architectural patterns? (state machine, cron, idempotency, etc.)
 ---
 RESPOND WITH STRUCTURED LEARNINGS:
 Format your response as:
 **PATTERNS TO SAVE:**
 ```
 Pattern: {Name}
 Technology: {tech}
 Code Example: {10-20 lines from your implementation}
 When to Use: {specific scenario}
 File: {source file path}
 ```
 **PITFALLS TO DOCUMENT:**
 ```
 Mistake: {What went wrong}
 Error: {Exact error message if applicable}
 Fix: {How you resolved it}
 Prevention: {Code/check to avoid in future}
 Technology: {tech where this applies}
 ```
 **BEST PRACTICES:**
 ```
 Practice: {Specific action}
 Reason: {Why it works}
 Example: {Command or code snippet}
 Technology: {tech where this applies}
 ```
 **PLAYBOOKS TO UPDATE:**
 - {playbook-name}: {what to add}
 - {playbook-name}: {what to update}
 Be specific. Include actual code from your implementation, not made-up examples.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 ### 4. Parse Agent Response
 **Extract structured learnings from agent's self-reflection:**
 ```bash
-# Look for:
+# Agent response will contain sections:
-# - Well-structured functions (with JSDoc, error handling, tests)
+# - PATTERNS TO SAVE
-# - Reusable utilities
+# - PITFALLS TO DOCUMENT
-# - Configuration patterns
+# - BEST PRACTICES
-# - Test fixtures
+# - PLAYBOOKS TO UPDATE
-# Example patterns to extract:
+# Parse each section
-patterns_found=()
+patterns=$(extract_section "PATTERNS TO SAVE" from agent response)
-
+pitfalls=$(extract_section "PITFALLS TO DOCUMENT" from agent response)
-# State machine pattern
+practices=$(extract_section "BEST PRACTICES" from agent response)
-if echo "$files_changed" | grep -q "state.*machine"; then
+playbooks_to_update=$(extract_section "PLAYBOOKS TO UPDATE" from agent response)
  patterns_found+=("state-machine")
 fi
 # Cron pattern
 if echo "$files_changed" | grep -q "cron"; then
  patterns_found+=("cron-job")
 fi
 # Migration pattern
 if echo "$files_changed" | grep -q "migration"; then
  patterns_found+=("database-migration")
 fi
 echo "🎯 Patterns identified: ${patterns_found[@]}"
 ```
 ### 5. Update or Create Playbooks
-**For each keyword/pattern:**
+**For each playbook the agent identified:**
 ```bash
 playbook_dir="{project-root}/docs/playbooks"
 mkdir -p "$playbook_dir"
-for keyword in $(echo "$all_keywords" | tr ',' ' '); do
+for playbook_update in $playbooks_to_update; do
-  playbook_file="${playbook_dir}/${keyword}-playbook.md"
+  # Parse: "billing-playbook.md: Add idempotency pattern"
  playbook_name=$(echo "$playbook_update" | cut -d: -f1 | tr -d ' ')
  update_description=$(echo "$playbook_update" | cut -d: -f2-)
-  if [ -f "$playbook_file" ]; then
+  playbook_path="${playbook_dir}/${playbook_name}"
-    echo "📖 Updating existing playbook: ${keyword}-playbook.md"
+
-    action="update"
+  if [ ! -f "$playbook_path" ]; then
-  else
+    # Create new playbook from template
-    echo "📝 Creating new playbook: ${keyword}-playbook.md"
+    create_playbook_from_template "$playbook_name" "$story_key"
    action="create"
  fi
-  # Extract learnings specific to this keyword
+  # Append learnings to appropriate sections
-  # Append to playbook
+  update_playbook_section "$playbook_path" "Best Practices" "$practices"
  update_playbook_section "$playbook_path" "Common Pitfalls" "$pitfalls"
  update_playbook_section "$playbook_path" "Code Patterns" "$patterns"
  # Update frontmatter
  update_frontmatter "$playbook_path" "$story_key"
  echo "✅ Updated: $playbook_name"
 done
 ```
-### 6. Extract Specific Learnings
+### 6. Update Playbook Index
-**What to extract:**
+**Regenerate index.md:**
-#### A. Best Practices (from successful implementation)
+```bash
 generate_playbook_index() {
  index_file="${playbook_dir}/index.md"
-```
+  cat > "$index_file" <<EOF
-IF story completed with:
+# Playbook Index
  - All tests passing
  - Code review found zero critical issues
  - Clean implementation (no major refactors needed)
-THEN extract:
+**Last Updated:** $(date +%Y-%m-%d)
-  - Code patterns used
+**Total Playbooks:** $(ls -1 ${playbook_dir}/*-playbook.md 2>/dev/null | wc -l | tr -d ' ')
  - File structure choices
  - Testing approaches
  - Configuration patterns
 ```
-**Example extraction:**
+## Available Playbooks
-```markdown
+EOF
 ## Best Practices
-**Story {story-key} ({story-title}):**
+  # For each playbook, extract summary
-✅ {Successful pattern used}
+  for playbook in ${playbook_dir}/*-playbook.md; do
-✅ {Approach that worked well}
+    if [ ! -f "$playbook" ]; then continue; fi
 ✅ {Quality standard met}
 ✅ {Test coverage achieved}
-**Lesson:** {Key insight from implementation}
+    basename=$(basename "$playbook")
 **Pattern:** See {file-path}:{function-name}()
 ```
-#### B. Common Pitfalls (from mistakes/fixes)
+    # Extract from frontmatter
    topics=$(sed -n '/^---$/,/^---$/p' "$playbook" | grep "^keywords:" | cut -d: -f2- | tr -d '[]')
    stories=$(sed -n '/^---$/,/^---$/p' "$playbook" | grep "^source_stories:" | cut -d: -f2- | tr -d '[]')
    pattern_count=$(sed -n '/^---$/,/^---$/p' "$playbook" | grep "^pattern_count:" | cut -d: -f2 | tr -d ' ')
    last_updated=$(sed -n '/^---$/,/^---$/p' "$playbook" | grep "^last_updated:" | cut -d: -f2 | tr -d ' ')
-```
+    # Append to index
-IF code review found issues, OR
+    cat >> "$index_file" <<ENTRY
   Implementation required fixes, OR
   Tests failed initially
-THEN extract:
+### $basename
-  - What went wrong
+**Topics:** $topics
-  - How it was fixed
+**Stories:** $stories
-  - How to avoid next time
+**Patterns:** $pattern_count patterns documented
-```
+**Last Updated:** $last_updated
 ENTRY
  done
-**Example extraction:**
+  echo "✅ Index updated: $(ls -1 ${playbook_dir}/*-playbook.md 2>/dev/null | wc -l | tr -d ' ') playbooks"
 ```markdown
 ## Common Pitfalls
 ❌ **Story {story-key}: {Mistake description}**
 - Problem: {What went wrong}
 - Error: {Error message if applicable}
 - Root cause: {Why it happened}
 - Fix: {How it was resolved}
 - Prevention: {How to avoid in future}
 ❌ **Story {story-key}: {Another mistake}**
 - Problem: {Issue encountered}
 - Fix: {Solution applied}
 - Prevention: {Best practice going forward}
 ```
 #### C. Code Patterns (reusable snippets)
 ```
 IF implementation created reusable code:
  - Helper functions
  - Type definitions
  - Test utilities
  - Configuration patterns
 THEN extract code snippets with documentation
 ```
 **Example extraction:**
 ```markdown
 ## Code Patterns
 ### Pattern: Idempotency Key Generation
 ```typescript
 // Source: Story 18-1, lib/billing/billing-service.ts
 export function generateIdempotencyKey(
  agreementId: string,
  billingPeriod: string,
  chargeType: ChargeType
 ): string {
  return `charge-${agreementId}-${billingPeriod}-${chargeType}`;
 }
 ```
 **When to use:** Preventing duplicate charge creation
 **Why it works:** Deterministic key based on unique identifiers
 **Tests:** See __tests__/lib/billing/billing-service.test.ts:47
 ```
 ### 7. Commit Playbook Updates
-**If playbooks were created/updated:**
+**Commit all changes:**
 ```bash
-git add docs/playbooks/*.md
+playbooks_updated=$(git diff --name-only docs/playbooks/ | wc -l | tr -d ' ')
-git commit -m "docs: update playbooks from Story ${story_key} learnings
+if [ "$playbooks_updated" -gt 0 ]; then
  git add docs/playbooks/*.md
-Added/updated:
+  git commit -m "docs: update playbooks from Story ${story_key} learnings
 Updated/created:
 $(git diff --cached --name-only docs/playbooks/ | sed 's/^/- /')
 Learnings from successful implementation of ${story_key}."
  echo "✅ Committed: $playbooks_updated playbook updates"
 else
  echo "ℹ️  No playbook changes to commit"
 fi
 ```
 ---
@ -257,150 +279,129 @@ Learnings from successful implementation of ${story_key}."
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ LEARNINGS EXTRACTED
+✅ LEARNINGS EXTRACTED FROM STORY {story_key}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Playbooks Updated: {count}
- prisma-playbook.md (added migration year validation)
+- billing-playbook.md (added idempotency pattern)
- state-machine-playbook.md (added transition validation pattern)
+- state-machine-playbook.md (added entity update reminder)
- billing-playbook.md (added idempotency key pattern)
+- database-migration-playbook.md (added enum pitfall)
-Patterns Extracted: {count}
+Patterns Documented: {count}
 - Idempotency key generation
- State machine validation
+- State transition validation
- Decimal field serialization
+- Related entity updates
-Common Pitfalls Documented: {count}
+Pitfalls Documented: {count}
- Migration year sorting issue
+- Enum transaction limitation (PostgreSQL)
- Enum transaction limitation
+- Forgotten entity updates on state changes
-These learnings will benefit future stories!
+Index Updated: docs/playbooks/index.md
 - Now tracks {total_playbooks} playbooks
 - {total_patterns} patterns documented
 - Ready for next story to benefit
 Future stories about billing, state machines, or migrations will
 automatically load these learnings in Step 1b.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 ---
-## Feedback Loop
+## Helper Functions
-```
+### create_playbook_from_template
 Story N Implementation
  ↓
 Extract Learnings (Step 12)
  ↓
 Update Playbooks
  ↓
 Commit Playbooks
  ↓
 Story N+1 Starts
  ↓
 Load Playbooks (Step 1b) ← Gets Story N's learnings!
  ↓
 Implement with Knowledge
  ↓
 Repeat
 ```
 **Result:** Each story is smarter than the last.
 ---
 ## Skill Integration
 **Use existing /extract-patterns skill:**
 ```bash
-# After implementation completes
+create_playbook_from_template() {
-/extract-patterns story-key={story_key} output-dir=docs/playbooks/
+  playbook_name="$1"
  story_key="$2"
-# This extracts:
+  # Extract technology/domain from filename
-# - Code patterns
+  # Example: billing-playbook.md → technology: billing
-# - Test patterns
+  tech_or_domain=$(echo "$playbook_name" | sed 's/-playbook\.md$//')
 # - Configuration patterns
 # Saves to playbooks directory
 ```
 **Use /get-playbook for on-demand guidance:**
 ```bash
 # During Step 1b if no playbook exists
 /get-playbook topic=prisma-migrations
 # Searches project docs for guidance
 # Creates playbook if patterns found
 ```
 **Use /get-more-context for comprehensive dives:**
 ```bash
 # For complex stories (COMPLEX complexity level)
 /get-more-context topic=stripe-integration
 # Loads comprehensive documentation
 # More detailed than playbook
 # Used for high-stakes implementations
 ```
  cat > "${playbook_dir}/${playbook_name}" <<EOF
 ---
 technology: ${tech_or_domain}
 keywords: [${tech_or_domain}]
 source_stories: [${story_key}]
 last_updated: $(date +%Y-%m-%d)
 pattern_count: 0
 pitfall_count: 0
 practice_count: 0
 ---
-## Configuration
+# ${tech_or_domain^} Playbook
-**In super-dev-pipeline/workflow.yaml:**
+**Created from:** Story ${story_key}
-```yaml
+## Best Practices
 learning_feedback:
  enabled: true  # Enable automatic playbook loading/saving
  playbook_dir: "{project-root}/docs/playbooks"
-  # When to extract learnings
+## Common Pitfalls
  extract_triggers:
    - on_success: true  # Extract after successful completion
    - on_code_review: true  # Extract from review findings
    - on_complex: true  # Always extract from COMPLEX stories
-  # When to load playbooks
+## Code Patterns
-  load_triggers:
+
-    - on_init: true  # Load at Step 1b
+## Lessons Learned
-    - keywords_required: 1  # Minimum keywords to trigger
+EOF
  echo "📝 Created new playbook: $playbook_name"
 }
 ```
---
+### update_playbook_section
-## Step Sequence Update
+```bash
 update_playbook_section() {
  playbook_file="$1"
  section_name="$2"  # "Best Practices", "Common Pitfalls", "Code Patterns"
  new_content="$3"
-**Before (without learning loop):**
+  if [ -z "$new_content" ]; then
-1. Init
+    return 0  # Nothing to add
-2. Gap Analysis
+  fi
 3. Write Tests
 4. Implement
 ...
 11. Summary
-**After (with learning loop):**
+  # Find section in file
-1. Init
+  # Append new content
-**1b. Load Playbooks** ← NEW (loads previous learnings)
+  # Use Edit tool for surgical update
-2. Gap Analysis (informed by playbooks)
+
-3. Write Tests (uses test patterns from playbooks)
+  echo "✏️  Updated section: $section_name in $(basename "$playbook_file")"
-4. Implement (follows playbook best practices)
+}
-...
+```
-11. Summary
+
-**12. Extract Learnings** ← NEW (saves for next story)
+### update_frontmatter
 ```bash
 update_frontmatter() {
  playbook_file="$1"
  story_key="$2"
  # Update source_stories list (append if not already present)
  # Increment pattern_count / pitfall_count / practice_count
  # Update last_updated to today
  # Use Edit tool to update frontmatter
  echo "✏️  Updated frontmatter in $(basename "$playbook_file")"
 }
 ```
 ---
 ## Success Criteria
 **Step 1b succeeds when:**
 - [x] Keywords extracted from story
 - [x] Existing playbooks checked
 - [x] Applicable playbooks loaded (or noted as missing)
 - [x] Context ready for implementation
 **Step 12 succeeds when:**
- [x] Learnings extracted from implementation
+- [x] Agent provided self-reflection
 - [x] Learnings extracted and categorized
 - [x] Playbooks updated or created
- [x] Patterns documented with code examples
+- [x] Index regenerated
- [x] Playbooks committed to git
+- [x] Changes committed to git
 **Step 12 can be skipped when:**
 - Story completion < 80%
 - No commit found
 - Agent reflection yields no learnings
 ---
-**Next:** Continue to Step 2 (Pre-Gap Analysis) with loaded playbook context.
+**Next:** Workflow complete. Story finished with learnings extracted for future benefit.