feat: refresh shared skills catalog

2026-10-30 12:40:16 +08:00
1 parent 98bb35e6fb
commit 418792d1ec
@@ -1,79 +1,21 @@
 ---
 name: debugging-workflow
 description: >
-  Systematic, hypothesis-driven debugging workflow: reproduction, isolation, root cause identification,
-  surgical fixes, and regression prevention. Use when diagnosing bugs, unexpected runtime errors,
-  failing tests, or when asked to debug an issue.
-concerns: [system-one-balance]
+  Diagnose and fix unexpected behavior, runtime errors, or failing checks when asked to debug or repair an issue.
+scope: global
 ---

-# Debugging Workflow
+# Debugging

-A systematic, disciplined protocol for finding and fixing software bugs efficiently without guessing or introducing collateral regressions.
+1. Establish expected versus actual behavior from existing errors, logs, and code.
+   Build a small reproduction when useful; do not ask for information already given.
+2. Rank plausible causes and choose a focused probe that distinguishes them.
+   Inspect boundary inputs, recent relevant diffs, or execution state as needed.
+3. Fix the demonstrated cause with a small change. Stop blind retry loops and
+   avoid broad refactoring while resolving a bug.
+4. Add regression coverage for meaningful behavioral failures when practical.
+   Use [shared verification](../../protocols/workflow.md#verification) to choose checks.
+5. Report the cause, changed behavior, evidence, and any remaining uncertainty.

---
-
-## Phase 0: Setup and Protocols
-
-1. Invariants:
-   - Never apply random fixes hoping one works. Every fix must be preceded by an identified root cause.
-   - Prefer minimal surgical edits over wide refactors during bug resolution.
-   - Every resolved bug should ideally be pinned with a reproduction test.
-
---
-
-## Phase 1: Ingest and Check
-
-1. **Information Gathering**:
-   - Inspect the verbatim error message, stack trace, and relevant log streams.
-   - Identify the exact file and line where failure manifests.
-   - Record the expected vs. actual behavior and environmental conditions.
-2. **Reproduction & Isolation**:
-   - Determine whether the bug is reliably reproducible.
-   - Construct a minimal reproduction case or failing test.
-   - Identify recent changes: review `git diff HEAD~5..HEAD` or recent commits if the issue is a regression.
-
---
-
-## Phase 2: Processing (Core Logic)
-
-### Step 1: Formulate and Rank Hypotheses
-Classify the issue into primary failure categories:
- **Logic Errors**: Off-by-one, inversion of boolean operators, missing edge cases.
- **Data Errors**: Null/undefined references, schema divergence, malformed encodings.
- **State & Concurrency**: Race conditions, stale cache, incomplete state mutation.
- **Integration Errors**: API contract drift, network timeouts, environment configuration.
-
-Formulate the most probable hypothesis and design a quick diagnostic probe to validate or falsify it.
-
-### Step 2: Diagnostic Probing
- Add focused diagnostic logging or evaluate intermediate states.
- Use binary search / bisection when isolating faults in large code paths.
- Check assumptions at subsystem boundaries: inspect inputs immediately before and outputs immediately after the failure site.
-
-### Step 3: Implement Minimal Surgical Fix
- Address the underlying defect rather than masking the symptom (e.g. don't simply wrap with a silent `try/catch` or null check if an invariant was violated upstream).
- Keep changes minimal and localized to the responsible subsystem.
-
-### Step 4: Regression Defense
- Execute test suites to confirm no existing functionality broke.
- Add or update an automated unit/integration test capturing the failure condition.
-
---
-
-## Phase 3: The System One Balance Pass
-
- **Augment, Don't Handcuff**:
-  - If full stack trace and error context are already visible in the conversation, do NOT ask the user redundant intake questions ("Can you provide the logs?"). Proceed directly to diagnosis.
-  - Do NOT rewrite unrelated modules or refactor working code while fixing a bug.
-  - Fix fast; reserve deep architectural audits for dedicated refactoring passes.
-
---
-
-## Phase 4: Output Execution & Verification
-
-Deliver the debugging report with:
-1. **Root Cause**: Crisp explanation of why the failure occurred.
-2. **Surgical Diff**: The exact code changes applied.
-3. **Verification**: Command executed or test output demonstrating the fix.
-4. **Prevention**: Regression test added to guard against recurrence.
+Use `backprop` only when an existing spec needs a bug record or invariant update.
+No spec creation, mandatory full suite, or separate review is required for a routine fix.