@dzhechkov/keysarium 1.3.0 → 1.5.0

package/templates/.claude/skills/feature-adr/references/agentic-qe/tdd-london-chicago.md

@@ -0,0 +1,249 @@
+---
+name: tdd-london-chicago
+description: "Apply London (mock-based) and Chicago (state-based) TDD schools. Use when practicing test-driven development or choosing testing style for your context."
+category: development-practices
+priority: high
+tokenEstimate: 1100
+agents: [qe-test-generator, qe-test-implementer, qe-test-refactorer]
+implementation_status: optimized
+optimization_version: 1.0
+last_optimized: 2025-12-02
+dependencies: []
+quick_reference_card: true
+tags: [tdd, testing, london-school, chicago-school, red-green-refactor, mocks]
+trust_tier: 2
+validation:
+  schema_path: schemas/output.json
+  validator_path: scripts/validate-config.json
+
+---
+
+# Test-Driven Development: London & Chicago Schools
+
+<default_to_action>
+When implementing TDD or choosing testing style:
+1. IDENTIFY code type: domain logic → Chicago, external deps → London
+2. WRITE failing test first (Red phase)
+3. IMPLEMENT minimal code to pass (Green phase)
+4. REFACTOR while keeping tests green (Refactor phase)
+5. REPEAT cycle for next functionality
+
+**Quick Style Selection:**
+- Pure functions/calculations → Chicago (real objects, state verification)
+- Controllers/services with deps → London (mocks, interaction verification)
+- Value objects → Chicago (test final state)
+- API integrations → London (mock external services)
+- Mix both in practice (London for controllers, Chicago for domain)
+
+**Critical Success Factors:**
+- Tests drive design, not just verify it
+- Make tests fail first to ensure they test something
+- Write minimal code - no features beyond what's tested
+</default_to_action>
+
+## Quick Reference Card
+
+### When to Use
+- Starting new feature with test-first approach
+- Refactoring legacy code with test coverage
+- Teaching TDD practices to team
+- Choosing between mocking vs real objects
+
+### TDD Cycle
+| Phase | Action | Discipline |
+|-------|--------|------------|
+| **Red** | Write failing test | Verify it fails, check message is clear |
+| **Green** | Minimal code to pass | No extra features, don't refactor |
+| **Refactor** | Improve structure | Keep tests passing, no new functionality |
+
+### School Comparison
+| Aspect | Chicago (Classicist) | London (Mockist) |
+|--------|---------------------|------------------|
+| Collaborators | Real objects | Mocks/stubs |
+| Verification | State (assert outcomes) | Interaction (assert calls) |
+| Isolation | Lower (integrated) | Higher (unit only) |
+| Refactoring | Easier | Harder (mocks break) |
+| Design feedback | Emerges from use | Explicit from start |
+
+### Agent Coordination
+- `qe-test-generator`: Generate tests in both schools
+- `qe-test-implementer`: Implement minimal code (Green)
+- `qe-test-refactorer`: Safe refactoring (Refactor)
+
+---
+
+## Chicago School (State-Based)
+
+**Philosophy:** Test observable behavior through public API. Keep tests close to consumer usage.
+
+```javascript
+// State verification - test final outcome
+describe('Order', () => {
+  it('calculates total with tax', () => {
+    const order = new Order();
+    order.addItem(new Product('Widget', 10.00), 2);
+    order.addItem(new Product('Gadget', 15.00), 1);
+
+    expect(order.totalWithTax(0.10)).toBe(38.50);
+  });
+});
+```
+
+**When Chicago Shines:**
+- Domain logic with clear state
+- Algorithms and calculations
+- Value objects (`Money`, `Email`)
+- Simple collaborations
+- Learning new domain
+
+---
+
+## London School (Mock-Based)
+
+**Philosophy:** Test each unit in isolation. Focus on how objects collaborate.
+
+```javascript
+// Interaction verification - test method calls
+describe('Order', () => {
+  it('delegates tax calculation', () => {
+    const taxCalculator = {
+      calculateTax: jest.fn().mockReturnValue(3.50)
+    };
+    const order = new Order(taxCalculator);
+    order.addItem({ price: 10 }, 2);
+
+    order.totalWithTax();
+
+    expect(taxCalculator.calculateTax).toHaveBeenCalledWith(20.00);
+  });
+});
+```
+
+**When London Shines:**
+- External integrations (DB, APIs)
+- Command patterns with side effects
+- Complex workflows
+- Slow operations (network, I/O)
+
+---
+
+## Mixed Approach (Recommended)
+
+```javascript
+// London for controller (external deps)
+describe('OrderController', () => {
+  it('creates order and sends confirmation', async () => {
+    const orderService = { create: jest.fn().mockResolvedValue({ id: 123 }) };
+    const emailService = { send: jest.fn() };
+
+    const controller = new OrderController(orderService, emailService);
+    await controller.placeOrder(orderData);
+
+    expect(orderService.create).toHaveBeenCalledWith(orderData);
+    expect(emailService.send).toHaveBeenCalled();
+  });
+});
+
+// Chicago for domain logic
+describe('OrderService', () => {
+  it('applies discount when threshold met', () => {
+    const service = new OrderService();
+    const order = service.create({ items: [...], total: 150 });
+
+    expect(order.discount).toBe(15); // 10% off > $100
+  });
+});
+```
+
+---
+
+## Common Pitfalls
+
+### ❌ Over-Mocking (London)
+```javascript
+// BAD - mocking everything
+const product = { getName: jest.fn(), getPrice: jest.fn() };
+```
+**Better:** Only mock external dependencies.
+
+### ❌ Mocking Internals
+```javascript
+// BAD - testing private methods
+expect(order._calculateSubtotal).toHaveBeenCalled();
+```
+**Better:** Test public behavior only.
+
+### ❌ Test Pain = Design Pain
+- Need many mocks? → Too many dependencies
+- Hard to set up? → Constructor does too much
+- Can't test without database? → Coupling issue
+
+---
+
+## Agent-Assisted TDD
+
+```typescript
+// Agent generates tests in both schools
+await Task("Generate Tests", {
+  style: 'chicago',      // or 'london'
+  target: 'src/domain/Order.ts',
+  focus: 'state-verification'  // or 'collaboration-patterns'
+}, "qe-test-generator");
+
+// Agent-human ping-pong TDD
+// Human writes test concept
+const testIdea = "Order applies 10% discount when total > $100";
+
+// Agent generates formal failing test (Red)
+await Task("Create Failing Test", testIdea, "qe-test-generator");
+
+// Human writes minimal code (Green)
+
+// Agent suggests refactorings
+await Task("Suggest Refactorings", { preserveTests: true }, "qe-test-refactorer");
+```
+
+---
+
+## Agent Coordination Hints
+
+### Memory Namespace
+```
+aqe/tdd/
+├── test-plan/*        - TDD session plans
+├── red-phase/*        - Failing tests generated
+├── green-phase/*      - Implementation code
+└── refactor-phase/*   - Refactoring suggestions
+```
+
+### Fleet Coordination
+```typescript
+const tddFleet = await FleetManager.coordinate({
+  workflow: 'red-green-refactor',
+  agents: {
+    testGenerator: 'qe-test-generator',
+    testExecutor: 'qe-test-executor',
+    qualityAnalyzer: 'qe-quality-analyzer'
+  },
+  mode: 'sequential'
+});
+```
+
+---
+
+## Related Skills
+- [agentic-quality-engineering](../agentic-quality-engineering/) - TDD with agent coordination
+- [refactoring-patterns](../refactoring-patterns/) - Refactor phase techniques
+- [api-testing-patterns](../api-testing-patterns/) - London school for API testing
+
+---
+
+## Remember
+
+**Chicago:** Test state, use real objects, refactor freely
+**London:** Test interactions, mock dependencies, design interfaces first
+**Both:** Write the test first, make it pass, refactor
+
+Neither is "right." Choose based on context. Mix as needed. Goal: well-designed, tested code.
+
+**With Agents:** Agents excel at generating tests, validating green phase, and suggesting refactorings. Use agents to maintain TDD discipline while humans focus on design decisions.

