cognitive-core 0.2.1 → 0.2.2

package/playbooks/compound-engineering/bug-reproduction.json

@@ -0,0 +1,62 @@
+{
+  "name": "bug-reproduction",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "moderate",
+  "estimatedEffort": 5,
+  "applicability": {
+    "situations": [
+      "Investigating a reported bug to find root cause and reproduction steps",
+      "Debugging issues with unclear or incomplete reproduction information",
+      "Systematically narrowing down failure conditions through hypothesis-driven investigation"
+    ],
+    "triggers": [
+      "reproduce bug",
+      "investigate issue",
+      "debug",
+      "root cause",
+      "bug report"
+    ],
+    "antiPatterns": [
+      "Starting investigation without forming hypotheses first",
+      "Trying all possible paths without ranking by likelihood",
+      "Making code changes before confirming root cause"
+    ],
+    "domains": ["debugging", "investigation", "software-engineering"]
+  },
+  "guidance": {
+    "strategy": "Hypothesis-driven investigation: understand the report, form ranked hypotheses, reproduce via the most efficient route (test, browser, or manual), trace the code path, and document everything before proposing a fix.",
+    "tactics": [
+      "Phase 1 — Understand: extract reported symptoms, expected behavior, reproduction steps, environment clues, and frequency from the issue/report",
+      "Phase 2 — Hypothesize: search for relevant code (error messages, feature names, route paths, model/service names), form 2-3 hypotheses about what might be wrong and where in the codebase, rank by likelihood",
+      "Phase 3 — Reproduce: choose the most efficient route: (A) test-based — find existing tests, run them, write a failing test if needed; (B) browser-based — follow reported steps in the UI; (C) manual — document conditions and guide through steps. Prefer test-based for fastest feedback",
+      "Phase 4 — Investigate: check logs, error tracking, database state, request/response cycle; trace the code path from entry point; check recent changes with git log on affected files",
+      "Phase 5 — Document: record root cause (file:line), confirmed reproduction steps, evidence collected, suggested fix approach, and open questions. Present findings before taking action",
+      "Always confirm root cause before proposing or implementing a fix",
+      "Use native search tools (not shell pipes) for code exploration"
+    ],
+    "steps": [
+      "1. Read the bug report — extract symptoms, expected behavior, steps, environment, frequency",
+      "2. Search codebase for relevant code paths (error messages, feature names, routes)",
+      "3. Form 2-3 hypotheses, ranked by likelihood",
+      "4. Attempt reproduction via most efficient route (test > browser > manual)",
+      "5. Trace code path from entry point, check logs and recent git changes",
+      "6. Document: root cause, reproduction steps, evidence, suggested fix, open questions",
+      "7. Present findings before taking any action"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Root cause identified with specific file and line reference",
+      "Reproduction is confirmed and steps are documented",
+      "Hypotheses were formed before investigation, not after",
+      "Findings documented before proposing a fix"
+    ],
+    "failureIndicators": [
+      "Investigation started without structured hypotheses",
+      "Code changes proposed before root cause confirmed",
+      "Reproduction steps are vague or unconfirmed",
+      "Only one hypothesis considered without exploring alternatives"
+    ]
+  }
+}

package/playbooks/compound-engineering/confidence-calibration.json

