From 861bab677b4632e9d30e6318bc2a35c36ee77105 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 29 Mar 2026 16:25:05 -0500 Subject: Add general-purpose skills and rules from DeepSat coding-rulesets Skills (adapted from DeepSat, stripped of project-specific references): - /review-pr: PR review against engineering standards - /fix-issue: issue-to-merge TDD workflow - /security-check: secrets, OWASP, and dependency audit - /debug: systematic 4-phase debugging - /add-tests: test coverage analysis and generation - /respond-to-review: evaluate and implement code review feedback Rules (general-purpose, copied as-is): - testing.md: universal TDD standards and anti-patterns - verification.md: proof over assumption Makefile updated to install both skills and rules via symlinks. Co-Authored-By: Claude Opus 4.6 (1M context) --- debug/SKILL.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 debug/SKILL.md (limited to 'debug') diff --git a/debug/SKILL.md b/debug/SKILL.md new file mode 100644 index 0000000..e4e1041 --- /dev/null +++ b/debug/SKILL.md @@ -0,0 +1,55 @@ +# /debug — Systematic Debugging + +Investigate a bug or test failure methodically. No guessing, no shotgun fixes. + +## Usage + +``` +/debug [description of the problem] +``` + +If no description is given, prompt the user to describe the symptom. + +## Instructions + +Work through four phases in order. Do not skip to a fix. + +### Phase 1: Understand the Symptom + +1. **Reproduce the failure** — run the failing test or trigger the bug. Capture the exact error message, stack trace, or incorrect output. If you can't reproduce it, say so — don't guess. +2. **Check logs and observability** — review application logs, error tracking, and metrics around the time of failure. For deployed services, check structured logs, APM traces, and alerting dashboards. Logs often reveal context that code reading alone cannot. +3. **Locate the failure point** — identify the exact file and line where the error occurs. Read the surrounding code. Understand what the code is trying to do, not just where it fails. +4. **Trace the data flow** — follow the inputs from their origin to the failure point. Read callers, callees, models, serializers, and middleware in the path. Understand how the data got into the state that caused the failure. + +Do not propose any fix during this phase. You are gathering evidence. + +### Phase 2: Identify the Root Cause + +5. **Ask "why?" at least three times** — if a value is wrong in a view, why? Because the service returned bad data. Why? Because the model query missed a filter. Why? Because the migration didn't add the index. That's the root cause. +6. **Check for related symptoms** — search for similar patterns elsewhere in the codebase. If the bug is in one endpoint, check sibling endpoints for the same mistake. Bugs often travel in packs. +7. **Form a hypothesis** — state the root cause clearly: "The bug is caused by [X] in [file:line] because [reason]." If you have multiple hypotheses, rank them by likelihood. + +### Phase 3: Verify the Hypothesis + +8. **Write a failing test** that proves your hypothesis — the test should fail for the reason you identified, not just any reason. If the test passes, your hypothesis is wrong. Go back to Phase 2. +9. **Confirm the test fails for the right reason** — read the failure output. Does it match your hypothesis? A test that fails for a different reason than expected is not evidence. + +### Phase 4: Fix and Verify + +10. **Write the minimal fix** — change only what is necessary to address the root cause. Do not refactor, clean up, or improve adjacent code. +11. **Run the failing test** — confirm it passes. +12. **Add boundary and error case tests** — cover edge cases around the fix. +13. **Run the full test suite** — confirm no regressions. +14. **Commit** following conventional commit format. + +## Escalation Rule + +If you've attempted 3 fixes and the bug persists, stop. The problem is likely architectural, not local. Report what you've learned and recommend a broader investigation rather than attempting fix #4. + +## What Not to Do + +- Don't propose fixes before completing Phase 2 +- Don't change multiple things at once — isolate variables +- Don't suppress errors or add try/catch to hide symptoms +- Don't add logging as a fix (logging is a diagnostic, not a solution) +- Don't delete or skip a failing test to "fix" the suite -- cgit v1.2.3