@tyroneross/build-loop 0.30.3

package/skills/debug-loop/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: debug-loop
+description: Use when a fix didn't hold, `/build-loop:debug` is invoked, the user asks for root cause analysis, memory lookup returns LIKELY_MATCH/WEAK_SIGNAL/NO_MATCH, or Review-B Validate fails. Deep iterative debugging loop — not for known fixes or trivial issues.
+version: 1.1.0
+user-invocable: true
+---
+
+<!-- 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.
+
+## Scope Check
+
+Before entering the loop, assess whether it's warranted. The 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 debugging-memory returned `KNOWN_FIX` — apply the fix directly and verify
+- **Skip the loop** for trivial issues: typos, missing imports, obvious config errors where the cause is immediately clear
+- **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.
+
+**Domain root-cause catalogs (read directly + point sub-agents at the PATH):** for SwiftUI/macOS "clunky UI" symptoms — choppy/janky panel resize, drag not tracking the cursor, collapse-snap-back, re-render storms, scrunched panes, Picker/list lag — use `references/swiftui-macos-clunky-ui-debugger.html` (13 discrete Root-Cause→Fix slides with real Swift code: onContinuousHover, two-state DragGesture, HSplitView vs NSViewRepresentable, updateNSView feedback-loop guard, re-render storms, animation placement, view-identity resets, NSViewRepresentable minimal pattern, Instruments workflow). It maps symptom→cause→fix directly (e.g. collapse-snap-back → Slide 9 NSViewRepresentable feedback loop → updateNSView guard). When dispatching an implementer, reference the file by PATH so it reads the full methodology — a structured reference FILE read directly beats pasting prose (a sub-agent then carries only your lossy summary). This catalog fixed an NSSplitView resize regression in one pass after two prior failed attempts (easy-terminal 2026-06-08).
+
+## 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
+
+**Output**: Hypothesis statement, evidence level, prediction test, related symptom predictions
+
+## 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** — if you're adding a null check instead of fixing why something is null, you're fixing the symptom
+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
+
+**Output**: List of changes with rationale
+
+## 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 the predicted effects present?
+
+Every verification step must produce evidence: command output, test results, or observable behavior. "It should work" is not evidence.
+
+**Output**: Evidence for each verification step
+
+## Phase 5: SCORE — Evaluate Against Criteria
+
+**Goal**: Objective pass/fail assessment with evidence.
+
+Score against these criteria:
+
+| # | 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)
+
+**Output**: Scorecard with pass/fail per criterion and evidence
+
+## 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** → the 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
+
+Every item in the report gets one marker:
+
+- **✅ Verified**: Checked with evidence (test output, reproduction, command results)
+- **⚠️ Assumed**: Believed to be true based on reasoning, but not verified with a test
+- **❓ Unknown**: Not checked at all — explicitly acknowledged gaps
+
+### 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**: Minimum proof needed to understand the cause
+5. **Tradeoffs and impact**: What improves, what risks remain, and who is affected
+6. **Prevention control**: Durable test, verifier, trace, gate, protocol, or routing rule
+7. **Root cause**: The identified system cause with evidence level
+8. **Causal Tree**: The investigation path — confirmed branches, pruned branches with rejection evidence, any multi-causal findings
+9. **Fix Applied**: What was changed, with rationale
+10. **Scorecard**: Final pass/fail per criterion with evidence
+11. **Research Used**: What was searched externally, what was found, what sources
+12. **Iteration History** (if >1 iteration): What was tried, what failed, what changed between iterations
+13. **Remaining Gaps**: Anything marked ⚠️ or ❓
+
+### After Reporting
+
+- **Store the incident** as a native `.build-loop/issues/*.md` note for future retrieval
+- **Record the outcome** through standalone Coding Debugger only if that optional plugin supplied the prior incident
+- **Write state** to `.build-loop/debug-loop/scorecard.md`
+
+## Iteration Rules
+
+When any criterion fails or the critique is CHALLENGED, iterate:
+
+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
+
+Load `references/convergence-rules.md` for detailed rules and escalation templates.
+
+Summary:
+- **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 the approach entirely
+- **New regression detected** → fix is causing side effects, reconsider the approach
+- **Hard stop at 5 iterations** → report what's known and what isn't. Never silently loop beyond 5
+
+### If stuck — parallel multi-domain assessment
+
+When the failure symptom touches multiple layers (e.g. search queries are slow AND results look wrong → database + frontend + API), the linear causal-tree loop can stall. Branch into parallel assessment instead of pursuing one hypothesis serially:
+
+1. Invoke `Skill("build-loop:assess")` with the symptom and the current attempt diff. The bundled `assessment-orchestrator` fans out to relevant domain assessors (`api-assessor` / `database-assessor` / `frontend-assessor` / `performance-assessor`) in parallel.
+
+2. **Model override**: when invoking from the build-loop orchestrator (Opus 4.7), explicitly pass `model: sonnet` to each domain assessor via the subagent dispatch. Without this override, the assessor agents inherit the orchestrator's tier and you get 4 parallel Opus invocations — wasteful for pattern-matching work that Sonnet handles well. Only escalate individual assessors back to Opus if their initial output flags `confidence: low` or `needs_judgment: true`.
+
+3. Aggregate the assessors' ranked findings. The top action becomes the next `HYPOTHESIZE → FIX` plan — feed it back into the loop.
+
+When to use parallel assessment vs continuing the linear loop:
+- Symptom is vague or unclear ("app broken", "something is wrong") → parallel
+- Multiple domains may be involved ("search is slow and returns wrong results") → parallel
+- Post-deploy regression with unknown scope → parallel
+- Symptom is sharp and localized to one layer → continue the linear loop
+
+### Extended capability — cross-domain assessor escalation
+
+If the bundled assessor coverage isn't enough (e.g., the failure crosses a domain build-loop's bundled assessors don't cover well, or you need cross-build coordination), escalate via the native debugging skills:
+
+```
+Skill("build-loop:debugging-assess") with input { symptom, scope: "global", calledBy: "debug-loop", reason: "stuck-iteration" }
+```
+
+The native skill includes domain-specific assessors (api / database / frontend / performance). It uses build-loop local memory by default and may use standalone Coding Debugger for cross-build memory when available; otherwise it falls back to grep across `.build-loop/issues/` and `.build-loop/feedback.md` with narrower coverage.
+
+### State Tracking
+
+Write iteration state to `.build-loop/debug-loop/state.json`:
+
+```json
+{
+  "symptom": "original symptom",
+  "iteration": 1,
+  "phase": "VERIFY",
+  "hypotheses": [
+    {
+      "iteration": 1,
+      "hypothesis": "description",
+      "evidence_level": "strong | moderate | weak",
+      "result": "confirmed | disproved | partial",
+      "evidence": "what was found"
+    }
+  ],
+  "scorecard": [
+    {
+      "criterion": "symptom_resolved",
+      "result": "PASS | FAIL",
+      "evidence": "summary"
+    }
+  ],
+  "critique_verdict": "APPROVED | CHALLENGED | pending",
+  "changes_made": ["file:change summary"]
+}
+```
+
+Create the directory with `mkdir -p .build-loop/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 to Avoid
+
+| Anti-Pattern | What to Do Instead |
+|-------------|-------------------|
+| Accepting the first explanation | Branch first — identify 2+ plausible causes before pursuing any |
+| Fixing the symptom | Trace to root cause, fix there |
+| "This should fix it" | Run the tests, show the output |
+| Retrying the same approach | If it failed once with the same evidence, it'll fail again. Change the hypothesis |
+| Declaring victory without evidence | Every claim needs a ✅/⚠️/❓ marker |
+| Skipping research when stuck | If you don't know why something behaves this way, search for it |
+| Hiding uncertainty | ⚠️ and ❓ are not failures — they're honest. Hiding them is the failure |

package/skills/debug-loop/references/convergence-rules.md

@@ -0,0 +1,145 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Convergence Detection Rules
+
+Reference for the debug-loop iteration phase. Load on demand when entering iteration.
+
+## Rule 1: Repeated Hypothesis Failure
+
+**Trigger**: The same root cause hypothesis fails verification twice with the same or similar evidence.
+
+**What it means**: The hypothesis is likely wrong. More of the same fix won't help.
+
+**Action**: Escalate to user with this template:
+
+```
+I've attempted to fix this issue twice with the same approach:
+
+Hypothesis: [what we thought the root cause was]
+Attempt 1: [what was tried, why it failed]
+Attempt 2: [what was tried, why it failed]
+
+The evidence suggests this hypothesis may be incorrect, or there's a constraint
+I'm not seeing. Options:
+
+1. Investigate a different hypothesis: [alternative if available]
+2. Provide additional context about the system's expected behavior
+3. Narrow the scope to a specific aspect of the problem
+```
+
+**Do NOT**: Retry a third time with the same hypothesis. That's the definition of insanity.
+
+## Rule 2: Oscillation
+
+**Trigger**: Fixing criterion A causes criterion B to fail, and fixing B causes A to fail again.
+
+**What it means**: The two criteria have a shared dependency or conflicting requirements. The fixes are fighting each other.
+
+**Action**: Flag as coupled issue:
+
+```
+I've detected oscillation between two criteria:
+
+- Fixing [criterion A] breaks [criterion B]
+- Fixing [criterion B] breaks [criterion A]
+
+This suggests a shared dependency or conflicting constraint:
+[describe what the two criteria share]
+
+Options:
+
+1. Accept a tradeoff: prioritize one criterion over the other
+2. Refactor the shared dependency to support both
+3. Reconsider whether both criteria are correct requirements
+```
+
+**Do NOT**: Continue alternating fixes. Each iteration makes the code more tangled.
+
+## Rule 3: Cascading Failures
+
+**Trigger**: 3 or more criteria fail simultaneously after applying a fix (when fewer were failing before).
+
+**What it means**: The fix introduced a systemic problem. The root cause may be deeper than expected, or the fix touched a critical path.
+
+**Action**: Stop the loop entirely and reassess:
+
+```
+Systemic issue detected: [N] criteria now failing (was [M] before the fix).
+
+The fix to [what was changed] appears to have broader impact than expected.
+This suggests:
+
+1. The root cause is deeper/broader than the current hypothesis
+2. The changed code is on a critical path affecting multiple systems
+3. The approach needs fundamental rethinking
+
+Rolling back the fix and reassessing the investigation.
+
+New failures introduced:
+- [criterion]: [what went wrong]
+- [criterion]: [what went wrong]
+```
+
+**Do NOT**: Try to fix each new failure individually. That's treating symptoms of a bad fix.
+
+## Rule 4: Regression Detection
+
+**Trigger**: The original symptom is fixed, but the broader test suite reveals new failures that didn't exist before the fix.
+
+**What it means**: The fix has unintended side effects. It may be correct for the specific symptom but wrong for the system.
+
+**Action**: Flag and evaluate:
+
+```
+The original symptom is resolved, but the fix introduced new issues:
+
+Original fix: [what was changed]
+New failures:
+- [test/behavior]: [what broke]
+- [test/behavior]: [what broke]
+
+Assessment:
+- Are these related to the same root cause? [yes/no + reasoning]
+- Can the fix be adjusted to avoid these regressions? [yes/no + approach]
+- Is a different fix approach needed? [yes/no + alternative]
+```
+
+**Do NOT**: Ignore the regressions and declare the bug fixed. A fix that creates new bugs isn't a fix.
+
+## Iteration Limit
+
+**Hard stop at 5 iterations.** After 5 iterations:
+
+1. Report the current state with full transparency markers (✅/⚠️/❓)
+2. List every hypothesis that was tried and why it failed
+3. List what criteria are still failing
+4. Provide the best current understanding of the root cause
+5. Recommend next steps (often: different approach, more context needed, or pair debugging)
+
+```
+Debug loop completed 5 iterations without full resolution.
+
+Current state:
+✅ Verified: [what we know works]
+⚠️ Partial: [what partially works]
+❓ Unresolved: [what's still failing]
+
+Hypotheses tested:
+1. [hypothesis] — [result]
+2. [hypothesis] — [result]
+...
+
+Best current understanding: [what we think is happening]
+
+Recommended next steps:
+- [specific actionable suggestion]
+```
+
+## When NOT to Iterate
+
+Not every failure needs another loop. Exit early if:
+
+- The user provides new information that changes the problem entirely → restart investigation, don't iterate
+- The root cause is confirmed as external (library bug, infrastructure) → report and recommend workaround, don't iterate on code
+- The issue is a known limitation, not a bug → document and close
+- The user says to stop → respect it immediately