changes

.config/opencode/skills/systematic-debugging/SKILL.md

@@ -1,92 +1,36 @@
 ---
 name: systematic-debugging
-description: Use when encountering bugs, test failures, or unexpected behavior before proposing fixes
+description: Diagnose failures with a hypothesis-first workflow, evidence capture, and escalation rules aligned to planner/builder
 permalink: opencode-config/skills/systematic-debugging/skill
 ---
 
 # Systematic Debugging
 
-## Overview
+Use this skill when tests fail, behavior regresses, or the root cause is unclear.
 
-Random fix attempts create churn and often introduce new issues.
+## Workflow
 
-**Core principle:** always identify root cause before attempting fixes.
+1. Define the failure precisely (expected vs actual, where observed, reproducible command).
+2. Capture a baseline with the smallest reliable repro.
+3. List 1-3 concrete hypotheses and rank by likelihood.
+4. Test one hypothesis at a time with targeted evidence collection.
+5. Isolate the minimal root cause before proposing fixes.
+6. Verify the fix with focused checks, then relevant regression checks.
 
-## The Iron Law
+## Evidence Requirements
 
-```
-NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
-```
+- Record failing and passing commands.
+- Keep key logs/errors tied to each hypothesis.
+- Note why rejected hypotheses were ruled out.
 
-If Phase 1 is incomplete, do not propose or implement fixes.
+## Planner/Builder Alignment
 
-## When to Use
+- Planner: use findings to shape bounded implementation tasks and verification oracles.
+- Builder: if contradictions or hidden dependencies emerge, escalate back to planner.
+- After two failed verification attempts, stop, record root cause evidence, and escalate.
 
-Use for any technical issue:
-- Test failures
-- Unexpected runtime behavior
-- Build or CI failures
-- Integration breakages
-- Performance regressions
+## Output
 
-Use this especially when:
-- You are under time pressure
-- A "quick patch" seems obvious
-- Previous fix attempts did not work
-- You do not yet understand why the issue occurs
-
-## Four-Phase Process
-
-Complete each phase in order.
-
-### Phase 1: Root-Cause Investigation
-
-1. Read error messages and stack traces fully.
-2. Reproduce the issue reliably with exact steps.
-3. Check recent changes (code, config, dependency, environment).
-4. Gather evidence at component boundaries (inputs, outputs, config propagation).
-5. Trace data flow backward to the original trigger.
-
-For deeper tracing techniques, see `root-cause-tracing.md`.
-
-### Phase 2: Pattern Analysis
-
-1. Find similar working code in the same repository.
-2. Compare broken and working paths line by line.
-3. List all differences, including small ones.
-4. Identify required dependencies and assumptions.
-
-### Phase 3: Hypothesis and Minimal Testing
-
-1. State one concrete hypothesis: "X is failing because Y".
-2. Make the smallest possible change to test only that hypothesis.
-3. Verify result before making any additional changes.
-4. If the test fails, form a new hypothesis from new evidence.
-
-### Phase 4: Fix and Verify
-
-1. Create a minimal failing reproduction (automated test when possible).
-2. Implement one fix targeting the identified root cause.
-3. Verify the issue is resolved and no regressions were introduced.
-4. If fix attempts keep failing, stop and reassess design assumptions.
-
-## Red Flags (Stop and Restart at Phase 1)
-
-- "Let me try this quick fix first"
-- "I’ll batch several changes and see what works"
-- "It probably is X"
-- Proposing solutions before tracing the data flow
-- Continuing repeated fix attempts without new evidence
-
-## Supporting Techniques
-
-Use these companion references while executing this process:
-
-- `root-cause-tracing.md` — trace failures backward through the call chain
-- `condition-based-waiting.md` — replace arbitrary sleeps with condition polling
-- `defense-in-depth.md` — add layered validation so recurrence is harder
-
-## Related Skills
-
-- `test-driven-development` — build minimal failing tests and iterate safely
-- `verification-before-completion` — confirm behavior end-to-end before claiming done
+- Root cause statement.
+- Fix strategy linked to evidence.
+- Verification results proving the issue is resolved and not regressed.