From 645c8b4822c74f6c991b76aa035086a1a4c1fc71 Mon Sep 17 00:00:00 2001
From: Jonah Schulte <jonah@jonahschulte.com>
Date: Mon, 26 Jan 2026 10:16:42 -0500
Subject: [PATCH] fix: use agent reasoning for playbook selection (not keyword
 matching)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**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'.
---
 .../steps/step-01b-load-playbooks.md          | 534 +++++++++-------
 .../steps/step-12-extract-learnings.md        | 581 +++++++++---------
 2 files changed, 587 insertions(+), 528 deletions(-)

diff --git 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
index 707df6ae..a17bc441 100644
--- 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
 
----
-
-## Execution
-
-### 1. Analyze Story for Keywords
-
-**Extract topics from story:**
+**Load the playbook manifest:**
 
 ```bash
-story_file="{story_file}"
+playbook_index="{project-root}/docs/playbooks/index.md"
 
-# Extract keywords from:
-# - Story title
-# - Task descriptions
-# - 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
+if [ ! -f "$playbook_index" ]; then
+  echo "📚 No playbook index found - skipping (will create after first story)"
+  exit 0
 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)
-
-**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:**
+**Index format:**
 
 ```markdown
-📚 Loaded: {technology}-playbook.md
+# Playbook Index
 
-Best Practices:
-- {Practice learned from previous implementations}
-- {Pattern that worked successfully}
-- {Standard established across stories}
+## Available Playbooks
 
-Common Pitfalls:
-- {Mistake that was made and fixed}
-- {Issue encountered and resolved}
-- {Edge case discovered}
+### billing-playbook.md
+**Topics:** Charge creation, payment processing, idempotency, Stripe integration
+**Stories:** 18-1, 18-3, 19-4
+**Patterns:** 8 code patterns, 5 pitfalls documented
+**Last Updated:** 2026-01-26
 
-Code Patterns:
-- {Reusable pattern with code example}
-- {Configuration approach}
-- {Testing strategy}
+### state-machine-playbook.md
+**Topics:** State transitions, validation rules, invalid state handling
+**Stories:** 18-1, 17-8, 6-1
+**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:**
-
-```
-🔍 No existing playbooks for: {keywords}
-
-Checking for project-level guidance...
-```
-
-**Use /get-playbook to request specific guidance:**
+**Understand what this story is about:**
 
 ```bash
-# For each keyword without playbook
-for keyword in $keywords_without_playbooks; do
-  echo "📖 Requesting playbook: $keyword"
+# Read from story file:
+# - Story description (user story)
+# - Acceptance criteria (what to build)
+# - Tasks section (how to build it)
+# - Technical Requirements (constraints)
 
-  # Invoke /get-playbook with keyword
-  # This searches docs/, pulls from project context, creates on-demand playbook
+story_description=$(sed -n '/^## Story/,/^##/p' "$story_file" | head -20)
+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:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📚 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
+**Concise, actionable format:**
 
 ```markdown
-# {Technology/Domain} Playbook
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📚 APPLICABLE PLAYBOOKS LOADED (2)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Last Updated:** {date}
-**Source Stories:** {story-keys that contributed learnings}
+**1. billing-playbook.md**
 
-## 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}
-2. {Pattern that worked well}
-3. {Standard we always follow}
+⚠️ Pitfalls to Avoid:
+- Don't create duplicate charges (use idempotency key unique constraint)
+- Don't hardcode amounts (pull from agreement.monthlyRent)
 
-## Common Pitfalls
-
-❌ {Mistake that was made}
-✅ {How to avoid it}
-
-❌ {Another mistake}
-✅ {Correct approach}
-
-## Code Patterns
-
-**Pattern: {Name}**
+💡 Recent Pattern (Story 18-1):
 ```typescript
-// Code example from actual implementation
-// Story: {story-key}
+export async function createCharge(input: CreateChargeInput) {
+  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}
-**When NOT to use:** {Anti-pattern}
+**2. state-machine-playbook.md**
 
-## 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}:**
-- Learned: {Insight}
-- Applied: {How we changed approach}
-- Result: {Outcome}
+⚠️ Pitfalls to Avoid:
+- Don't allow arbitrary transitions (use validation map)
+- Don't forget to update related entities (e.g., space status)
 
-## Do's and Don'ts
+💡 Recent Pattern (Story 17-8):
+```typescript
+const STATE_TRANSITIONS = {
+  ACTIVE: ['TERMINATING', 'TERMINATED'],
+  TERMINATING: ['TERMINATED'],
+  // ...
+}
 
