vasily
4fa17b8086
- Add junior-to-senior with research playbook and review rubric - Add fuck-slop with tell catalog and multi-register voice profiles - Add interface-kit with design engineering, motion, and a11y references - Add app-security with 4-pillar upload defense and hardening playbooks - Add debugging-workflow with systematic root cause isolation - Standardize all skills to 5-phase Skill Architect protocol - Sync symlinks to OpenCode, Codex, and Claude Code
80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
---
|
|
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]
|
|
---
|
|
|
|
# Debugging Workflow
|
|
|
|
A systematic, disciplined protocol for finding and fixing software bugs efficiently without guessing or introducing collateral regressions.
|
|
|
|
---
|
|
|
|
## 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.
|