@tyroneross/build-loop 0.30.3

package/skills/debugging/assess/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: build-loop:debugging-assess
+description: Parallel domain assessment for complex debugging symptoms — fans out database / frontend / API / performance assessors in parallel and ranks findings. Build-loop's native assessor orchestration, adapted from debugger command workflows (no canonical SKILL.md exists upstream).
+version: 0.1.0
+user-invocable: false
+source: claude-code-debugger/commands/assess.md
+source_hash: f97d4966e110928acea7678124aad0c421e6fc64ddf0a6f53a7e14580650307a
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Parallel Domain Assessment
+
+Run multiple specialized assessor agents in parallel against a vague or multi-domain symptom, then rank findings by confidence. Native to build-loop; initially adapted from the debugger command workflow.
+
+> **Divergence note**: the standalone debugger ships this as a slash command, not a discrete SKILL.md. The assessor agents (`api-assessor`, `database-assessor`, `frontend-assessor`, `performance-assessor`) are bundled into build-loop under `agents/` and used directly here.
+
+## When to Activate
+
+- Phase 5 Iterate: after 2 consecutive same-root-cause failures in Review-B
+- Symptom is vague or unclear ("app broken", "something wrong")
+- Multiple domains may be involved ("search is slow and returns wrong results")
+- Post-deploy regression with unknown scope
+- Complex issue affecting multiple layers
+
+## Hard Caps
+
+- Spawn parallel assessors via `Agent` tool; obey the `~/.claude/CLAUDE.md` §Sub-Agents 4-parallel cap
+- Pin model to `sonnet` for each domain assessor — at the orchestrator's Opus 4.7 tier, defaulting to `inherit` would fan out 4× Opus invocations and shred the cost ledger
+- Only escalate an individual assessor to Opus if its initial output flags `confidence: low` or `needs_judgment: true`
+
+## Workflow
+
+1. **Detect domains** from symptom keywords:
+
+   | Domain | Trigger Keywords |
+   |--------|-----------------|
+   | Database | query, schema, migration, prisma, sql, connection, constraint, index |
+   | Frontend | react, hook, useEffect, render, component, state, hydration, browser |
+   | API | endpoint, route, request, response, auth, 500, 404, cors, middleware |
+   | Performance | slow, latency, timeout, memory, leak, cpu, bottleneck, optimization |
+
+2. **Search memory once** — invoke `build-loop:debugging-memory` with the symptom; pass any matching incidents to each assessor as context. Don't make each assessor re-query memory.
+
+3. **Launch assessors in parallel** with `Agent`, all in a single message:
+   - `database-assessor` — queries, schema, migrations, connection issues
+   - `frontend-assessor` — React, hooks, rendering, state, hydration, SSR
+   - `api-assessor` — endpoints, REST/GraphQL, auth, middleware, CORS
+   - `performance-assessor` — latency, memory, CPU, bottlenecks
+
+   Pass each: `{ symptom, repro_steps, related_incidents, files_in_scope, model: "sonnet" }`.
+
+4. **Aggregate results** — each assessor returns JSON:
+   ```json
+   {
+     "confidence": 0.0-1.0,
+     "probable_causes": ["..."],
+     "recommended_actions": ["..."],
+     "related_incidents": ["INC_..."]
+   }
+   ```
+
+5. **Rank** by confidence, then by `len(related_incidents)`. Generate priority sequence of recommended actions.
+
+6. **Present unified diagnosis** — top 3 actions, evidence count, escalation if all assessors return `confidence < 0.4`.
+
+## Result Aggregation Format
+
+```
+═══ PARALLEL DOMAIN ASSESSMENT ═══
+Symptom: <symptom string>
+Assessors fired: database, frontend, api, performance
+
+Top finding (confidence 0.78, database-assessor):
+  Probable cause: N+1 query on Article.findMany inside getServerSideProps
+  Recommended action: add `include: { author: true }` to eliminate per-row lookup
+  Related incidents: INC_DB_20260315_..., INC_DB_20260201_...
+
+Secondary finding (confidence 0.52, performance-assessor):
+  Probable cause: missing index on Article.publishedAt
+  Recommended action: add migration `CREATE INDEX articles_published_at`
+
+Action sequence: 1) eliminate N+1, 2) add index, 3) re-verify latency
+```
+
+## When Assessors Disagree
+
+If two assessors return overlapping `probable_causes` with similar confidence — flag as **multi-causal**. Both fixes may be needed. Don't pick one and discard the other.
+
+If they disagree fundamentally (e.g., database-assessor says query, performance-assessor says rendering) — present both, ask user which path to pursue first, OR escalate to `build-loop:debugging-debug-loop` for causal-tree investigation.
+
+## Output
+
+Write summary to `.build-loop/state.json.debugging.assess[<symptom-hash>]`:
+```json
+{
+  "symptom": "...",
+  "assessors_fired": ["database", "frontend", "api", "performance"],
+  "top_finding": { "domain": "database", "confidence": 0.78, "cause": "..." },
+  "action_sequence": [...],
+  "multi_causal": false
+}
+```
+
+## Sibling Skills
+
+- `build-loop:debugging-memory` — search before assessing (mandatory pre-step)
+- `build-loop:debugging-debug-loop` — escalate when assessment is inconclusive
+- `build-loop:debugging-store` — store the resolved incident after the recommended action lands
+
+*Source: adapted from the standalone debugger assess command plus the four assessor agents. Drift-checked by `build-loop:sync-skills`.*