package/templates/.claude/skills/knowledge-extractor/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: knowledge-extractor
+description: >
+  Multi-agent knowledge harvesting system that extracts reusable patterns, commands,
+  rules, templates, and snippets from any project directory. Uses 5 parallel extractor
+  agents, 7-category classification, 8 blocking quality gates, and auto-placement.
+  Triggers on "harvest", "extract knowledge", "извлеки знания", "/harvest".
+trust_tier: 2
+trust_tier_label: "Validated"
+bto_score: 7.5
+bto_date: "2026-03-03"
+trust_tier_path: "Run /bto-test, score >= 8.5 + eval tests for Tier 3"
+---
+
+# Knowledge Extractor
+
+> Domain-agnostic multi-agent system for extracting, classifying, gating, and placing
+> reusable knowledge from completed projects into the toolkit.
+
+## When To Activate
+
+Trigger on:
+- `/harvest [path]` or `/harvest all`
+- "extract knowledge from [path]"
+- "извлеки знания из [path]"
+- "harvest patterns from [project]"
+- "что можно переиспользовать из [project]"
+
+## What You Get
+
+After a successful harvest session:
+- **Findings JSON** — structured extraction results at `.keysarium/harvest/findings-{SESSION_ID}.json`
+- **Placed artifacts** — skills, commands, and rules placed in `.claude/skills/`, `.claude/commands/`, `.claude/rules/`
+- **TOOLKIT_HARVEST.md** — updated with new patterns, templates, snippets, and hooks
+- **Harvest report** — session summary with metrics (extracted → approved → placed counts, gate pass rates)
+- **Memory record** — reward data stored via `memory_store()` for future session optimization
+
+## Architecture
+
+```
+.claude/skills/knowledge-extractor/
+├── SKILL.md                              ← This file (orchestrator)
+├── modules/
+│   ├── 01-extract.md                     ← 5 parallel extractor agents
+│   ├── 02-classify.md                    ← 7-category classification + dedup
+│   ├── 03-gate.md                        ← 8 quality gates (2-pass)
+│   └── 04-integrate.md                   ← Auto-placement + harvest report
+├── references/
+│   ├── quality-gates.md                  ← Gate definitions (G1-G8)
+│   ├── artifact-categories.md            ← 7 categories with destinations
+│   └── maturity-model.md                 ← Alpha → Beta → Stable
+└── templates/
+    ├── artifact-card.md                  ← Per-finding output template
+    └── harvest-report.md                 ← Session summary template
+```
+
+## Modules
+
+| Module | Purpose | Agents | Model |
+|--------|---------|--------|-------|
+| 01-extract | Scan project via 5 focused lenses | 5 parallel | sonnet |
+| 02-classify | Assign categories, deduplicate, cross-ref | 0 (inline) | — |
+| 03-gate | Evaluate 8 quality gates in 2 passes | 1 (semantic) | haiku |
+| 04-integrate | Place artifacts, generate report | 0 (inline) | — |
+
+## Pipeline Protocol
+
+### Step 0: Initialize Session
+
+1. Parse arguments: `{TARGET_PATH}` (directory or "all"), `{SCOPE_FILTER}` (optional `only X,Y`)
+2. **Resolve target path:**
+   - If `{TARGET_PATH}` is a specific directory → validate it exists, set `{slug}` = directory basename
+   - If `{TARGET_PATH}` is `"all"` → list all subdirectories in `researches/`. For each directory, run a separate harvest session (each gets its own findings JSON, session ID, and pipeline run). Merge reports at the end.
+   - If `{TARGET_PATH}` does not exist → report error and stop
+3. **Resolve domain:** If running inside a `/casarium` pipeline, inherit `{domain}` from Phase 0 discovery. If standalone, detect domain from file content keywords (banking/retail/enterprise/healthcare). If unable to detect, set `{domain}` = `"unknown"`.
+4. Generate session ID: `{slug}-{YYYYMMDDHHmmss}`
+5. If `TOOLKIT_HARVEST.md` does not exist at repo root → create it with a standard skeleton (title + empty section headers for each category).
+6. Call `memory_query({phase: "harvest", domain, slug, skill: "knowledge-extractor"})`
+7. Log loaded patterns count
+
+### Step 1: Extract (Module 01)
+
+```
+Read: modules/01-extract.md
+```
+
+Spawn 5 parallel extractor agents (sonnet), each with a focused lens:
+
+| Agent | Lens | Seeks |
+|-------|------|-------|
+| extractor-patterns | patterns | Architecture patterns, design patterns, agent topologies |
+| extractor-commands | commands | Scripts, CLI workflows, pipeline stages, automation |
+| extractor-rules | rules | Constraints, anti-patterns, lessons learned, domain rules |
+| extractor-templates | templates | Document structures, config templates, diagram templates |
+| extractor-snippets | snippets | Reusable code fragments, hooks, utility functions |
+
+Each agent returns numbered findings with reusability confidence (0.0-1.0).
+Orchestrator merges all findings into a single numbered list and writes to JSON:
+`.keysarium/harvest/findings-{SESSION_ID}.json`
+
+**Scope filtering:** If `{SCOPE_FILTER}` is set, only spawn matching agents. See mapping in `references/artifact-categories.md`.
+
+### Step 2: Classify (Module 02)
+
+```
+Read: modules/02-classify.md
+Read: references/artifact-categories.md
+```
+
+1. Read findings from JSON file
+2. Assign each finding to one of 7 categories
+3. Deduplicate: check content similarity across findings and against TOOLKIT_HARVEST.md
+4. Cross-reference: link findings that reference existing skills/commands
+5. Write classified findings back to JSON
+
+### Step 3: User Checkpoint (Interactive)
+
+Display all findings grouped by category as a numbered list:
+
+```
+═══════════════════════════════════════════════════════
+📋 HARVEST FINDINGS: {N} items extracted
+
+## patterns (K items)
+#1  [0.85] Agent Swarm Topology — parallel agents with merge pattern
+#4  [0.72] Event-Driven Pipeline — phase-to-phase data flow via files
+
+## rules (M items)
+#2  [0.91] Domain Detection Rule — auto-detect domain from keywords
+#7  [0.65] Regulatory Constraint — ФЗ-152 data isolation requirement
+
+## snippets (P items)
+#3  [0.78] CJM Renderer — universal React component for CJM display
+...
+
+Commands:
+• "убери #N"                    — remove finding
+• "переклассифицируй #N в X"   — reclassify to category X
+• "доработай #N"                — expand/improve finding
+• "объедини #N и #M"            — merge two findings
+• "покажи только X"             — filter by category
+• "ок"                          — proceed to quality gates
+═══════════════════════════════════════════════════════
+```
+
+Apply user mutations to JSON file. Numbers are stable (removed items leave gaps).
+Loop until user says "ок".
+
+### Step 4: Gate (Module 03)
+
+```
+Read: modules/03-gate.md
+Read: references/quality-gates.md
+```
+
+Evaluate each active finding against 8 quality gates in 2 passes:
+
+**Pass 1 — Deterministic (zero LLM cost):**
+- G1: Has "When to use" section
+- G2: Has "When NOT to use" section
+- G5: Reusability confidence >= 0.5
+- G6: Not a duplicate of existing toolkit entry
+- G7: Has maturity label (alpha/beta/stable)
+
+**Pass 2 — Semantic (haiku agent):**
+- G3: Properly decontextualized (no project-specific refs)
+- G4: Has at least one concrete example
+- G8: Passes brutal-honesty review (self-critical assessment)
+
+Findings passing all gates → status `approved`.
+Findings failing any gate → status `blocked` with gate IDs.
+
+Display blocked findings and allow overrides:
+```
+⚠️ BLOCKED: #7 — failed G3 (project-specific references remain)
+• "пропусти G3 для #7" — override gate
+• "ок" — accept blocks, proceed with approved only
+```
+
+### Step 5: Integrate (Module 04)
+
+```
+Read: modules/04-integrate.md
+Read: templates/artifact-card.md
+Read: templates/harvest-report.md
+```
+
+1. Render artifact cards for each approved finding
+2. Auto-place by category:
+   - `skills` → create `.claude/skills/<name>/SKILL.md` (skeleton)
+   - `commands` → create `.claude/commands/<name>.md`
+   - `hooks` → document in TOOLKIT_HARVEST.md (hooks section)
+   - `rules` → create `.claude/rules/<name>.md`
+   - `templates` → document in TOOLKIT_HARVEST.md (templates section)
+   - `patterns` → document in TOOLKIT_HARVEST.md (patterns section)
+   - `snippets` → document in TOOLKIT_HARVEST.md (snippets section)
+3. Update TOOLKIT_HARVEST.md "Обработанные проекты" table
+4. Generate harvest report
+5. Call `memory_store()` with harvest results and user reward
+6. Update `.keysarium/insights/trigger-state.json` (case_completion event)
+7. Clean up findings JSON file
+
+## Scope Filtering
+
+The `only` keyword filters which extractor agents are spawned:
+
+```
+/harvest path/                      → all 5 agents
+/harvest path/ only patterns        → extractor-patterns only
+/harvest path/ only rules,templates → extractor-rules + extractor-templates
+/harvest all only snippets          → extractor-snippets for each directory
+```
+
+Category-to-agent mapping (see `references/artifact-categories.md`):
+- patterns → extractor-patterns
+- commands → extractor-commands
+- hooks → extractor-commands (shared lens)
+- rules → extractor-rules
+- templates → extractor-templates
+- snippets → extractor-snippets
+- skills → all agents (skills are cross-cutting)
+
+## Integration Points
+
+| System | When | Operation |
+|--------|------|-----------|
+| memory_query() | Pipeline start | Load historical harvest patterns |
+| memory_store() | After user checkpoint | Store harvest reward data |
+| brain-export | N/A (passive) | Findings JSON is brain-compatible schema |
+| BTO | Post-harvest | Placed skills can be evaluated via `/bto-test` |
+| dream cycles | Pipeline end | Update trigger-state.json |
+| /harvest command | Entry point | Thin wrapper loads this skill |
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Extracting project-specific details | Finding contains project names, slugs, dates | Decontextualize: replace specifics with generic placeholders |
+| Duplicate extraction | content_hash matches existing TOOLKIT_HARVEST.md entry | Skip or merge; gate G6 blocks duplicates |
+| Extracting from incomplete phases | Artifact lacks promise tag or checkpoint | Only harvest from completed projects |
+| Over-classifying snippets as patterns | Single-use code without abstraction | Require reuse evidence before promoting to pattern |
+| Under-specifying maturity | All findings marked "stable" on first run | First extraction is always "alpha" or "beta" |
+| Skipping user checkpoint | Proceeding to gates without user review | BLOCK — user checkpoint is mandatory |
+| Running all agents when scope is filtered | `only patterns` but 5 agents spawned | Check SCOPE_FILTER before spawning |
+
+## Dependencies
+
+| Resource | Path | Purpose |
+|----------|------|---------|
+| quality-gates.md | references/quality-gates.md | Gate definitions for Module 03 |
+| artifact-categories.md | references/artifact-categories.md | 7-category taxonomy |
+| maturity-model.md | references/maturity-model.md | Alpha/Beta/Stable criteria |
+| artifact-card.md | templates/artifact-card.md | Per-finding output format |
+| harvest-report.md | templates/harvest-report.md | Session report format |

