@tyroneross/build-loop 0.30.3

package/skills/debugging-memory/SKILL.md

@@ -0,0 +1,440 @@
+---
+name: debugging-memory
+description: Use when the user asks to "debug this", "fix this bug", "investigate error", "diagnose", "root cause", or reports a crash/exception/failure. Memory-first workflow checks past incidents before investigating.
+version: 1.5.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Debugging Memory Workflow
+
+This skill integrates build-loop's native debugging memory into debugging workflows. The core principle: **never solve the same bug twice**.
+
+## Memory-First Approach
+
+Before investigating any bug, always check build-loop's native debugging memory:
+
+```
+Search `.build-loop/issues/` and invoke `build-loop:debugging-memory-search` with the symptom description.
+```
+
+The search returns a **verdict** with matching incidents and patterns.
+
+**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, document the solution afterward
+
+## Direct-apply gate (strict)
+
+Compressing a failure to a single-line symptom and then applying a historical fix directly can overfit on superficially similar incidents (same error string, different root cause, version, or layer). Direct-apply on a `KNOWN_FIX` is gated behind three independent checks. **All three must hold** or the verdict falls back to "adapted plan, route through the normal fix flow":
+
+1. **File match**: at least one of the incident's `files[]` exists at the same path in the current project (suffix match is acceptable — `src/auth/session.ts` matches even if relative vs absolute).
+2. **Version match**: if the incident records a framework/library version (e.g. `next@14`, `prisma@5.8`), the current project's equivalent version must be within the same major (and same minor for libraries with pre-1.0 semver). If no version metadata on the incident, this check defaults to **fail** — no direct-apply.
+3. **Second validation signal**: a non-symptom-string match must also agree. At least one of:
+   - An exact stack-frame match (same function name + same file) between current failure and incident
+   - A matching error class/type hierarchy (not just the message text)
+   - A matching log entry from `read_logs` that ran earlier in the gate
+
+If any of the three fails, downgrade to adapted-plan routing and record the downgrade with `direct_apply_blocked_by: "version_mismatch" | "no_file_overlap" | "no_secondary_signal"`.
+
+**Why this is strict**: a bad direct-apply mutates the codebase on a lossy match and then Review-F stores the (wrong) outcome back to memory, reinforcing the false association. The cost of occasionally skipping a legitimate direct-apply is small; the cost of one overfit mutation compounding across sessions is large.
+
+When `KNOWN_FIX` direct-apply is blocked, the caller should treat the verdict as `LIKELY_MATCH` for routing purposes — load the top incident's detail, adapt the fix to current context, and run it through whatever fix flow the caller normally uses (in build-loop, that's Iterate as an adapted plan).
+
+## Progressive Depth Retrieval
+
+Results are returned as compact summaries. Drill into matches on demand:
+
+1. **Initial search**: Use `build-loop:debugging-memory-search` — returns verdict + compact matches when structured memory exists
+2. **Drill down**: Read the matching `.build-loop/issues/<id>.md` incident note for full context
+3. **Outcome tracking**: Use `build-loop:debugging-store` after verification to record whether the fix worked, failed, or was modified
+
+## Visibility
+
+When this skill activates, always announce it to the user:
+
+1. **Before searching**: Output "Checking debugging memory for similar issues..."
+2. **After search**: Report result briefly:
+   - Found match: "Found X matching incident(s) from past debugging sessions"
+   - No match: "No matching incidents in debugging memory - starting fresh investigation"
+
+This ensures users know the debugger is active and working.
+
+## Structured Debugging Process
+
+When no past solution applies, follow this systematic approach.
+
+### Deep Investigation Mode
+
+For non-trivial issues, load the `debug-loop` skill instead of the basic steps below. The trigger is the **verdict category** from memory search, not a numeric confidence score:
+
+- **`KNOWN_FIX`** → apply the fix directly, skip the loop
+- **`LIKELY_MATCH`** → enter debug loop (past incidents exist but need verification against current context)
+- **`WEAK_SIGNAL`** → enter debug loop (loosely related, needs fresh investigation)
+- **`NO_MATCH`** → enter debug loop (no prior knowledge, full investigation needed)
+
+Also enter the debug loop when:
+- The initial diagnosis feels superficial (treating a symptom as the cause)
+- A previous fix attempt didn't hold — the bug came back
+- The user explicitly asks for root cause analysis or deep investigation
+- Multiple symptoms suggest a shared underlying cause
+
+The debug loop provides: causal tree investigation, hypothesis testing, iterative fix-verify-score cycles (up to 5x), fix critique before declaring done, and transparent ✅/⚠️/❓ reporting.
+
+### Basic Steps (for simple, clear-cut issues)
+
+For straightforward bugs where the cause is immediately apparent, use these steps directly:
+
+### 1. Reproduce
+
+Establish a reliable reproduction path:
+- Identify exact steps to trigger the bug
+- Note any environmental factors (OS, dependencies, state)
+- Create a minimal reproduction if possible
+
+### 2. Isolate
+
+Narrow down the problem space:
+- Binary search through recent changes
+- Disable components to find the culprit
+- Check logs and error messages for clues
+
+### 3. Diagnose
+
+Find the root cause:
+- Trace the execution path
+- Examine state at failure point
+- Identify the specific code causing the issue
+
+### 4. Fix
+
+Implement the solution:
+- Make minimal, targeted changes
+- Avoid side effects
+- Consider edge cases
+
+### 5. Verify
+
+Confirm the fix works:
+- Test the original reproduction steps
+- Run related tests
+- Check for regressions
+
+## Review-F outcome feedback (closing the memory-first loop)
+
+When a build / debugging session completes, close the feedback loop locally. If standalone Coding Debugger supplied cross-project memory for this run, mirror the result there as an optional second step.
+
+### Step A — Store resolved incidents (write new knowledge)
+
+For each failure resolved during this run, write a native Build Loop incident note:
+
+```bash
+mkdir -p .build-loop/issues
+```
+
+```markdown
+# <short incident title>
+
+## Symptom
+<original failure string>
+
+## Root Cause
+<what was wrong>
+
+## Fix
+<diff or description>
+
+## Verification
+<tests or reproduction checks that passed>
+
+## Tags
+build-loop, <project>, <layer>
+```
+
+Use `.build-loop/issues/<stable-slug>.md` as the path. Keep each note concise enough for future local search to surface the symptom, root cause, and verified fix.
+
+### Step B — Report outcomes on applied optional memory
+
+For each prior gate where standalone Coding Debugger supplied a `KNOWN_FIX` or `LIKELY_MATCH`, report back whether the suggested fix actually worked through that plugin's outcome tool:
+
+- `worked`: applied as-is, resolved the criterion on first attempt
+- `modified`: applied the suggested approach but had to adapt substantially (Iterate attempt count > 1 on that criterion)
+- `failed`: applied but criterion still failed; eventually resolved via different fix or not at all
+
+This optional training signal belongs to standalone Coding Debugger. Build Loop itself does not register an MCP outcome tool.
+
+## Incident Documentation
+
+After fixing a bug, store a local `.build-loop/issues/*.md` incident note for future retrieval.
+
+The local note should include:
+- **Symptom**: user-facing description of the bug
+- **Root Cause**: technical explanation of why the bug occurred
+- **Fix**: what was done to fix it
+- **Verification**: tests or reproduction checks that passed
+- **Tags**: search keywords for future retrieval
+- **Files Changed**: list of files that were modified
+
+### Manual Incident Storage (Alternative)
+
+Agents can write incident files directly with the Write tool.
+
+**Step 1: Generate incident ID**
+```
+INC_YYYYMMDD_HHMMSS_xxxx
+```
+Where `xxxx` is 4 random alphanumeric characters. Example: `INC_20241231_143052_a7b2`
+
+**Step 2: Write JSON file**
+```bash
+.build-loop/issues/INC_20241231_143052_a7b2.md
+```
+
+**Minimal incident structure:**
+```markdown
+# INC_20241231_143052_a7b2
+
+## Symptom
+User-facing description of the bug.
+
+## Root Cause
+Technical explanation of why the bug occurred.
+
+## Fix
+What was done to fix it.
+
+## Verification
+- Reproduction now passes
+- Related regression tests pass
+
+## Files Changed
+- path/to/file.ts
+
+## Tags
+relevant, keywords, search
+```
+
+**Step 3: Ensure directory exists**
+Before writing, create the directory if needed:
+```bash
+mkdir -p .build-loop/issues
+```
+
+### 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
+
+Apply descriptive tags for better searchability:
+- Technology: `react`, `typescript`, `api`, `database`
+- Category: `logic`, `config`, `dependency`, `performance`
+- Symptom type: `crash`, `render`, `timeout`, `validation`
+
+## Using Past Solutions
+
+When the memory system finds a match:
+
+1. **Review the past incident** - Understand the original context
+2. **Assess applicability** - Consider differences in current situation
+3. **Adapt the fix** - Modify as needed for current codebase
+4. **Verify thoroughly** - The same symptom may have different causes
+
+## Pattern Recognition
+
+The memory system automatically extracts patterns when 3+ similar incidents exist. Patterns represent reusable solutions with higher reliability than individual incidents.
+
+When a pattern matches:
+- Trust the solution template (90%+ confidence)
+- Apply the recommended approach
+- Note any caveats mentioned
+
+## Extended capability — global-scope memory + cross-domain assessors
+
+If project-local memory misses but cross-project memory might have a hit, re-call this skill with broader scope, or escalate to the assess skill for additional domain assessor coverage:
+
+```
+Skill("build-loop:debugging-memory") with input { symptom, scope: "global", calledBy: "debugging-memory" }
+Skill("build-loop:debugging-assess") with input { symptom, scope: "global" }
+```
+
+Both are native build-loop skills. They search local `.build-loop/issues/` first and may use standalone Coding Debugger only when that plugin is installed and the caller explicitly requests cross-project memory.
+
+Use this for:
+- A `NO_MATCH` from project memory where cross-project history might still have a relevant incident
+- An ambiguous verdict where additional assessor input would change the routing decision
+- Coordination state that lives outside the current project and was explicitly requested
+
+Do NOT use this for: every memory call (it's escalation, not primary path), or when project memory already returned `KNOWN_FIX` (bundled is enough).
+
+## Native Memory Quick Reference
+
+| Surface | Purpose |
+|------|---------|
+| `build-loop:debugging-memory-search` | Search memory for similar bugs (returns verdict when available) |
+| `build-loop:debugging-store` | Store a new debugging incident |
+| `.build-loop/issues/<id>.md` | Full incident or pattern detail |
+| `.build-loop/issues/` | Recent incidents and local memory corpus |
+| `build-loop:debugging-assess` | Parallel domain assessment |
+
+## Parallel Domain Assessment
+
+For complex issues that may span multiple areas (database, frontend, API, performance), use parallel assessment to diagnose all domains simultaneously.
+
+### When to Use Parallel Assessment
+
+- 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 issues affecting multiple layers
+
+### Domain Assessors
+
+Four specialized assessor agents are available:
+
+| Assessor | Expertise |
+|----------|-----------|
+| `database-assessor` | Prisma, PostgreSQL, queries, 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, optimization |
+
+### Parallel Execution
+
+Launch assessors **in parallel** using the Task tool:
+
+```
+For: "search is slow and returns wrong results"
+
+Launch simultaneously:
+- database-assessor (query performance)
+- api-assessor (endpoint correctness)
+- performance-assessor (latency analysis)
+```
+
+Each assessor returns a JSON assessment with:
+- `confidence`: 0-1 score
+- `probable_causes`: List of likely issues
+- `recommended_actions`: Steps to fix
+- `related_incidents`: Past memory matches
+
+### Domain Detection 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 |
+
+### Result Aggregation
+
+After parallel assessments complete:
+1. Rank by confidence score (highest first)
+2. Consider evidence count (more related incidents = higher priority)
+3. Generate priority ranking of recommended actions
+4. Present unified diagnosis with action sequence
+
+## Trace Integration
+
+The debugger can ingest traces from multiple sources to aid diagnosis:
+
+### Supported Trace Sources
+
+- **OpenTelemetry (OTLP)**: Distributed tracing spans
+- **Sentry**: Error events and breadcrumbs
+- **Langchain/LangSmith**: LLM operation traces
+- **Browser**: Chrome DevTools, Playwright, console logs
+
+### Using Traces for Debugging
+
+When traces are available:
+1. Correlate error traces with symptoms
+2. Review performance spans for latency issues
+3. Check LLM traces for AI-related bugs
+4. Examine browser console for frontend errors
+
+Traces are summarized to minimize token usage while preserving key diagnostic information.
+
+## Token-Efficient Retrieval
+
+The memory system uses tiered retrieval to minimize context size:
+
+### Retrieval Tiers
+
+| Tier | Token Usage | Content |
+|------|-------------|---------|
+| Summary | ~100 tokens | ID, symptom preview, category |
+| Compact | ~200 tokens | Short keys, essential fields |
+| Full | ~550 tokens | Complete incident details |
+
+### Automatic Token Budgeting
+
+Default budget: 2500 tokens
+- Patterns: 30% (750 tokens)
+- Incidents: 60% (1500 tokens)
+- Metadata: 10% (250 tokens)
+
+The system automatically selects the appropriate tier based on available budget.
+
+## Subagent Integration
+
+When debugging involves subagents (your own or from other plugins), follow these guidelines to ensure debugging memory is utilized.
+
+### Automatic Behavior
+
+**Before spawning debugging-related subagents:**
+1. Search debugging memory first using `build-loop:debugging-memory-search`
+2. Pass relevant context to the subagent in its prompt
+3. Include any matching incidents or patterns found
+
+**Example subagent prompt with debugging context:**
+```
+Investigate the database timeout issue.
+
+DEBUGGING MEMORY CONTEXT:
+- Found 2 similar incidents: INC_20241215_db_timeout, INC_20241201_pool_exhaust
+- Pattern PTN_connection_pool suggests checking pool size and idle timeout
+- Previous fix: Increased pool size from 10 to 25 in DATABASE_URL
+
+Start your investigation considering this prior knowledge.
+```
+
+### When Subagents Cannot Access Debugging Memory
+
+**Inform the user** when debugging memory cannot be used with subagents:
+
+1. **External MCP tools**: "Note: The debugging subagent is using external MCP tools that cannot access local debugging memory. I searched memory beforehand and found [X matching incidents / no matches]."
+
+2. **Third-party agents**: "Note: This third-party debugging agent doesn't have access to your project's debugging memory. Consider searching debugging memory first to check for similar past issues."
+
+3. **Sandboxed environments**: "Note: The subagent runs in a sandboxed environment without access to debugging memory. I've pre-loaded relevant context from [X] matching incidents."
+
+### Coordinating Multiple Debugging Subagents
+
+When using parallel assessment or multiple debugging subagents:
+
+1. **Pre-query memory once** using `build-loop:debugging-memory-search` before spawning agents
+2. **Distribute context** - each agent gets relevant subset
+3. **Aggregate findings** - collect new insights from all agents
+4. **Store unified incident** - write a native `.build-loop/issues/*.md` note to document the combined diagnosis
+
+## Best Practices
+
+1. **Always check memory first** - Search local `.build-loop/issues/` before investigating any bug
+2. **Document every fix** - Write a `.build-loop/issues/*.md` note after resolving bugs
+3. **Use descriptive symptoms** - Better matching requires good descriptions
+4. **Include verification status** - Helps prioritize trusted solutions
+5. **Record outcomes** - Use standalone Coding Debugger outcomes only when that optional plugin supplied the prior incident
+6. **Pass context to subagents** - Don't let debugging knowledge stay siloed
+7. **Inform users of limitations** - Be transparent when memory can't be accessed

package/skills/debugging-memory/examples/incident-example.json

@@ -0,0 +1,67 @@
+{
+  "incident_id": "INC_20241225_143052_abc1",
+  "timestamp": 1735135852000,
+  "session_id": "SESSION_1735135800000_xyz",
+
+  "symptom": "Search results not displaying after typing in the search box. The input field accepts keystrokes but the results list remains empty.",
+  "symptom_type": "ui",
+
+  "root_cause": {
+    "description": "The debounce hook was resetting the search query on every keystroke because the dependency array included a reference-unstable callback. Each render created a new callback reference, triggering the debounce reset. This caused the debounced value to never settle, so the API call was never made.",
+    "file": "src/hooks/useDebounce.ts",
+    "line_range": [15, 28],
+    "code_snippet": "const debouncedValue = useMemo(() => {\n  const handler = setTimeout(() => setValue(value), delay);\n  return () => clearTimeout(handler);\n}, [value, callback]); // callback was unstable",
+    "category": "react-hooks",
+    "confidence": 0.95
+  },
+
+  "fix": {
+    "approach": "Wrapped the search callback in useCallback with appropriate dependencies to stabilize the reference. Updated the debounce hook to only depend on the memoized callback. This allowed the debounce timer to complete and trigger the API call.",
+    "changes": [
+      {
+        "file": "src/hooks/useDebounce.ts",
+        "lines_changed": 8,
+        "change_type": "modify",
+        "summary": "Removed callback from dependency array, added internal memoization"
+      },
+      {
+        "file": "src/components/SearchBar.tsx",
+        "lines_changed": 5,
+        "change_type": "modify",
+        "summary": "Wrapped onSearch handler in useCallback with stable dependencies"
+      }
+    ],
+    "pattern_used": null,
+    "time_to_fix": 25
+  },
+
+  "verification": {
+    "status": "verified",
+    "regression_tests_passed": true,
+    "user_journey_tested": true,
+    "tests_run": ["search.test.ts", "useDebounce.test.ts"],
+    "success_criteria_met": true
+  },
+
+  "tags": ["react", "hooks", "useMemo", "useCallback", "debounce", "search", "ui"],
+  "files_changed": ["src/hooks/useDebounce.ts", "src/components/SearchBar.tsx"],
+  "agent_used": "coder",
+
+  "quality_gates": {
+    "guardian_validated": true,
+    "tested_e2e": false,
+    "tested_from_ui": true,
+    "security_reviewed": false,
+    "architect_reviewed": false
+  },
+
+  "completeness": {
+    "symptom": true,
+    "root_cause": true,
+    "fix": true,
+    "verification": true,
+    "quality_score": 0.85
+  },
+
+  "quality_score": 0.85
+}