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
3.4 KiB
3.4 KiB
name, description, concerns
| name | description | concerns | |
|---|---|---|---|
| debugging-workflow | 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. |
|
Debugging Workflow
A systematic, disciplined protocol for finding and fixing software bugs efficiently without guessing or introducing collateral regressions.
Phase 0: Setup and Protocols
- 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
- 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.
- 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..HEADor 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/catchor 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:
- Root Cause: Crisp explanation of why the failure occurred.
- Surgical Diff: The exact code changes applied.
- Verification: Command executed or test output demonstrating the fix.
- Prevention: Regression test added to guard against recurrence.