cf-sys-debug

Context footprint: ⚡⚡ (medium) — what does this mean?

The cf-sys-debug skill activates when you're debugging issues. It guides you through a structured 4-phase process (Root Cause Investigation, Pattern Analysis, Hypothesis Testing, Implementation) followed by mandatory bug documentation.

When It Activates

Automatically triggered when:

• Code is failing or behaving unexpectedly
• Tracking down a bug or error
• Investigating performance issues
• Debugging test failures
• Escalated from /cf-fix after 3 failed attempts

The 3-Fix Rule

If you've attempted 3+ fixes and the bug persists, stop. The problem is architectural, not local. Step back and re-examine your assumptions.

4-Phase Process + Documentation

Phase 1: Root Cause Investigation

1a. Check existing bug docs (frontmatter recall):

Before investigating, search for related past bugs. Extract 2-3 keywords from the bug description.

1. Grep description: lines across docs/memory/bugs/ -- match against bug keywords
2. If no match, grep tags: lines
3. If matches found, read the top 1-2 matched files -- they may reveal known root causes or patterns that save investigation time

1b. Investigate:

1. Read the actual error. Do not guess. Read the full stack trace, error message, and logs.
2. Reproduce the bug. Write a test or command that triggers the failure reliably.
3. Trace backward. Follow the call chain from the error to its origin. The bug is usually NOT where the error appears.

Phase 2: Pattern Analysis

1. When did it start? Check recent changes: git log --oneline -20, git diff HEAD~5
2. Is it consistent? Does it fail every time, or intermittently? Intermittent = timing/state issue.
3. What's the minimal reproduction? Strip away everything unrelated until you have the smallest case.

Phase 3: Hypothesis Testing

1. Form one hypothesis. "The bug is caused by X because Y."
2. Design a test. What observation would confirm or disprove this hypothesis?
3. Test it. Run the test. Read the output carefully.
4. If disproved, go back to Phase 1 with new information. Do NOT patch around it.

Phase 4: Implementation

1. Fix the root cause, not the symptom
2. Write a regression test that would have caught this bug
3. Run the full test suite -- your fix must not break anything else
4. Verify the original error is gone -- reproduce the original failure and confirm it's fixed

Phase 5: Document the Bug

Since cf-sys-debug only handles hard bugs, it always documents findings to docs/memory/bugs/ via the cf-writer agent. Each bug doc includes:

• Overview -- Symptom and why it was hard to diagnose
• Investigation -- What was tried and ruled out
• Root Cause -- The actual underlying issue
• Fix -- What was changed
• Prevention -- How to avoid recurrence

Documents include YAML frontmatter (title, description, tags) for efficient future recall by /cf-fix and cf-sys-debug itself.

Common Traps

Trap	Why It Fails	Do This Instead
"Let me just try this..."	Random fixes waste time and obscure the real cause	Form a hypothesis first
Adding a try/catch to suppress the error	Hides the bug, doesn't fix it	Find and fix the root cause
"It works on my machine"	Environment difference IS the bug	Compare environments systematically
Fixing where the error appears	Symptom vs cause confusion	Trace backward to the origin
Multiple changes at once	Can't tell which one fixed it	One change at a time, test after each

Key Principles

• Collect Data -- Use logs, errors, and tests, not guesses
• Isolate -- Find the narrowest failing case
• Reproduce -- Make failure consistent and repeatable
• Question Assumptions -- Your first guess is often wrong
• Automate -- Convert manual debugging to automated tests
• Document -- Capture findings so future bugs benefit from past work

Debugging Tools

• git bisect -- Find the exact commit that introduced a bug
• git stash -- Isolate your changes to test clean state
• Print/log tracing -- Add strategic logging at decision points
• Minimal reproduction -- Smallest possible code that triggers the bug