@@ -0,0 +1,49 @@
+{
+  "name": "confidence-calibration",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.9,
+  "complexity": "simple",
+  "estimatedEffort": 1,
+  "applicability": {
+    "situations": [
+      "Any task producing findings, recommendations, or assessments that need confidence scoring",
+      "Code review findings that could be false positives",
+      "Analysis results where certainty varies across findings"
+    ],
+    "triggers": [
+      "confidence score",
+      "how sure",
+      "false positive",
+      "suppress low confidence"
+    ],
+    "antiPatterns": [
+      "Binary pass/fail assessments where confidence doesn't apply",
+      "Objective facts that are either true or false (syntax errors, type mismatches)"
+    ],
+    "domains": ["quality-assurance", "code-review", "analysis"]
+  },
+  "guidance": {
+    "strategy": "Apply a three-tier confidence model to all findings. Suppress anything below 0.60 to prevent noise. Be transparent about what tier each finding falls into.",
+    "tactics": [
+      "HIGH confidence (0.80+): Finding is provable from available evidence alone; full execution/reasoning path is visible; no external context needed to confirm",
+      "MODERATE confidence (0.60-0.79): Finding likely but depends on conditions not directly visible; needs context from calling code, runtime state, or configuration to fully confirm",
+      "LOW confidence (below 0.60): Finding requires runtime observation, specific input shapes, or environmental conditions to confirm — SUPPRESS these findings entirely",
+      "When in doubt about tier, choose the lower one — false negatives (missing a real issue) are less damaging than false positives (noise that erodes trust)",
+      "Report suppressed count so reviewers know what was filtered and can request expansion if needed",
+      "Severity and confidence are independent axes: a P0 at 0.55 confidence should still be suppressed"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "All findings include explicit confidence scores",
+      "No findings below 0.60 confidence in final output",
+      "Suppressed count reported for transparency",
+      "High-confidence findings are all provable without runtime context"
+    ],
+    "failureIndicators": [
+      "Findings with 'might', 'could', 'possibly' language but no confidence score",
+      "Low-confidence findings not suppressed, adding noise",
+      "Confidence score inflated to avoid suppression"
+    ]
+  }
+}

package/playbooks/compound-engineering/correctness-review.json