package/skills/debugging/debug-loop/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: build-loop:debugging-debug-loop
+description: Iterative root-cause debugging with 5 Whys, causal/fault-tree analysis, hypothesis testing, fix-verify-score cycles, and fix-critique pressure-test. Up to 5 iterations. Build-loop's native debug loop, adapted from debugger workflows.
+version: 0.1.0
+user-invocable: false
+source: claude-code-debugger/skills/debug-loop/SKILL.md
+source_hash: 07b2dd2ad30c210b14bbac3c4e7ddd772ed642dd4c478dfbdb81b52ae809c92a
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Debug Loop — Iterative Root Cause Debugging
+
+A 7-phase debugging loop: investigate with structured root-cause methods, hypothesize root cause, implement targeted fix, verify with evidence, score against criteria, pressure-test via critique agent, and report with transparency markers. Iterates up to 5x on failures. Native to build-loop; initially adapted from the debugger workflow lineage.
+
+## Scope Check
+
+Trigger is the **verdict category**, not a numeric score — research shows LLM-assigned confidence scores are poorly calibrated for open-ended tasks (Tian et al., EMNLP 2023; 49-84% calibration error on open-ended generation).
+
+- **Skip the loop** if `build-loop:debugging-memory` returned `KNOWN_FIX` — apply the fix directly and verify
+- **Skip the loop** for trivial issues: typos, missing imports, obvious config errors
+- **Enter the loop** when: verdict is `LIKELY_MATCH`, `WEAK_SIGNAL`, or `NO_MATCH`, the user asks for deep investigation, the initial diagnosis feels superficial, or a previous fix attempt didn't hold
+
+## Efficiency
+
+- Terminal output: current phase, key findings (one line each), status changes, failures. No verbose reasoning
+- Agent context: minimum needed per job. Pass symptom + relevant findings, not full conversation history
+- Load convergence rules reference on demand only when entering iteration
+
+## Phase 1: INVESTIGATE — Gather Evidence and Trace Root Cause
+
+**Goal**: Understand what's actually failing and why, not just what it looks like.
+
+1. **Search debugging memory** — invoke `build-loop:debugging-memory` with the symptom. Note related incidents from local build-loop memory and optional standalone Coding Debugger memory when available.
+2. **Reproduce the issue** — identify exact steps, commands, or conditions that trigger the bug
+3. **Deploy `root-cause-investigator` agent** — pass the symptom and reproduction steps for causal tree analysis. The agent explores multiple branches (not a single chain), prioritizes by evidence strength, and prunes with evidence.
+4. **Research gate** — if the investigator flags unfamiliar error codes, library behavior, or version-specific issues:
+   - Search externally (WebSearch, Context7, or documentation)
+   - Document what was searched and what was found
+   - If search is unavailable, document what SHOULD be searched
+5. **Assess completeness** — does the investigation explain ALL reported symptoms? Check for multi-causal bugs (2+ independent root causes)
+
+**Output**: Causal tree (with confirmed and pruned branches), reproduction steps, evidence gathered, research performed.
+
+### Root-Cause Frameworks
+
+Use the lightest framework that fits the failure. Stack frameworks only when the current one stalls.
+
+| Framework | Use when | Output |
+|---|---|---|
+| 5 Whys | A symptom has a plausible linear chain and needs a controllable system cause | Five-level why-chain ending in a code, test, config, protocol, or process control |
+| Causal tree / fault tree | Multiple causes could explain the same symptom | Branches with confirming and pruning evidence |
+| Ishikawa / fishbone | The failure may span people/process/code/tooling/data/environment | Category map, then the top 2-3 branches to test |
+| Kepner-Tregoe problem analysis | The issue is intermittent, version-specific, or boundary-sensitive | Is/is-not table: affected/unaffected versions, inputs, users, routes, environments |
+| Differential diagnosis | Several hypotheses look similar from symptoms alone | Ranked hypotheses plus the discriminating test for each |
+| Falsification test | A hypothesis is attractive but under-proven | Smallest test that would disprove it |
+
+For hard fixes, record which framework was used and the decisive evidence. The framework is a thinking scaffold, not a report section unless it clarifies the outcome.
+
+## Phase 2: HYPOTHESIZE — State the Root Cause
+
+**Goal**: Commit to a specific, testable hypothesis before writing any fix.
+
+Start with plain language before implementation detail. State what failed in normal words, then trace visible symptom -> technical failure -> upstream dependency/interface/process failure -> first controllable system failure. Do not use "agent forgot", "agent missed context", or similar actor-blame language as the terminal cause unless you also name the missing system control that allowed it.
+
+1. **State the root cause hypothesis** with evidence level:
+   - **Strong**: Multiple evidence types (code, logs, reproduction) all point to this cause
+   - **Moderate**: Some direct evidence plus reasonable inference
+   - **Weak**: Mostly inference, limited direct evidence — consider investigating other branches first
+2. **Predict verification test**: If this hypothesis is correct, what specific test would prove it?
+3. **Predict related symptoms**: What else should be affected if this root cause is real?
+4. **If multiple hypotheses exist**, rank by evidence strength. Pursue the strongest first.
+
+## Phase 3: FIX — Implement Targeted Change
+
+**Goal**: Make the minimal change that addresses the hypothesized root cause.
+
+1. **Fix the root cause, not the symptom** — adding a null check instead of fixing why something is null is a symptom fix
+2. **Minimal changes** — touch only what's needed. Don't refactor, don't improve, don't clean up
+3. **Note exactly what was changed and why** — this becomes the evidence trail
+
+## Phase 4: VERIFY — Test the Fix with Evidence
+
+**Goal**: Collect concrete evidence that the fix works.
+
+1. Run the prediction test from Phase 2 — does it confirm the hypothesis?
+2. Run the original reproduction steps — is the symptom gone?
+3. Run related test suite — do existing tests still pass?
+4. Check for regressions — run broader test suite if available
+5. Verify related symptom predictions — are predicted effects present?
+
+Every verification step must produce evidence: command output, test results, observable behavior. "It should work" is not evidence.
+
+## Phase 5: SCORE — Evaluate Against Criteria
+
+**Goal**: Objective pass/fail with evidence.
+
+| # | Criterion | Method | Pass Condition | Evidence Required |
+|---|-----------|--------|----------------|-------------------|
+| 1 | Symptom resolved | Reproduction steps | Symptom no longer occurs | Command output or test result |
+| 2 | Tests pass | Test suite | All relevant tests pass | Test runner output |
+| 3 | No regressions | Broader test suite | No new failures introduced | Test runner output |
+| 4 | Root cause addressed | Code review | Fix targets root cause, not symptom | Diff + reasoning |
+| 5 | Hypothesis confirmed | Prediction test | Prediction test passes | Test output |
+
+**All criteria must have evidence.** No criterion marked PASS without proof.
+
+If any criterion fails → enter iteration (Phase 6 rules apply).
+If all criteria pass → proceed to critique (Phase 6).
+
+## Phase 6: CRITIQUE — Pressure-Test Before Declaring Done
+
+**Goal**: Challenge the fix before the user relies on it.
+
+1. **Deploy `fix-critique` agent** with: the symptom, the causal tree from investigation (confirmed branch path + pruned branches), the fix (what was changed), the verification evidence
+2. **Evaluate verdict**:
+   - **APPROVED** → proceed to REPORT
+   - **CHALLENGED** → concerns become input for the next iteration. Route back to INVESTIGATE with the specific challenges as new investigation targets
+
+The critique agent checks 5 things:
+- Root cause vs symptom fix
+- Symptom coverage (similar bugs elsewhere)
+- Regression risk
+- Evidence verification
+- Causal tree consistency
+
+## Phase 7: REPORT — Transparent Status
+
+**Goal**: Clear, honest summary. No overclaiming.
+
+### Transparency Markers
+
+- ✅ **Verified**: Checked with evidence (test output, reproduction, command results)
+- ⚠️ **Assumed**: Believed true based on reasoning, not verified with a test
+- ❓ **Unknown**: Not checked — explicitly acknowledged gap
+
+### Report Contents
+
+1. Verdict: Fixed (all criteria pass + critique approved) or Unresolved (iteration limit hit)
+2. Plain-language failure: what went wrong in normal words
+3. Why it happened: symptom -> technical failure -> upstream dependency/interface/process failure -> first controllable system failure
+4. Technical details needed to prove the cause
+5. Tradeoffs and impact
+6. Prevention control
+7. Root cause + evidence level
+8. Causal tree — confirmed branches, pruned branches with rejection evidence, multi-causal findings
+9. Fix applied — what was changed, with rationale
+10. Scorecard — final pass/fail per criterion + evidence
+11. Research used — what was searched, what was found
+12. Iteration history (if >1 iteration) — what was tried, what failed, what changed
+13. Remaining gaps — anything ⚠️ or ❓
+
+### After Reporting
+
+- Store via `build-loop:debugging-store`
+- Record outcome through standalone Coding Debugger only when it supplied the matched prior incident
+- Write state to `.build-loop/debugging-debug-loop/scorecard.md`
+
+## Iteration Rules
+
+When any criterion fails or critique is CHALLENGED:
+
+1. Diagnose why the criterion failed — don't blind retry
+2. Revise the hypothesis if verification disproved it
+3. Create targeted fix plan for failed criteria only
+4. Execute fix
+5. Re-verify ONLY failed criteria — don't re-run passing checks
+6. Re-score and re-critique
+
+### Convergence Detection
+
+- **Same hypothesis fails 2x** → escalate to user ("I've tried this approach twice — the hypothesis may be wrong or there's a constraint I'm not seeing")
+- **Fix A breaks criterion B (oscillation)** → flag as coupled issue, present both sides, ask user
+- **3+ criteria fail after a fix** → systemic issue, stop loop and reassess
+- **New regression detected** → fix is causing side effects, reconsider
+- **Hard stop at 5 iterations** → report what's known and what isn't
+
+### State Tracking
+
+Write iteration state to `.build-loop/debugging-debug-loop/state.json`:
+
+```json
+{
+  "symptom": "...",
+  "iteration": 1,
+  "phase": "VERIFY",
+  "hypotheses": [
+    { "iteration": 1, "hypothesis": "...", "evidence_level": "strong|moderate|weak", "result": "confirmed|disproved|partial", "evidence": "..." }
+  ],
+  "scorecard": [
+    { "criterion": "symptom_resolved", "result": "PASS|FAIL", "evidence": "..." }
+  ],
+  "critique_verdict": "APPROVED|CHALLENGED|pending",
+  "changes_made": ["file:change summary"]
+}
+```
+
+`mkdir -p .build-loop/debugging-debug-loop/` before writing.
+
+## Process Flow
+
+```
+MEMORY SEARCH → INVESTIGATE → HYPOTHESIZE → FIX → VERIFY → SCORE
+                                                       ↓
+                                                  All pass? ──yes──→ CRITIQUE ──approved──→ REPORT
+                                                       ↓                  ↓
+                                                      no            challenged
+                                                       ↓                  ↓
+                                                  ITERATE ←──────────────┘
+                                                 (up to 5x)
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | What to Do Instead |
+|-------------|-------------------|
+| Accepting the first explanation | Branch first — identify 2+ plausible causes |
+| Fixing the symptom | Trace to root cause |
+| "This should fix it" | Run the tests, show the output |
+| Retrying the same approach | If it failed once with the same evidence, change the hypothesis |
+| Declaring victory without evidence | Every claim needs ✅/⚠️/❓ |
+| Skipping research when stuck | Search for unfamiliar behavior |
+| Hiding uncertainty | ⚠️ and ❓ are not failures — hiding them is |
+
+## Sibling Skills
+
+- `build-loop:debugging-memory` — mandatory pre-step (Phase 1.1)
+- `build-loop:debugging-assess` — escalation path when investigation can't isolate domain
+- `build-loop:debugging-store` — Phase 7 incident storage
+
+*Source: adapted from the debugger workflow lineage and maintained as a build-loop-native skill. Drift-checked by `build-loop:sync-skills`.*

package/skills/debugging/memory/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: build-loop:debugging-memory-search
+description: Memory-first lookup before debugging — search local build-loop incidents and optionally standalone Coding Debugger memory. Build-loop's native debugging memory, adapted from debugger workflows. Distinct from the legacy in-tree `build-loop:debugging-memory` skill (kept for backward compat); this is the source-tracked native version.
+version: 0.1.0
+user-invocable: false
+source: claude-code-debugger/skills/debugging-memory/SKILL.md
+source_hash: 5c4ee5ada781107e7def92abeca4d51fc0efc61700f7cf43e948da34f4c0681d
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Debugging Memory Workflow (Native, Sourced)
+
+Memory-first debugging. Core principle: **never solve the same bug twice**. Native to build-loop; initially adapted from the debugger workflow lineage. Search local `.build-loop/issues/` first, then use standalone Coding Debugger for cross-project memory only when that plugin is installed.
+
+> **Naming note**: this skill is `build-loop:debugging-memory-search` to avoid colliding with the legacy in-tree `build-loop:debugging-memory` skill (which the orchestrator continues to call as the memory-first gate's primary entry point). Both have equivalent content; this one carries `source` + `source_hash` provenance and is drift-checked by `build-loop:sync-skills`. New code should prefer the legacy name until the orchestrator is migrated; sibling skills in `skills/debugging/` reference the legacy name where the gate's exact runtime semantics are needed.
+
+## When to Activate
+
+- Phase 1 Assess: pull recent project incident context for orientation (`list-recent` intent)
+- Phase 4 Review-B Validate: on every criterion failure with an error-like signal — read logs first, synthesize symptom, search memory
+- Phase 5 Iterate: at the start of every Iterate attempt, re-search with the new symptom (failure may have shifted shape after a fix)
+
+## Memory-First Approach
+
+Before investigating any bug, check debugging memory with the symptom description.
+
+The search returns a **verdict** with matching incidents and patterns when structured memory is available. File-backed fallback returns a degraded local verdict with the same action shape.
+
+**Verdict-based decision tree:**
+
+1. **KNOWN_FIX**: Apply the documented fix directly only when the strict direct-apply gate (below) passes; otherwise adapt the prior incident as a hypothesis and route to the standard fix flow
+2. **LIKELY_MATCH**: Review the past incident, use it as a starting point — never direct-apply
+3. **WEAK_SIGNAL**: Consider loosely related incidents, but investigate fresh
+4. **NO_MATCH**: Proceed with standard debugging via `build-loop:debugging-debug-loop`, then document the solution after
+
+### Direct-apply gate (KNOWN_FIX only)
+
+All three must pass — otherwise downgrade to adapted-plan routing and record `direct_apply_blocked_by`:
+
+1. **file_match**: at least one file in the prior incident's `files_changed` exists in current repo at same relative path
+2. **version_match**: dependency versions in the prior incident match current within minor (semver). If the prior incident's `tags` include a version, compare it to current `package.json`/`requirements.txt`/etc.
+3. **second_signal**: at least one secondary signal — same error class, same callsite line range, or same component layer
+
+Skip direct-apply for any pattern with category `react-hooks`, `performance`, or anything where the fix is "increase value X" — those are context-sensitive.
+
+## Progressive Depth Retrieval
+
+1. **Initial search**: local build-loop incident lookup; if standalone Coding Debugger is available, use its `search` tool for cross-project matches
+2. **Drill down**: read the local issue file or, for Coding Debugger matches, use `detail` with the ID
+3. **Outcome tracking**: for Coding Debugger matches, use `outcome` to record whether the fix worked
+
+## Visibility
+
+When this skill activates, always announce it to the user:
+
+1. **Before searching**: "Checking debugging memory for similar issues..."
+2. **After search**: "Found X matching incident(s) from past debugging sessions" or "No matching incidents — starting fresh investigation"
+
+## Deep Investigation Mode
+
+For non-trivial issues, escalate to the `build-loop:debugging-debug-loop` skill. Trigger is the **verdict category**, not a numeric confidence score:
+
+- **`KNOWN_FIX`** → apply directly, skip the loop
+- **`LIKELY_MATCH`** → enter debug loop (past incidents need verification against current context)
+- **`WEAK_SIGNAL`** → enter debug loop (loosely related, fresh investigation needed)
+- **`NO_MATCH`** → enter debug loop (no prior knowledge)
+
+Also enter the debug loop when:
+- Initial diagnosis feels superficial
+- Previous fix didn't hold
+- User explicitly asks for root-cause analysis
+- Multiple symptoms suggest a shared cause
+
+## Basic Steps (simple, clear-cut issues)
+
+1. **Reproduce** — exact steps, environmental factors, minimal repro
+2. **Isolate** — binary search recent changes, disable components, check logs
+3. **Diagnose** — trace execution, examine state, identify offending code
+4. **Fix** — minimal, targeted, no side effects
+5. **Verify** — original repro, related tests, regression check
+
+## Incident Documentation
+
+After fixing a bug, store via `build-loop:debugging-store`. Required fields: `symptom`, `root_cause`, `fix`. Optional: `category`, `tags`, `files_changed`, `file`.
+
+## Quality Indicators
+
+The memory system scores incidents on:
+- Root cause analysis depth (30%)
+- Fix documentation completeness (30%)
+- Verification status (20%)
+- Tags and metadata (20%)
+
+Target 75%+ quality score for effective future retrieval.
+
+## Tagging Strategy
+
+- Technology: `react`, `typescript`, `api`, `database`
+- Category: `logic`, `config`, `dependency`, `performance`
+- Symptom type: `crash`, `render`, `timeout`, `validation`
+
+## Pattern Recognition
+
+The memory system extracts patterns when 3+ similar incidents exist. Patterns have higher reliability than individual incidents. When a pattern matches, trust the solution template (90%+ confidence), apply the recommended approach, note caveats.
+
+## Optional Coding Debugger Tools
+
+| Tool | Purpose |
+|------|---------|
+| `search` | Search memory for similar bugs (returns verdict) |
+| `store` | Store a new debugging incident |
+| `detail` | Get full incident or pattern details |
+| `status` | Show memory statistics |
+| `list` | List recent incidents |
+| `patterns` | List known fix patterns |
+| `outcome` | Record whether a fix worked |
+
+Use these only when standalone Coding Debugger is installed. Build-loop does not register these MCP tools itself.
+
+## Review-F Outcome Feedback
+
+Closes the memory-first gate's feedback loop. Both required:
+
+- For each newly resolved Review-B/Iterate failure: invoke `build-loop:debugging-store` with `{symptom, root_cause, fix, tags: ["build-loop", project, layer], files}`
+- For each Review-B memory gate where standalone Coding Debugger supplied a prior `KNOWN_FIX` or `LIKELY_MATCH`: invoke its `outcome` tool with `{incident_id, result: "worked"|"failed"|"modified", notes}` — this trains the optional verdict classifier
+
+Skipping `outcome` means the optional verdict classifier never improves.
+
+## Subagent Integration
+
+When debugging involves subagents:
+
+1. **Pre-query memory once** through `build-loop:debugging-memory` before spawning agents
+2. **Distribute context** — each agent gets relevant subset
+3. **Aggregate findings** — collect insights from all agents
+4. **Store unified incident** — single `build-loop:debugging-store` call to document combined diagnosis
+
+Subagents do not inherit Skill or MCP access — pre-load context into their prompt.
+
+## Sibling Skills
+
+- `build-loop:debugging-store` — write incident after fix
+- `build-loop:debugging-assess` — parallel domain assessment for multi-domain symptoms
+- `build-loop:debugging-debug-loop` — iterative root-cause analysis with causal-tree investigation
+
+*Source: adapted from the debugger workflow lineage and maintained as a build-loop-native skill. Drift-checked by `build-loop:sync-skills`.*

package/skills/debugging/store/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: build-loop:debugging-store
+description: Store a debugging incident after fixing a bug — writes build-loop's native local incident record and optionally mirrors to standalone Coding Debugger. Build-loop's native incident storage; canonical source has no discrete SKILL.md (the §"Incident Documentation" section of debugging-memory).
+version: 0.1.0
+user-invocable: false
+source: claude-code-debugger/skills/debugging-memory/SKILL.md
+source_hash: 5c4ee5ada781107e7def92abeca4d51fc0efc61700f7cf43e948da34f4c0681d
+source_section: "Incident Documentation"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Debugging Incident Storage
+
+Persist a fixed bug to debugging memory so future builds can recognize recurrence. Native to build-loop; initially adapted from the §"Incident Documentation" workflow in the debugger lineage.
+
+> **Divergence note**: the standalone debugger does not ship a discrete `store` SKILL.md. Build-loop keeps storage as a native skill because Review-F needs deterministic local persistence even when no MCP server exists.
+
+## When to Activate
+
+- Phase 4 Review-F Report: for each Review-B/Iterate failure newly resolved this build, store the incident
+- After any `build-loop:debugging-debug-loop` run that produced a verified fix
+- User asks "save this fix", "remember this bug"
+
+## Native Path — Build-Loop Incident Note
+
+Write one incident note per resolved failure:
+
+```bash
+mkdir -p .build-loop/issues
+```
+
+Path:
+
+```text
+.build-loop/issues/YYYY-MM-DD-<short-slug>.md
+```
+
+Template:
+
+```markdown
+# <one-line symptom>
+
+**Symptom**: <error string, failing command, or observed behavior>
+**Root cause**: <technical cause plus first controllable system cause>
+**Fix**: <what changed and why>
+**Verification**: <commands, tests, or observed proof>
+**Files**: <paths touched>
+**Tags**: build-loop, <project>, <layer>, <framework>, <symptom-type>
+**RCA framework**: <5 Whys | causal tree | fishbone | Kepner-Tregoe | differential diagnosis | falsification>
+```
+
+**Required**: `symptom`, `root_cause`, `fix`, `verification`. Everything else improves future retrieval.
+
+## Optional Mirror — Coding Debugger MCP
+
+If standalone Coding Debugger is installed and available, mirror the same incident:
+
+```
+mcp__plugin_coding_debugger__store({
+  symptom: "user-facing description (≤200 chars, preserves error type/file/key phrase)",
+  root_cause: "technical explanation of why",
+  fix: "what was changed",
+  category: "logic|config|dependency|performance|react-hooks",
+  tags: ["build-loop", "<project>", "<layer>", "<framework>", "<symptom-type>"],
+  files_changed: ["path/to/file1.ts", "path/to/file2.ts"],
+  file: "path/to/primary/problematic/file.ts"
+})
+```
+
+Mirror failure is not a build failure. Report it as "local incident stored; Coding Debugger mirror unavailable."
+
+## Tag Discipline
+
+Always include:
+- `"build-loop"` — distinguishes build-orchestrator origins from manual `/build-loop:debug` runs
+- Project name (lowercase, slugified)
+- Layer (`frontend`, `backend`, `database`, `infra`, `external`)
+
+Add as relevant:
+- Technology: `react`, `typescript`, `python`, `api`, `prisma`
+- Category: `logic`, `config`, `dependency`, `performance`
+- Symptom type: `crash`, `render`, `timeout`, `validation`
+
+## Quality Score Targets
+
+The memory system scores stored incidents:
+- Root cause depth (30%)
+- Fix documentation completeness (30%)
+- Verification status (20%)
+- Tags and metadata (20%)
+
+Target 75%+. Score below 75% means future searches won't surface this incident reliably — pad the description and tags before storing.
+
+## JSON Compatibility Fallback
+
+If a downstream process requires JSON, write a compatibility copy after the native note:
+
+**Step 1: Generate incident ID**
+```
+INC_<CATEGORY>_YYYYMMDD_HHMMSS_xxxx
+```
+where `xxxx` is 4 random alphanumeric characters. Example: `INC_API_20260403_143052_a7b2`.
+
+**Step 2: Ensure directory exists**
+```bash
+mkdir -p .build-loop/debugging/incidents
+```
+
+**Step 3: Write the JSON**
+```json
+{
+  "incident_id": "INC_API_20260403_143052_a7b2",
+  "timestamp": 1735654252000,
+  "symptom": "User-facing description of the bug",
+  "root_cause": {
+    "description": "Technical explanation",
+    "file": "path/to/problematic/file.ts",
+    "category": "logic|config|dependency|performance|react-hooks",
+    "confidence": 0.85
+  },
+  "fix": {
+    "approach": "What was done",
+    "changes": [
+      { "file": "path/to/file.ts", "lines_changed": 10, "change_type": "modify|add|delete", "summary": "..." }
+    ]
+  },
+  "verification": {
+    "status": "verified|unverified",
+    "regression_tests_passed": true,
+    "success_criteria_met": true
+  },
+  "tags": ["build-loop", "project-name", "layer", "category"],
+  "files_changed": ["list/of/all/files.ts"],
+  "quality_score": 0.75
+}
+```
+
+Write to `.build-loop/debugging/incidents/<incident_id>.json`. Flag `debugger JSON compatibility copy written` in Review-F only if another workflow requested JSON.
+
+## After Storing
+
+1. Confirm the local note path.
+2. If standalone Coding Debugger supplied the prior incident, invoke `outcome({incident_id, result: "worked"|"failed"|"modified", notes})` to train its verdict classifier.
+3. If the note lacks verification, enrich it before ending Review-F.
+
+## Sibling Skills
+
+- `build-loop:debugging-memory` — search memory before debugging
+- `build-loop:debugging-assess` — parallel domain assessment
+- `build-loop:debugging-debug-loop` — full iterative debugging that produces the incident this skill stores
+
+*Source: adapted from the debugger incident-documentation workflow and maintained as a build-loop-native skill. Drift-checked by `build-loop:sync-skills`.*