package/templates/.claude/skills/knowledge-extractor/modules/01-extract.md

@@ -0,0 +1,188 @@
+# Extract Module — Parallel Knowledge Extraction
+
+## Purpose
+
+Spawn 5 focused extractor agents to scan a project directory through different lenses, collecting reusable knowledge findings with confidence scores.
+
+## Input
+
+- `{TARGET_PATH}` — directory to scan (e.g., `researches/bank-kc-automation/`)
+- `{SCOPE_FILTER}` — optional list of lenses to activate (null = all 5)
+- `{MEMORY_PATTERNS}` — historical patterns from memory_query() (may be empty)
+- `{SESSION_ID}` — harvest session identifier
+
+## Protocol
+
+### Step 1: Inventory Target Directory
+
+List all files in `{TARGET_PATH}`. Build a file manifest with paths and sizes.
+Skip binary files, images, and files > 100KB.
+
+### Step 2: Determine Active Agents
+
+If `{SCOPE_FILTER}` is set, map categories to lenses:
+
+| Requested Category | Agent Lens to Spawn |
+|-------------------|---------------------|
+| patterns | extractor-patterns |
+| commands | extractor-commands |
+| hooks | extractor-commands (shared) |
+| rules | extractor-rules |
+| templates | extractor-templates |
+| snippets | extractor-snippets |
+| skills | ALL agents (cross-cutting) |
+
+If `{SCOPE_FILTER}` is null, spawn all 5 agents.
+
+### Step 3: Spawn Extractor Agents
+
+Spawn selected agents in parallel using the Agent tool:
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Harvest Extractor — {LENS_NAME}",
+  prompt="""
+    You are a knowledge extraction agent with a focused lens: {LENS_DESCRIPTION}.
+
+    ## Your Task
+    Scan the following project files and extract reusable knowledge through your lens.
+    For each finding, provide:
+    1. A short descriptive title (3-8 words)
+    2. Content: the reusable knowledge (decontextualized where possible)
+    3. "When to use" guidance (1-2 sentences)
+    4. "When NOT to use" guidance (1-2 sentences)
+    5. A concrete example of usage
+    6. Reusability confidence (0.0 to 1.0):
+       - 0.9-1.0: Universal, works in any project
+       - 0.7-0.89: Works in most similar projects
+       - 0.5-0.69: Works in some contexts
+       - < 0.5: Probably too project-specific
+    7. Suggested maturity: alpha (first time seen) or beta (if evidence of reuse)
+
+    ## Project Files
+    Read the following directory: {TARGET_PATH}
+
+    ## Historical Patterns (from previous harvests)
+    {MEMORY_PATTERNS_OR_NONE}
+
+    Avoid extracting findings that overlap with these historical patterns.
+
+    ## Extraction Rules
+    - Extract ONLY genuinely reusable knowledge
+    - DO NOT extract project-specific implementation details
+    - DO NOT extract trivial or obvious patterns
+    - Each finding must be independently useful outside this project
+    - Prefer actionable knowledge over abstract observations
+    - If in doubt about reusability, include it with a lower confidence score
+
+    ## Output Format
+    Return a numbered list of findings in this exact format:
+
+    ### Finding 1
+    **Title:** [short title]
+    **Confidence:** [0.0-1.0]
+    **Maturity:** [alpha|beta]
+    **Content:** [the reusable knowledge]
+    **When to use:** [guidance]
+    **When NOT to use:** [anti-guidance]
+    **Example:** [concrete example]
+
+    ### Finding 2
+    ...
+  """
+)
+```
+
+### Step 4: Handle Agent Failures
+
+If any extractor agent fails, times out, or returns malformed output:
+
+1. **Partial success:** Proceed with results from successful agents. Do NOT block the entire pipeline.
+2. **Log failures:** Record which lenses failed and why:
+   ```
+   ⚠️ Extractor agent failed: extractor-snippets (timeout after 120s)
+   Proceeding with 4/5 lenses. Snippets will not be harvested.
+   ```
+3. **Surface in report:** Add failed lenses to the harvest report's "Coverage Gaps" section.
+4. **Retry option:** Offer the user: `"повтори snippets"` — retry the failed lens only.
+5. **Malformed output:** If an agent returns output that cannot be parsed into the Finding format, discard that agent's results and log: `"Extractor {lens} returned unparseable output — discarded."`
+6. **Zero findings:** If an agent returns no findings, this is normal (not all lenses find relevant content). Log: `"Extractor {lens}: 0 findings (no relevant content detected)."`
+
+### Step 5: Report Skipped Files
+
+Before merging, surface any files that were skipped during inventory:
+
+```
+📋 File inventory: {total_files} files scanned, {skipped_count} skipped
+Skipped: {file1} (112KB, exceeds 100KB limit), {file2} (binary)
+```
+
+Include this in the harvest report under "Coverage Gaps" so the user knows what was NOT examined.
+
+### Step 6: Merge Results
+
+After all agents complete (or after handling failures):
+
+1. Collect all findings from all agents
+2. Assign sequential numbers starting from 1 (global numbering across all agents)
+3. Tag each finding with its source lens
+4. Set initial status to `raw`
+5. Write to findings JSON file at `.keysarium/harvest/findings-{SESSION_ID}.json`
+
+### 5 Agent Lens Descriptions
+
+| Agent | Lens Description |
+|-------|-----------------|
+| extractor-patterns | Architecture patterns, design patterns, agent topologies, data flow patterns, orchestration strategies, parallelism approaches. Look for structural solutions that could be applied to other systems. |
+| extractor-commands | CLI commands, scripts, pipeline stages, automation workflows, slash commands, build processes. Look for reusable command patterns and workflow automations. |
+| extractor-rules | Constraints, quality gates, anti-patterns, domain rules, naming conventions, regulatory requirements, lessons learned. Look for guardrails and restrictions that prevent mistakes. |
+| extractor-templates | Document structures, config file formats, diagram templates, report formats, checklist templates. Look for reusable document and configuration scaffolding. |
+| extractor-snippets | Reusable code fragments, utility functions, React components, bash one-liners, prompt templates, hook implementations. Look for copy-paste-ready code blocks. |
+
+## Output Format
+
+The findings JSON file structure:
+
+```json
+{
+  "session_id": "{SESSION_ID}",
+  "status": "extracting",
+  "target_paths": ["{TARGET_PATH}"],
+  "scope_filter": null,
+  "created_at": "ISO-8601",
+  "next_number": 16,
+  "extractors_spawned": ["patterns", "commands", "rules", "templates", "snippets"],
+  "findings": {
+    "1": {
+      "number": 1,
+      "title": "Agent Swarm Topology",
+      "content": "...",
+      "when_to_use": "...",
+      "when_not_to_use": "...",
+      "example": "...",
+      "confidence": 0.85,
+      "maturity": "alpha",
+      "source_lens": "patterns",
+      "category": null,
+      "status": "raw",
+      "gate_results": {},
+      "gate_overrides": [],
+      "merged_from": null
+    }
+  }
+}
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Agent extracts trivial findings | Findings like "use git for version control" | Prompt emphasizes non-obvious, actionable knowledge |
+| Agent reads files outside target | File paths outside {TARGET_PATH} | Prompt constrains to target directory only |
+| Duplicate findings across agents | Two agents extract the same pattern | Handled by Module 02 (dedup), not here |
+| Agent returns unstructured text | Missing required fields in output | Strict output format in prompt; orchestrator validates |
+| All findings have confidence 0.9+ | Agent is not being self-critical | Prompt calibration: explain the confidence scale |
+| Agent timeout with no fallback | Pipeline stalls waiting for failed agent | Use Step 4 failure protocol: proceed with partial results |
+| Large files silently skipped | User unaware of coverage gaps | Step 5 surfaces skipped files; harvest report includes coverage gaps |