-**DO:**
-- {Positive practice}
-- {What works}
+function isValidTransition(from, to) {
+  return STATE_TRANSITIONS[from]?.includes(to) ?? false
+}
+```
 
-**DON'T:**
-- {What to avoid}
-- {Anti-pattern}
-
-## References
-
-- Story implementations: {list of story-keys}
-- Architecture docs: {relevant docs}
-- External resources: {links}
+Apply these learnings to Story {story_key}.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 ---
 
-## Benefits
+## Why This is Better Than Keyword Matching
 
-**Positive Feedback Loop:**
-1. Story 18-1 implements Prisma migration → Learns "use 2026 in names"
-2. Story 18-1 complete → Extracts pattern → Saves to prisma-playbook.md
-3. Story 18-2 starts → Loads prisma-playbook.md → Applies learning
-4. Story 18-2 implements correctly first time (no year mistake)
+**Keyword Matching (Dumb):**
+```
+Story mentions "billing" → Load billing-playbook.md
+Story mentions "payment" → Load payment-playbook.md
+```
+- Doesn't understand context
+- Might load irrelevant playbooks
+- Might miss relevant playbooks (different words, same concept)
 
-**Cumulative Intelligence:**
-- Epic 1: Creates foundational playbooks
-- Epic 2: Builds on Epic 1 playbooks, adds new learnings
-- Epic 18: Has 17 epics worth of learnings available
-- Gets smarter with every story
-
-**Prevents Repeated Mistakes:**
-- Migration year mistakes (happened multiple times)
-- Enum transaction limitations (PostgreSQL gotcha)
-- Story file naming inconsistencies (just experienced!)
-- Missing checkbox updates (just fixed!)
+**Agent Reasoning (Smart):**
+```
+Agent reads: "Create charge model with state machine"
+Agent sees playbooks: billing, state-machine, queue, auth
+Agent decides: "This is about billing + state transitions"
+Agent loads: billing-playbook.md, state-machine-playbook.md
+Agent skips: queue-playbook.md (not relevant), auth-playbook.md (not needed)
+```
+- Understands what the story is actually about
+- Makes intelligent decisions
+- 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 |
-|----------------|---------------------|
-| 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 |
+**After implementation completes, ask agent:**
 
-**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.
diff --git 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
index 47efce8d..15d10a1c 100644
--- 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:
-- Patterns that worked well
-- Mistakes that were made and fixed
-- Code examples worth reusing
-- Best practices discovered
+### 1. Verify Story Quality (Skip if Low Quality)
 
-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:"
-echo "  Story: $story_key"
-echo "  Commit: $commit_hash"
-echo "  Files: $(echo "$files_changed" | wc -l | tr -d ' ')"
-```
-
-### 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"
+# Check for code review
+review_file="{sprint_artifacts}/review-${story_key}.md"
+has_review=false
+critical_issues=0
+high_issues=0
 
 if [ -f "$review_file" ]; then
-  echo "📝 Code review exists - extracting learnings"
-
-  # Extract issues that were fixed
-  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
+  has_review=true
+  critical_issues=$(grep -c "CRITICAL" "$review_file" || echo "0")
+  high_issues=$(grep -c "HIGH" "$review_file" || echo "0")
 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:
-# - Well-structured functions (with JSDoc, error handling, tests)
-# - Reusable utilities
-# - Configuration patterns
-# - Test fixtures
+# Agent response will contain sections:
+# - PATTERNS TO SAVE
+# - PITFALLS TO DOCUMENT
+# - BEST PRACTICES
+# - PLAYBOOKS TO UPDATE
 
-# Example patterns to extract:
-patterns_found=()
-
-# State machine pattern
-if echo "$files_changed" | grep -q "state.*machine"; then
-  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[@]}"
+# Parse each section
+patterns=$(extract_section "PATTERNS TO SAVE" from agent response)
+pitfalls=$(extract_section "PITFALLS TO DOCUMENT" from agent response)
+practices=$(extract_section "BEST PRACTICES" from agent response)
+playbooks_to_update=$(extract_section "PLAYBOOKS TO UPDATE" from agent response)
 ```
 
 ### 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
-  playbook_file="${playbook_dir}/${keyword}-playbook.md"
+for playbook_update in $playbooks_to_update; do
+  # 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
-    echo "📖 Updating existing playbook: ${keyword}-playbook.md"
-    action="update"
-  else
-    echo "📝 Creating new playbook: ${keyword}-playbook.md"
-    action="create"
+  playbook_path="${playbook_dir}/${playbook_name}"
+
+  if [ ! -f "$playbook_path" ]; then
+    # Create new playbook from template
+    create_playbook_from_template "$playbook_name" "$story_key"
   fi
 
-  # Extract learnings specific to this keyword
-  # Append to playbook
+  # Append learnings to appropriate sections
+  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"
 
-```
-IF story completed with:
-  - All tests passing
-  - Code review found zero critical issues
-  - Clean implementation (no major refactors needed)
+  cat > "$index_file" <<EOF
+# Playbook Index
 
