Name: debug
Author: TGabeCar

Prompt file imported from TGabeCar/CandidateRanker (.cursor/commands/debug.md). Copyright stays with the author.

debug

Systematically diagnose and fix a bug or unexpected behavior. Follow a structured approach instead of guessing — this prevents the common AI agent failure mode of trying random things that compound the problem.

Debugging Process

Step 1: Understand the Problem

Before changing any code:

What is the expected behavior? (Reference PRD.md or TASKS.md for the correct specification)
What is the actual behavior? (Exact error message, unexpected output, or incorrect state)
When does it happen? (Always? Sometimes? Under specific conditions?)
What changed recently? (New code, dependency update, configuration change?)

Step 2: Gather Evidence

Collect concrete evidence before forming hypotheses:

Read the exact error message and stack trace
Check application logs (search by correlation ID if available)
Check the relevant test results — are tests failing? Which ones?
Reproduce the issue with a minimal test case if possible

Step 3: Form a Hypothesis

Based on the evidence:

Most likely cause: [What the evidence points to]
Supporting evidence: [What specifically suggests this cause]
What to check: [How to confirm or disprove this hypothesis]

Do NOT start changing code yet. Verify the hypothesis first.

Step 4: Verify the Hypothesis

Test the hypothesis without modifying production code:

Add a focused test case that reproduces the bug
Add temporary debug logging (clearly marked for removal)
Check documentation: does the API/library actually work the way we assumed? (Verify against @Docs)
Check version compatibility: is this a known issue with the specific version we're using?

Step 5: Implement the Fix

Once the root cause is confirmed:

Make the minimal change that fixes the issue
Don't refactor unrelated code in the same fix
Ensure the fix addresses the root cause, not just the symptom
Verify the fix doesn't break existing tests

Step 6: Verify the Fix

The reproduction test case now passes
All existing tests still pass
The original reported behavior is fixed
No new issues introduced (check related functionality)
Remove any temporary debug logging

Step 7: Document the Fix

Explain the root cause (not just "changed X to Y", but WHY)
Note if documentation needs updating
Suggest a commit message

Anti-Patterns to Avoid

Shotgun debugging: Changing multiple things at once hoping something works. Change ONE thing, verify, then proceed.
Hypothesizing without evidence: "Maybe it's X" without checking. Always look at the actual error first.
Fixing symptoms: Adding a try/catch around a crash instead of fixing why it crashes.
Scope creep: Refactoring or improving unrelated code while debugging. Fix the bug, commit, then improve separately.
Ignoring tests: If tests pass but the bug exists, the tests are incomplete. Add the missing test first.
Overwriting state: Adding workarounds that mask the underlying issue.

Output Format

Debug Report

Problem

Expected: [behavior]
Actual: [behavior]
Reproducible: [Always / Sometimes / Specific conditions]

Evidence Gathered

Error: [exact message and stack trace]
Logs: [relevant log entries]
Related tests: [which tests pass/fail]

Root Cause

