feat: refresh shared skills catalog
This commit is contained in:
vasily committed
1 parent
98bb35e6fb
commit
418792d1ec
49 files changed
+2273
-2390
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user