-THEN extract:
-  - Code patterns used
-  - File structure choices
-  - Testing approaches
-  - Configuration patterns
-```
+**Last Updated:** $(date +%Y-%m-%d)
+**Total Playbooks:** $(ls -1 ${playbook_dir}/*-playbook.md 2>/dev/null | wc -l | tr -d ' ')
 
-**Example extraction:**
+## Available Playbooks
 
-```markdown
-## Best Practices
+EOF
 
-**Story {story-key} ({story-title}):**
-✅ {Successful pattern used}
-✅ {Approach that worked well}
-✅ {Quality standard met}
-✅ {Test coverage achieved}
+  # For each playbook, extract summary
+  for playbook in ${playbook_dir}/*-playbook.md; do
+    if [ ! -f "$playbook" ]; then continue; fi
 
-**Lesson:** {Key insight from implementation}
-**Pattern:** See {file-path}:{function-name}()
-```
+    basename=$(basename "$playbook")
 
-#### 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 ' ')
 
-```
-IF code review found issues, OR
-   Implementation required fixes, OR
-   Tests failed initially
+    # Append to index
+    cat >> "$index_file" <<ENTRY
 
-THEN extract:
-  - What went wrong
-  - How it was fixed
-  - How to avoid next time
-```
+### $basename
+**Topics:** $topics
+**Stories:** $stories
+**Patterns:** $pattern_count patterns documented
+**Last Updated:** $last_updated
+ENTRY
+  done
 
-**Example extraction:**
-
-```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}`;
+  echo "✅ Index updated: $(ls -1 ${playbook_dir}/*-playbook.md 2>/dev/null | wc -l | tr -d ' ') playbooks"
 }
 ```
 
-**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)
-- state-machine-playbook.md (added transition validation pattern)
-- billing-playbook.md (added idempotency key pattern)
+- billing-playbook.md (added idempotency pattern)
+- state-machine-playbook.md (added entity update reminder)
+- database-migration-playbook.md (added enum pitfall)
 
-Patterns Extracted: {count}
+Patterns Documented: {count}
 - Idempotency key generation
-- State machine validation
-- Decimal field serialization
+- State transition validation
+- Related entity updates
 
-Common Pitfalls Documented: {count}
-- Migration year sorting issue
-- Enum transaction limitation
+Pitfalls Documented: {count}
+- Enum transaction limitation (PostgreSQL)
+- 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
 
-```
-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:**
+### create_playbook_from_template
 
 ```bash
-# After implementation completes
-/extract-patterns story-key={story_key} output-dir=docs/playbooks/
+create_playbook_from_template() {
+  playbook_name="$1"
+  story_key="$2"
 
-# This extracts:
-# - Code patterns
-# - Test patterns
-# - 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
-```
+  # Extract technology/domain from filename
+  # Example: billing-playbook.md → technology: billing
+  tech_or_domain=$(echo "$playbook_name" | sed 's/-playbook\.md$//')
 
+  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
-learning_feedback:
-  enabled: true  # Enable automatic playbook loading/saving
-  playbook_dir: "{project-root}/docs/playbooks"
+## Best Practices
 
-  # When to extract learnings
-  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
+## Common Pitfalls
 
-  # When to load playbooks
-  load_triggers:
-    - on_init: true  # Load at Step 1b
-    - keywords_required: 1  # Minimum keywords to trigger
+## Code Patterns
+
+## Lessons Learned
+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):**
-1. Init
-2. Gap Analysis
-3. Write Tests
-4. Implement
-...
-11. Summary
+  if [ -z "$new_content" ]; then
+    return 0  # Nothing to add
+  fi
 
-**After (with learning loop):**
-1. Init
-**1b. Load Playbooks** ← NEW (loads previous learnings)
-2. Gap Analysis (informed by playbooks)
-3. Write Tests (uses test patterns from playbooks)
-4. Implement (follows playbook best practices)
-...
-11. Summary
-**12. Extract Learnings** ← NEW (saves for next story)
+  # Find section in file
+  # Append new content
+  # Use Edit tool for surgical update
+
+  echo "✏️  Updated section: $section_name in $(basename "$playbook_file")"
+}
+```
+
+### 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] Playbooks committed to git
+- [x] Index regenerated
+- [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.