@@ -0,0 +1,49 @@
+{
+  "name": "correctness-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 3,
+  "applicability": {
+    "situations": [
+      "Reviewing code changes for logical correctness",
+      "Hunting for runtime bugs before they reach production",
+      "Verifying behavioral correctness of new or changed code paths"
+    ],
+    "triggers": [
+      "code review",
+      "logic error",
+      "bug hunt",
+      "correctness check"
+    ],
+    "antiPatterns": [
+      "Style or formatting reviews — use maintainability review instead",
+      "Test coverage analysis — use testing review instead",
+      "Performance optimization — use performance review instead"
+    ],
+    "domains": ["code-review", "debugging", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Mentally execute code with concrete values. Trace inputs through every branch. Ask 'what happens when X is null/empty/zero/negative/concurrent'. Focus exclusively on behavioral correctness, not style.",
+    "tactics": [
+      "Hunt for: off-by-one errors, null/undefined propagation, race conditions, ordering assumptions, incorrect state transitions, broken error propagation, TOCTOU gaps",
+      "Mental execution discipline: follow state changes step by step, check loop bounds with boundary values (0, 1, N-1, N, N+1), trace async completion ordering",
+      "For each finding, trace the full execution path from input to bug — it must be reproducible from code alone",
+      "Confidence calibration: HIGH (0.80+) when full execution path is visible and bug is reproducible from code alone; MODERATE (0.60-0.79) when bug depends on conditions in calling code not visible in diff; suppress below 0.60",
+      "Never flag defensive coding that isn't needed — only flag actual bugs with concrete trigger conditions",
+      "Focus on semantic issues that linters cannot catch"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Finding traces specific input through specific branch to specific wrong output",
+      "Bug is reproducible by reading the code alone without runtime context",
+      "No false positives from style, naming, or lint-catchable issues"
+    ],
+    "failureIndicators": [
+      "Finding requires runtime conditions or specific input shapes that aren't provable from code",
+      "Finding is actually a style preference disguised as a correctness issue",
+      "Confidence is below 0.60 but finding was not suppressed"
+    ]
+  }
+}

package/playbooks/compound-engineering/data-migration-safety.json

@@ -0,0 +1,59 @@
+{
+  "name": "data-migration-safety",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "complex",
+  "estimatedEffort": 6,
+  "applicability": {
+    "situations": [
+      "Reviewing database migrations, schema changes, or data backfills",
+      "Validating data transformation correctness against production data",
+      "Ensuring rollback safety and referential integrity during migrations"
+    ],
+    "triggers": [
+      "migration",
+      "schema change",
+      "backfill",
+      "column drop",
+      "data transform",
+      "ALTER TABLE"
+    ],
+    "antiPatterns": [
+      "Adding nullable columns (safe by definition)",
+      "Adding indexes on small or low-traffic tables",
+      "Test database changes (fixtures, test setup, seed files)",
+      "Purely additive schema changes (new tables, new columns with defaults)"
+    ],
+    "domains": ["code-review", "database", "data-safety", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Verify mappings against production data, never fixtures. The single most common migration bug is swapped/inverted ID mappings. Every migration needs a rollback plan and post-deploy verification SQL queries.",
+    "tactics": [
+      "Swapped mappings (THE most common bug): verify CASE/IF branches map IDs correctly — check that '1 => TypeA, 2 => TypeB' in code matches production, not the reverse. Flag hard-coded mapping constants without verification against live data",
+      "Irreversible migrations: flag column drops, type changes losing precision (float→integer), string length reductions (text→varchar(255)), constraint additions that may violate existing data — require explicit rollback plan or acknowledgment",
+      "Missing backfill: flag NOT NULL columns added without defaults or backfill plan; flag renamed columns still referenced by old code, serializers, API responses, or background jobs",
+      "Deploy-window safety: detect schema changes that break running code during deployment (column removed before code deployed, constraint added while violating rows exist)",
+      "Transaction boundaries: flag multi-table updates without transaction wrapping; verify atomic operations on related tables",
+      "Index locking: flag index creation on large frequently-written tables without concurrent/online option",
+      "Referential integrity: check for orphaned references after column/table drops; verify cascade behavior; flag polymorphic associations lacking integrity checks",
+      "Dual-write validation: during transition periods verify both old and new columns are written for all code paths (not just new records)",
+      "Privacy/compliance: identify PII in new columns, verify encryption for sensitive fields, check GDPR retention policies",
+      "Post-deploy verification: require concrete SQL queries to verify data invariants remain true after migration",
+      "Confidence calibration: HIGH (0.80+) when migration DDL is directly in diff; MODERATE (0.60-0.79) when inferring data impact from application code; suppress below 0.60"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Mapping correctness verified against production data, not fixtures",
+      "Rollback plan exists for every destructive operation",
+      "Post-deploy verification SQL queries are concrete and runnable",
+      "Transaction boundaries cover all multi-step transforms"
+    ],
+    "failureIndicators": [
+      "Mappings trusted from fixtures or hardcoded constants without production verification",
+      "Irreversible migration without explicit acknowledgment or rollback plan",
+      "Missing post-deploy verification queries",
+      "Index creation on hot table without concurrent option"
+    ]
+  }
+}

package/playbooks/compound-engineering/deployment-verification.json

@@ -0,0 +1,63 @@
+{
+  "name": "deployment-verification",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "moderate",
+  "estimatedEffort": 4,
+  "applicability": {
+    "situations": [
+      "Preparing Go/No-Go checklists for risky deployments",
+      "Creating pre-deploy and post-deploy verification SQL queries",
+      "Planning rollback procedures and monitoring for data-affecting changes"
+    ],
+    "triggers": [
+      "deployment checklist",
+      "go/no-go",
+      "deploy verification",
+      "pre-deploy",
+      "post-deploy monitoring"
+    ],
+    "antiPatterns": [
+      "Routine deployments with no data or schema changes",
+      "Feature flag rollouts that are trivially reversible",
+      "Documentation-only or test-only changes"
+    ],
+    "domains": ["deployment", "operations", "data-safety"]
+  },
+  "guidance": {
+    "strategy": "Transform abstract 'be careful with data' into executable checklists with concrete SQL verification queries, rollback procedures, and monitoring plans. Every risky deployment gets a Go/No-Go checklist.",
+    "tactics": [
+      "Define data invariants: document specific properties that must remain true (e.g., 'every order has exactly one payment record', 'no user has null email')",
+      "Pre-deploy baseline: write read-only SQL queries that capture current state of invariants — save results for post-deploy comparison",
+      "Destructive steps: document each step with runtime estimate, batching requirements (batch size, sleep between batches), and explicit rollback procedure",
+      "Index locking: assess lock time for index creation on large tables; use concurrent/online options where available",
+      "Post-deploy verification: SQL queries to run within 5 minutes of deployment confirming invariants still hold and new data is correct",
+      "Rollback plan: for each migration step, document whether rollback is full/partial/impossible with explicit steps (not vague 'restore from backup')",
+      "Post-deploy monitoring (24 hours): define specific metrics to watch, dashboard links, healthy signal baselines, alert thresholds, and failure triggers",
+      "Console verification: include spot-check commands (Rails console, SQL queries) for manual verification"
+    ],
+    "steps": [
+      "1. Identify data invariants that must remain true",
+      "2. Write pre-deploy baseline SQL queries (read-only)",
+      "3. Document each destructive step with runtime estimate and batching",
+      "4. Write rollback procedure for each step (full/partial/impossible)",
+      "5. Write post-deploy verification SQL queries (run within 5 minutes)",
+      "6. Define monitoring plan: metrics, dashboards, thresholds, failure triggers (24 hours)",
+      "7. Compile Go/No-Go checklist for deployment day"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Data invariants explicitly documented with SQL verification queries",
+      "Pre-deploy baselines captured for post-deploy comparison",
+      "Rollback procedures are concrete and tested, not vague",
+      "Monitoring plan has specific metrics, thresholds, and 24-hour window"
+    ],
+    "failureIndicators": [
+      "No data invariants defined — deploying blind",
+      "Rollback plan says 'restore from backup' without concrete steps",
+      "Post-deploy verification missing or scheduled for 'later'",
+      "Monitoring plan lacks specific alert thresholds"
+    ]
+  }
+}

package/playbooks/compound-engineering/error-recovery-patterns.json

@@ -0,0 +1,53 @@
+{
+  "name": "error-recovery-patterns",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.75,
+  "complexity": "moderate",
+  "estimatedEffort": 3,
+  "applicability": {
+    "situations": [
+      "Diagnosing and recovering from common error categories in agent task execution",
+      "Applying structured error classification to choose the right recovery strategy",
+      "Learning from failure→recovery trajectories to build causal knowledge"
+    ],
+    "triggers": [
+      "error recovery",
+      "task failure",
+      "retry strategy",
+      "error classification",
+      "recovery pattern"
+    ],
+    "antiPatterns": [
+      "Retrying the identical action without diagnosing the root cause",
+      "Classifying errors locally instead of using the shared error classifier",
+      "Ignoring the causal store when a similar failure→recovery pattern already exists"
+    ],
+    "domains": ["debugging", "error-handling", "agent-execution"]
+  },
+  "guidance": {
+    "strategy": "Classify the error using the canonical error taxonomy, check the causal store for known recovery patterns, then apply the appropriate recovery strategy. Every failure→recovery pair becomes a causal edge for future learning.",
+    "tactics": [
+      "Error classification: use the canonical types — syntax-error, type-error, runtime-error, logic-error, environment-error, dependency-error, configuration-error, timeout-error, permission-error, resource-error, unknown-error",
+      "Before retrying: check the causal store for existing failure→recovery edges matching this error type and context; reuse known recovery patterns rather than rediscovering them",
+      "Recovery strategies by class: syntax/type errors → fix the specific code; runtime/logic errors → trace the execution path, add assertions; environment/dependency/config errors → verify setup before retrying; timeout/resource errors → adjust limits or batch size; permission errors → check and request access",
+      "Avoid repeated actions: if the same action has been tried 3+ times without progress, escalate to a different strategy rather than retrying",
+      "Extract tool names and action patterns from the trajectory to detect loops early",
+      "After successful recovery: record the failure→recovery pair as a causal edge so future encounters can shortcut to the solution",
+      "Reflexion: generate a reflexion episode capturing what went wrong, what the recovery was, and what to do differently next time"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Error classified using canonical taxonomy, not ad-hoc categories",
+      "Causal store checked before attempting recovery",
+      "Recovery strategy matches the error class",
+      "Failure→recovery pair recorded as causal edge after successful resolution"
+    ],
+    "failureIndicators": [
+      "Same action retried 3+ times without changing strategy",
+      "Error classified with local ad-hoc logic instead of shared classifier",
+      "Known recovery pattern in causal store was ignored",
+      "Successful recovery not recorded — knowledge lost"
+    ]
+  }
+}

package/playbooks/compound-engineering/implementation-planning.json

@@ -0,0 +1,64 @@
+{
+  "name": "implementation-planning",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "complex",
+  "estimatedEffort": 8,
+  "applicability": {
+    "situations": [
+      "Creating a structured implementation plan from requirements",
+      "Technical planning before code execution",
+      "Establishing architecture, patterns, and test strategy before work starts"
+    ],
+    "triggers": [
+      "create plan",
+      "implementation plan",
+      "plan this feature",
+      "how to implement",
+      "technical plan"
+    ],
+    "antiPatterns": [
+      "Requirements are unclear — brainstorm first",
+      "Trivial change that doesn't need a plan (single file, obvious fix)",
+      "Runtime discovery needed — some things must be learned by doing, not planned"
+    ],
+    "domains": ["planning", "architecture", "software-engineering"]
+  },
+  "guidance": {
+    "strategy": "Research-then-structure: parallel research (repo patterns + institutional knowledge + external best practices) before structuring the plan. Plans are decision artifacts, not instruction scripts — they document what and why, not line-by-line how.",
+    "tactics": [
+      "Research phase: run repo-research (patterns, conventions, existing code) and learnings-research (past solutions, known gotchas) in parallel; conditionally add external research for security, payments, APIs, migrations, compliance",
+      "Requirements traceability: carry forward all decisions from requirements; preserve blocked vs deferred questions",
+      "Decompose into implementation units: logical clusters (not micro-steps); each unit has Goal, Patterns to follow, Approach, Files, Test scenarios, Verification, Dependencies",
+      "Test scenario specificity: name exact inputs and expected outcomes, not generic 'validates correctly'",
+      "Execution posture signals: annotate units with test-first, characterization-first, or external-delegate when signals are clear",
+      "Reference actual files in the repo for patterns to follow — don't invent from scratch",
+      "Depth classification: lightweight (brief, <1hr), standard (structured, 1-3hrs), deep (full research + options analysis, 3hrs+)",
+      "Plans must contain decisions with rationale, not just task lists"
+    ],
+    "steps": [
+      "1. Assess scope and depth classification (lightweight/standard/deep)",
+      "2. Research: repo patterns + institutional knowledge + external guidance (in parallel)",
+      "3. Resolve planning questions — separate 'resolve now' from 'deferred to implementation'",
+      "4. Structure plan into implementation units with dependencies",
+      "5. Deep-dive each unit: concrete file paths, test file paths, exact test scenarios",
+      "6. Confidence check: verify sequencing, risk mitigation, unknown handling",
+      "7. Finalize with explicit ordering and execution posture signals"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "All requirements traced to implementation units",
+      "Each unit has concrete file paths and exact test scenarios (not generic)",
+      "Decisions documented with rationale",
+      "Dependencies explicitly ordered",
+      "Pattern references point to actual files in the repo"
+    ],
+    "failureIndicators": [
+      "Plan contains pre-written implementation code (should be decisions, not code)",
+      "Test scenarios say 'validates correctly' without naming inputs and expected outputs",
+      "Pattern references are invented, not sourced from existing codebase",
+      "Requirements not traceable to implementation units"
+    ]
+  }
+}

package/playbooks/compound-engineering/issue-pattern-analysis.json

@@ -0,0 +1,53 @@
+{
+  "name": "issue-pattern-analysis",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "moderate",
+  "estimatedEffort": 4,
+  "applicability": {
+    "situations": [
+      "Analyzing GitHub issues to identify systemic themes rather than individual bugs",
+      "Understanding user pain patterns for planning and prioritization",
+      "Detecting recurring problems that indicate architectural weaknesses"
+    ],
+    "triggers": [
+      "issue analysis",
+      "bug patterns",
+      "systemic issues",
+      "issue themes",
+      "user pain"
+    ],
+    "antiPatterns": [
+      "Analyzing issues one by one instead of clustering into themes",
+      "Creating themes from closed-only issues with zero open support",
+      "Over-granular clustering (more than 8 themes obscures signal)"
+    ],
+    "domains": ["planning", "analysis", "project-management"]
+  },
+  "guidance": {
+    "strategy": "Cluster issues by root cause or system area, not by symptom. Distinguish open from recently-closed issues to detect recurrence. Produce 3-8 themes with quantified impact and trend direction.",
+    "tactics": [
+      "Token-efficient fetching: scan labels first, fetch high-priority issues, backfill remaining, fetch recently closed (last 30 days) for recurrence signal, deduplicate",
+      "Cluster by theme: group by root cause or system area, not surface symptom; use labels as hints but don't over-rely; separate bugs from enhancements",
+      "Recurrence detection: check recently closed issues for themes that keep coming back — recurrence is a stronger signal than open count alone",
+      "Theme structure: for each theme provide title, description, why it matters, issue count, source mix (open vs closed), trend direction (growing/stable/declining), representative issues, and confidence",
+      "Target 3-8 themes: fewer than 3 means clustering is too coarse; more than 8 means too granular for strategic signal",
+      "Data integrity: never fabricate statistics not computed from actual data; all counts and trends must be derivable from the issues analyzed",
+      "Do not let closed-only issues create new themes — they must have open issue support"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "3-8 themes identified with quantified impact",
+      "Themes clustered by root cause, not symptom",
+      "Recurrence patterns detected from recently-closed issues",
+      "All statistics derivable from actual issue data"
+    ],
+    "failureIndicators": [
+      "Issues listed individually instead of clustered into themes",
+      "Themes based on closed-only issues with no open support",
+      "More than 8 themes (too granular for strategic planning)",
+      "Fabricated or estimated statistics not computed from data"
+    ]
+  }
+}

package/playbooks/compound-engineering/knowledge-compounding.json

@@ -0,0 +1,63 @@
+{
+  "name": "knowledge-compounding",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "moderate",
+  "estimatedEffort": 5,
+  "applicability": {
+    "situations": [
+      "Documenting a solved problem while context is fresh",
+      "Extracting reusable knowledge from debugging sessions",
+      "Preventing repeated mistakes by compounding institutional knowledge"
+    ],
+    "triggers": [
+      "problem solved",
+      "that worked",
+      "it's fixed",
+      "document solution",
+      "compound knowledge"
+    ],
+    "antiPatterns": [
+      "Problem is not fully solved and verified — don't document partial solutions",
+      "Trivial fix that doesn't generalize (typo, missing import)",
+      "Solution is identical to an existing documented solution"
+    ],
+    "domains": ["knowledge-management", "documentation", "learning"]
+  },
+  "guidance": {
+    "strategy": "Use parallel extraction agents (Context Analyzer + Solution Extractor) to capture the problem and solution, then check for overlap with existing knowledge before writing. Update existing docs when overlap is high rather than creating duplicates.",
+    "tactics": [
+      "Phase 0.5: Scan existing knowledge for related entries using grep-first filtering on frontmatter fields (title, tags, module, component)",
+      "Phase 1: Run Context Analyzer (extract problem, symptoms, category, affected files) and Solution Extractor (root cause, solution steps, prevention rules, test cases) in parallel — they return text only, no file writes",
+      "Phase 2: Assess overlap with existing docs on 5 dimensions: problem statement, root cause, solution approach, referenced files, prevention rules",
+      "High overlap (4-5 dimensions match): update existing document instead of creating new one",
+      "Moderate overlap (2-3 dimensions): create new document but flag for later consolidation",
+      "Low/no overlap: create new document",
+      "Single file write guarantee: only the orchestrator writes output, subagents return text",
+      "Include all required sections: Problem, Symptoms, What Didn't Work, Solution, Why This Works, Prevention (with code examples)"
+    ],
+    "steps": [
+      "1. Grep existing knowledge for related entries by keywords, tags, and module",
+      "2. Extract context (problem, symptoms, category) and solution (root cause, fix, prevention) in parallel",
+      "3. Score overlap with found entries on 5 dimensions",
+      "4. If high overlap, update existing entry with new information",
+      "5. If low overlap, create new entry with YAML frontmatter (category, problem_type, tags, severity, module)",
+      "6. Add cross-links to related entries"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Knowledge entry created/updated with valid frontmatter",
+      "All required sections present with specific details (not generic text)",
+      "Overlap assessment performed — no unnecessary duplicates",
+      "Prevention section includes concrete, actionable rules",
+      "Cross-links connect to related existing entries"
+    ],
+    "failureIndicators": [
+      "Duplicate of existing entry created without overlap check",
+      "Solution section is vague or lacks root cause explanation",
+      "Missing prevention rules — knowledge won't prevent future recurrence",
+      "Problem wasn't actually solved before documenting"
+    ]
+  }
+}

package/playbooks/compound-engineering/learnings-research.json

@@ -0,0 +1,54 @@
+{
+  "name": "learnings-research",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 3,
+  "applicability": {
+    "situations": [
+      "Looking up institutional knowledge before starting work",
+      "Finding past solutions for similar problems during debugging",
+      "Preventing repeated mistakes by surfacing known patterns and gotchas"
+    ],
+    "triggers": [
+      "search knowledge",
+      "past solutions",
+      "known issues",
+      "institutional knowledge",
+      "what do we know about"
+    ],
+    "antiPatterns": [
+      "Searching for information that doesn't exist in the knowledge base yet",
+      "Using full-text search as the first step instead of grep-first filtering",
+      "Reading all files sequentially instead of parallel keyword search"
+    ],
+    "domains": ["knowledge-management", "research", "debugging"]
+  },
+  "guidance": {
+    "strategy": "Grep-first filtering: extract keywords, narrow by category, run parallel content searches on frontmatter fields, then read only strong/moderate matches. Never read all files — always pre-filter.",
+    "tactics": [
+      "Extract keywords from the current task/problem description",
+      "Category narrowing (if clear): focus on the relevant knowledge subdirectory first",
+      "Parallel content-search: search on frontmatter fields (title, tags, module, component) using multiple keywords in parallel; use case-insensitive matching; use OR for synonyms",
+      "Score matches into four categories: Strong (module + tags match), Moderate (problem_type relevant + tags), Weak (tangential), None — only read Strong and Moderate",
+      "Always check critical-patterns document regardless of grep results — it contains must-know patterns for all work",
+      "Distill summaries from matched documents — surface actionable insights, not raw content",
+      "Assess overlap on 5 dimensions: problem statement, root cause, solution, referenced files, prevention rules",
+      "Run multiple searches in parallel — never sequentially"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Relevant documents found and ranked by relevance strength",
+      "Critical patterns checked and incorporated",
+      "Summaries are distilled and actionable (not raw file dumps)",
+      "Search used grep-first filtering, not sequential file reading"
+    ],
+    "failureIndicators": [
+      "All files read sequentially instead of pre-filtered",
+      "Tangentially related entries included, adding noise",
+      "Critical patterns document skipped",
+      "Searches run sequentially instead of in parallel"
+    ]
+  }
+}

package/playbooks/compound-engineering/maintainability-review.json

@@ -0,0 +1,49 @@
+{
+  "name": "maintainability-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 3,
+  "applicability": {
+    "situations": [
+      "Reviewing code for long-term carrying cost and maintainability",
+      "Evaluating abstractions, indirection, and naming clarity",
+      "Checking for dead code, unnecessary coupling, and premature complexity"
+    ],
+    "triggers": [
+      "code review",
+      "maintainability",
+      "complexity",
+      "refactoring"
+    ],
+    "antiPatterns": [
+      "Reviewing for correctness bugs — use correctness review instead",
+      "Style preferences that don't affect comprehension",
+      "Debating naming conventions already established in the codebase"
+    ],
+    "domains": ["code-review", "maintainability", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Apply the future developer lens: will the next person who touches this in 6 months understand it quickly? Every abstraction must earn its keep with 3+ implementations or proven variation.",
+    "tactics": [
+      "Hunt for: premature abstraction (interface/factory with one user), unnecessary indirection (>2 delegation levels), dead code (commented, unused exports, unreachable), unrelated module coupling, naming that obscures intent",
+      "Anti-pattern catalog: generic solution for specific problem, wrapper with no added value, config for unchanging values, unused extension points, circular dependencies, shared mutable state",
+      "Abstractions must earn their keep: 3+ implementations or proven variation axis — otherwise inline",
+      "Indirection must add clear value: if a function just delegates to another without transformation, it's overhead",
+      "Naming describes what, not how: booleans have is/has/should prefixes; functions describe outcome not mechanism",
+      "Confidence calibration: HIGH (0.80+) when objectively provable (abstraction has 1 user visible in codebase); MODERATE (0.60-0.79) for naming/abstraction boundary judgments; suppress below 0.60 for style preferences"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "All flagged abstractions are objectively underused (provable from codebase search)",
+      "Indirection findings show concrete delegation chain with no value-add",
+      "Dead code findings are verifiable via search (no callers/importers)"
+    ],
+    "failureIndicators": [
+      "Finding is really a style preference, not a maintainability concern",
+      "Abstraction flagged as premature but actually has 3+ users",
+      "Naming critique is subjective rather than clarity-impacting"
+    ]
+  }
+}