/self-reflect

description: Extract learnings from recent PR reviews, conversations, and session patterns to update the knowledge base

BEADS Self-Reflect

You are performing a self-reflection for the BEADS agent swarm. Your job is to analyze PR review comments, conversation history, and session patterns to extract high-quality, reusable learnings.

**Philosophy**: Be judicious. Quality over quantity. Each learning should make future development measurably better.

Phase A: PR Comment Analysis

Step 1: Fetch PR Comments

GITHUB_TOKEN=$(gh auth token) npx tsx scripts/beads-fetch-pr-comments.ts --days 7

This outputs PR comments to `.beads/temp/pr-comments.json`.

Step 2: Extract CodeRabbit's Structured Learnings

cat .beads/temp/pr-comments.json | jq -r '.comments[].body' | grep -A5 "^Learnt from:" | grep "^Learning:" | sed 's/^Learning: //' | sort -u

Evaluate Each CodeRabbit Learning

**NOT all CodeRabbit learnings are equal.** Evaluate each one:

ACCEPT (High Value)

• **Applies to patterns**: `Applies to **/*.test.ts: ...` - Actionable file-scoped rules
• **NEVER/ALWAYS rules**: Clear, enforceable constraints
• **Security/Performance**: Critical quality gates
• **Gotchas with context**: Explains WHY something is problematic

REJECT or DEFER (Low Value)

• **PR-specific context**: "In PR #X, someone did Y" - Too specific unless the pattern generalizes
• **Personality observations**: "Developer provides detailed updates" - Not actionable
• **Process descriptions**: Meta, not code
• **Duplicate with slight rewording**: Check if we already have this fact
• **Obvious/trivial**: Things any developer should know

TRANSFORM (Medium Value -> Make High Value)

• **Before**: "In PR #593, developer explains optional AIProvider methods support backward compatibility"
• **After**: "Optional interface methods (generateWithTools?, generateObject?) follow Interface Segregation Principle - add runtime guards before use"

Quality Filter Questions

For each potential learning, ask:

1. **Would this prevent a bug?** If yes, high priority. 2. **Would this save review cycles?** If yes, add it. 3. **Is this codebase-specific or universal?** Tag accordingly. 4. **Do we already have this?** Check for semantic duplicates. 5. **Can an agent act on this?** If not actionable, skip it. 6. **Would this confuse a naive agent?** If a future agent without context wouldn't benefit, skip it.

Phase B: Conversation & Session Mining (Optional)

Analyze current context window and optionally historical sessions for implicit insights:

**Strategic patterns to look for:**

| Pattern | Usually indicates | Value | | ----------------------------- | -------------------------- | --------- | | "The problem was..." | Debugging insight | High | | "It turns out..." | Discovery moment | High | | "We decided to..." | Architectural decision | Very High | | "The reason we..." | Rationale worth preserving | Very High | | "Unlike what you'd expect..." | Non-obvious behavior | High | | "Never do X because..." | Gotcha/pitfall | High |

**Filter**: Only capture insights that are codebase-specific, non-obvious, actionable, and durable.

Phase C: Config Reflection (Optional)

Review Claude instructions and config for improvement opportunities:

• `.claude/commands/*` - Are commands still accurate?
• `CLAUDE.md` - Any outdated guidance?
• `.claude/settings.json` - Missing permissions or tools?

Present findings interactively: explain issue -> propose change -> get feedback -> implement.

Step 3: Analyze Comment Patterns

Beyond CodeRabbit's structured learnings, look for **recurring patterns** in review comments:

cat .beads/temp/pr-comments.json | jq -r '.comments[] | select(.reviewerType == "coderabbit") | .body' | grep -i "nitpick\|issue\|suggestion\|consider\|should\|must\|avoid" | head -50

Pattern Detection Checklist

Look for these patterns across multiple PRs:

1. **Repeated corrections**: Same issue flagged in multiple PRs -> Create a learning 2. **Architectural feedback**: Comments about service design, dependencies -> Capture the principle 3. **Testing feedback**: Mock patterns, test structure issues -> Document the pattern 4. **Type safety issues**: Repeated type casting problems -> Create a gotcha 5. **Performance concerns**: N+1 queries, memory issues -> Document with context

Step 4: Present Candidates for Approval

Present learnings as a numbered list for user selection:

## Candidate Learnings

1. **<Brief title>** - <One sentence description>

2. **<Brief title>** - <One sentence description>

3. **<Brief title>** - <One sentence description>

---

Which numbers do you want to capture? (all / 1,2,3 / none)

**After user selects**, classify each approved learning interactively:

**Fact**: [extracted core insight]
**Type**: [pattern|gotcha|decision|api_behavior|security|performance]
**Applies to**: [file patterns or components]
**Confidence**: [high|medium|low]

Does this look right? (yes / edit)

Conflict Resolution

When a new learning conflicts with an existing one:

| Situation | Action | | -------------------------------------- | ------------------------------------- | | New learning is more specific/accurate | New supersedes old | | Both capture different valid aspects | Keep both, add distinguishing context | | New learning contradicts old | Ask user which is correct | | Old learning is a subset of new | Merge into comprehensive learning |

**The key question**: Would having both learnings confuse a naive agent, or complement each other?

Step 5: Categorize and Store

For each validated learning, add it to the appropriate knowledge base JSONL file followin