[Explanation of WHY the bug occurs — not just what's wrong, but the chain of events]

Fix Applied

File(s) changed: [list]
Change description: [what was changed and why this fixes the root cause]
Minimal change: [confirmation this is the smallest fix that addresses the issue]

Verification

Reproduction test case added and passes
All existing tests still pass
Original behavior is corrected
No regressions in related functionality
Temporary debug logging removed

Commit Message

fix(scope): [description of what was fixed]

Root cause: [brief explanation]

Follow-up

[Any documentation that needs updating]
[Any related issues that should be investigated]
[Any tests that should be added beyond the reproduction case]

Install debug and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# debug Systematically diagnose and fix a bug or unexpected behavior. Follow a structured approach instead of guessing — this prevents the common AI agent failure mode of trying random things that compound the problem. ## Debugging Process ### Step 1: Understand the Problem Before changing any code: - **What is the expected behavior?** (Reference PRD.md or TASKS.md for the correct specification) - **What is the actual behavior?** (Exact error message, unexpected output, or incorrect state) - **When does it happen?** (Always? Sometimes? Under specific conditions?) - **What changed recently?** (New code, dependency update, configuration change?) ### Step 2: Gather Evidence Collect concrete evidence before forming hypotheses: - Read the exact error message and stack trace - Check application logs (search by correlation ID if available) - Check the relevant test results — are tests failing? Which ones? - Reproduce the issue with a minimal test case if possible ### Step 3: Form a Hypothesis Based on the evidence: - **Most likely cause**: [What the evidence points to] - **Supporting evidence**: [What specifically suggests this cause] - **What to check**: [How to confirm or disprove this hypothesis] Do NOT start changing code yet. Verify the hypothesis first. ### Step 4: Verify the Hypothesis Test the hypothesis without modifying production code: - Add a focused test case that reproduces the bug - Add temporary debug logging (clearly marked for removal) - Check documentation: does the API/library actually work the way we assumed? (Verify against @Docs) - Check version compatibility: is this a known issue with the specific version we're using? ### Step 5: Implement the Fix Once the root cause is confirmed: - Make the minimal change that fixes the issue - Don't refactor unrelated code in the same fix - Ensure the fix addresses the root cause, not just the symptom - Verify the fix doesn't break existing tests ### Step 6: Verify the Fix - The reproduction test case now passes - All existing tests still pass - The original reported behavior is fixed - No new issues introduced (check related functionality) - Remove any temporary debug logging ### Step 7: Document the Fix - Explain the root cause (not just "changed X to Y", but WHY) - Note if documentation needs updating - Suggest a commit message ## Anti-Patterns to Avoid - **Shotgun debugging**: Changing multiple things at once hoping something works. Change ONE thing, verify, then proceed. - **Hypothesizing without evidence**: "Maybe it's X" without checking. Always look at the actual error first. - **Fixing symptoms**: Adding a try/catch around a crash instead of fixing why it crashes. - **Scope creep**: Refactoring or improving unrelated code while debugging. Fix the bug, commit, then improve separately. - **Ignoring tests**: If tests pass but the bug exists, the tests are incomplete. Add the missing test first. - **Overwriting state**: Adding workarounds that mask the underlying issue. ## Output Format ## Debug Report ### Problem - **Expected**: [behavior] - **Actual**: [behavior] - **Reproducible**: [Always / Sometimes / Specific conditions] ### Evidence Gathered - **Error**: [exact message and stack trace] - **Logs**: [relevant log entries] - **Related tests**: [which tests pass/fail] ### Root Cause [Explanation of WHY the bug occurs — not just what's wrong, but the chain of events] ### Fix Applied - **File(s) changed**: [list] - **Change description**: [what was changed and why this fixes the root cause] - **Minimal change**: [confirmation this is the smallest fix that addresses the issue] ### Verification - [ ] Reproduction test case added and passes - [ ] All existing tests still pass - [ ] Original behavior is corrected - [ ] No regressions in related functionality - [ ] Temporary debug logging removed ### Commit Message ``` fix(scope): [description of what was fixed] Root cause: [brief explanation] ``` ### Follow-up - [Any documentation that needs updating] - [Any related issues that should be investigated] - [Any tests that should be added beyond the reproduction case]

{ "prompt": "# debug\n\nSystematically diagnose and fix a bug or unexpected behavior. Follow a structured approach instead of guessing — this prevents the common AI agent failure mode of trying random things that compound the problem.\n\n## Debugging Process\n\n### Step 1: Understand the Problem\nBefore changing any code:\n- **What is the expected behavior?** (Reference PRD.md or TASKS.md for the correct specification)\n- **What is the actual behavior?** (Exact error message, unexpected output, or incorrect state)\n- **When does it happen?** (Always? Sometimes? Under specific conditions?)\n- **What changed recently?** (New code, dependency update, configuration change?)\n\n### Step 2: Gather Evidence\nCollect concrete evidence before forming hypotheses:\n- Read the exact error message and stack trace\n- Check application logs (search by correlation ID if available)\n- Check the relevant test results — are tests failing? Which ones?\n- Reproduce the issue with a minimal test case if possible\n\n### Step 3: Form a Hypothesis\nBased on the evidence:\n- **Most likely cause**: [What the evidence points to]\n- **Supporting evidence**: [What specifically suggests this cause]\n- **What to check**: [How to confirm or disprove this hypothesis]\n\nDo NOT start changing code yet. Verify the hypothesis first.\n\n### Step 4: Verify the Hypothesis\nTest the hypothesis without modifying production code:\n- Add a focused test case that reproduces the bug\n- Add temporary debug logging (clearly marked for removal)\n- Check documentation: does the API/library actually work the way we assumed? (Verify against @Docs)\n- Check version compatibility: is this a known issue with the specific version we're using?\n\n### Step 5: Implement the Fix\nOnce the root cause is confirmed:\n- Make the minimal change that fixes the issue\n- Don't refactor unrelated code in the same fix\n- Ensure the fix addresses the root cause, not just the symptom\n- Verify the fix doesn't break existing tests\n\n### Step 6: Verify the Fix\n- The reproduction test case now passes\n- All existing tests still pass\n- The original reported behavior is fixed\n- No new issues introduced (check related functionality)\n- Remove any temporary debug logging\n\n### Step 7: Document the Fix\n- Explain the root cause (not just \"changed X to Y\", but WHY)\n- Note if documentation needs updating\n- Suggest a commit message\n\n## Anti-Patterns to Avoid\n\n- **Shotgun debugging**: Changing multiple things at once hoping something works. Change ONE thing, verify, then proceed.\n- **Hypothesizing without evidence**: \"Maybe it's X\" without checking. Always look at the actual error first.\n- **Fixing symptoms**: Adding a try/catch around a crash instead of fixing why it crashes.\n- **Scope creep**: Refactoring or improving unrelated code while debugging. Fix the bug, commit, then improve separately.\n- **Ignoring tests**: If tests pass but the bug exists, the tests are incomplete. Add the missing test first.\n- **Overwriting state**: Adding workarounds that mask the underlying issue.\n\n## Output Format\n\n## Debug Report\n\n### Problem\n- **Expected**: [behavior]\n- **Actual**: [behavior]\n- **Reproducible**: [Always / Sometimes / Specific conditions]\n\n### Evidence Gathered\n- **Error**: [exact message and stack trace]\n- **Logs**: [relevant log entries]\n- **Related tests**: [which tests pass/fail]\n\n### Root Cause\n[Explanation of WHY the bug occurs — not just what's wrong, but the chain of events]\n\n### Fix Applied\n- **File(s) changed**: [list]\n- **Change description**: [what was changed and why this fixes the root cause]\n- **Minimal change**: [confirmation this is the smallest fix that addresses the issue]\n\n### Verification\n- [ ] Reproduction test case added and passes\n- [ ] All existing tests still pass\n- [ ] Original behavior is corrected\n- [ ] No regressions in related functionality\n- [ ] Temporary debug logging removed\n\n### Commit Message\n```\nfix(scope): [description of what was fixed]\n\nRoot cause: [brief explanation]\n```\n\n### Follow-up\n- [Any documentation that needs updating]\n- [Any related issues that should be investigated]\n- [Any tests that should be added beyond the reproduction case]", "variables": [], "notes": "Systematically diagnose and fix a bug or unexpected behavior. Follow a structured approach instead of guessing — this prevents the common AI agent failure mode of trying random things that compound the problem.", "metadata": { "source": { "provider": "github-cursor-commands", "repository": "https://github.com/TGabeCar/CandidateRanker", "path": ".cursor/commands/debug.md", "ref": "7a6f94c35935f280ee5056db466e72b55decdf10", "url": "https://github.com/TGabeCar/CandidateRanker/blob/7a6f94c35935f280ee5056db466e72b55decdf10/.cursor/commands/debug.md", "key": "TGabeCar/CandidateRanker/.cursor/commands/debug.md" } } }

debug

About

debug

Debugging Process

Step 1: Understand the Problem

Step 2: Gather Evidence

Step 3: Form a Hypothesis

Step 4: Verify the Hypothesis

Step 5: Implement the Fix

Step 6: Verify the Fix

Step 7: Document the Fix

Anti-Patterns to Avoid

Output Format

Debug Report

Problem

Evidence Gathered

Root Cause

Fix Applied

Verification

Commit Message

Follow-up

Install debug and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews