Debug Probe

intent

use this skill when a bug resists static analysis and you need runtime evidence to pinpoint root cause. the six-phase hypothesis-driven process (hypothesize → instrument → reproduce → converge → fix → clean up) isolates unexpected behavior through targeted instrumentation, log collection, and iterative refinement. triggers on: debug, diagnose, broken, bug, not working, unexpected behavior, investigate, root cause, probe.

inputs

required context:

• access to source code (git repo, codebase, file system)
• ability to build and deploy (local or CI/CD pipeline)
• user who can reproduce the bug (manual repro or automated test harness)
• log export mechanism (console dump, file write, buffer download, etc.)

external connections:

• version control system (git, svn) - for reverting instrumentation
• build system (make, gradle, npm, python, etc.) - for compilation validation
• deployment target (localhost, staging, prod) - for user verification

environment setup:

• if using diagnostic buffer pattern from TEMPLATES.md, ensure language-specific logging library is available (console for js, logging for python, etc.)
• no special auth required; instrumentation is local code changes

procedure

phase 1: hypothesize

1. read source code relevant to reported bug (stack trace, affected module, recent changes)
   • input: bug description, error message if available, user reproduction steps
   • output: 2-4 falsifiable hypotheses in format [H1] root cause may be X → if true, log would show Y
2. share hypotheses with user before modifying code
   • input: hypothesis list
   • output: user acknowledgment or additional context

phase 2: instrument

3. for each hypothesis, identify 2-4 code locations that will confirm or refute it
   • input: hypotheses from phase 1
   • output: list of line numbers and variables to log
4. insert minimal logging statements tagged [DIAG_<topic>] (topic examples: auth, render, state, network, cache)
   • input: line numbers and variables
   • output: instrumented source code with markers like // DIAG: remove after debug (adapt syntax to language)
5. use diagnostic buffer function (e.g. diagLog('H1', 'key=val', ...)) that writes to both console and in-memory buffer for export
   • input: hypothesis label, key-value pairs
   • output: log entries tagged with hypothesis and topic
6. commit instrumented code or tag it clearly for rollback
   • input: modified source files
   • output: saved checkpoint (git stash, branch, backup)

phase 3: collect

7. build the application (npm run build, make, gradle build, python setup.py, etc.)
   • input: instrumented source code
   • output: compiled/packaged artifact
   • error handling: if build fails, fix compilation errors and retry; instrumentation syntax errors are common
8. deploy to testing environment (localhost, staging, or temporary instance)
   • input: compiled artifact
   • output: running service/app
9. user reproduces the bug using provided steps or automated test
   • input: deployment target, repro steps
   • output: bug observed, logs generated
10. user exports logs (dump buffer to file, copy console output, curl log endpoint, etc.)
    • input: running service with diagnostic buffer
    • output: plain-text log file or console capture
11. group exported logs by hypothesis tag ([DIAG][H1], [DIAG][H2], etc.) and examine execution flow
    • input: exported logs
    • output: annotated log sections, one per hypothesis

phase 4: converge

12. match log evidence to hypotheses:
    • if one hypothesis confirmed (expected log path hit, values match prediction): advance to phase 5
    • if all hypotheses refuted (none of the expected logs appear): extract new clues from logs (unexpected values, missing branches, earlier failure point) and formulate new hypotheses, return to phase 2
    • if data insufficient (logs hit but are ambiguous or incomplete): add more precise instrumentation around the ambiguous section, return to phase 2
    • input: annotated log groups
    • output: confirmed root cause or new hypothesis set
13. enforce iteration limit: max 2-3 phase 2-4 loops before escalating or requesting more user context
    • input: iteration count, evidence quality
    • output: decision to fix, escalate, or refine

phase 5: fix and verify

14. write minimal fix targeting only the confirmed root cause (one-file change if possible, no refactors)
    • input: confirmed root cause hypothesis
    • output: modified source file with fix applied
15. build and deploy fixed code (keep instrumentation in place for now)
    • input: fixed source
    • output: new artifact with instrumentation + fix
16. user verifies fix resolves the bug
    • input: deployed fixed artifact, original repro steps
    • output: user confirmation or observation that fix failed
17. if fix failed: keep key instrumentation that showed root cause, revert fix, return to phase 1 to re-hypothesize
    • input: user feedback, instrumentation logs from phase 3
    • output: new hypothesis set
18. if fix succeeded: proceed to phase 6
    • input: user confirmation
    • output: approval for cleanup

phase 6: clean up

19. search source code for all markers (DIAG: remove after debug, diagLog, [DIAG_ comments, diagnostic imports)
    • input: instrumented source code
    • output: list of all temporary code lines
20. remove all temporary instrumentation code (logging calls, buffer setup, diagnostic branches)
    • input: list of lines to remove
    • output: cleaned source file
21. remove all diagnostic imports or library setup (if diagLog was imported separately)
    • input: import statements
    • output: cleaned imports
22. delete diagnostic buffer file if it exists and is no longer referenced elsewhere
    • input: file path
    • output: confirmation of deletion or skip if file is permanent
23. build cleaned source to confirm no compilation errors
    • input: cleaned source
    • output: successful build artifact
    • error handling: if build fails after cleanup, you removed too much; restore from phase 2 checkpoint and retry
24. confirm with user that instrumentation is removed and only the fix remains
    • input: final artifact
    • output: user acknowledgment

decision points

phase 2 → phase 3: only proceed to collect if you have 2-4 concrete hypotheses and user is ready to reproduce. if context is unclear, ask clarifying questions in phase 1 first.

phase 3 → phase 4: if user cannot reproduce the bug in testing environment, it may be environment-specific (timing, load, data state). ask user to reproduce in their original environment and capture logs there, or provide a more precise repro scenario.

phase 4 (converge branch):

• if logs confirm hypothesis: route to phase 5 fix.
• if all hypotheses refuted: do not guess; extract clues from logs (unexpected values, code paths that ran earlier than expected, missing branch hits) and formulate new hypotheses. return to phase 2 with refined instrumentation.
• if insufficient data: add more precise logging around ambiguous sections (e.g., log variable state before and after a conditional, add timestamps to track timing issues). return to phase 2 with denser instrumentation.
• if 2-3 iterations complete and root cause still unclear: escalate. this indicates the bug is non-deterministic, environment-specific, or requires deeper architectural review.

phase 5 (fix verification branch):

• if fix works: proceed to phase 6 cleanup immediately.
• if fix fails: do not iterate blindly on the fix. keep the key instrumentation that revealed the root cause and go back to phase 1. the hypothesis was wrong or incomplete.

phase 6 cleanup: if build fails after removing instrumentation, you removed code that was not actually temporary. restore the instrumented version from phase 2 checkpoint, identify the actual temporary code more carefully, and retry. do not ship instrumentation to production.

edge cases and rate limits:

• if user cannot export logs (log buffer not accessible, console cleared, file permission denied), provide an alternate capture method (HAR file, network tab screenshot, manual note-taking during repro).
• if instrumentation adds latency and slows down repro (e.g., logging millions of lines), reduce instrumentation density. target 2-4 points per hypothesis, not 20.
• if code path is unreachable during repro (instrumentation code never runs), either the repro steps are incomplete, the bug is in a different code path, or the build is stale. ask user to double-check repro steps and redeploy.
• if logs show timeouts, network errors, or auth failures, these are often side effects, not root causes. trace back to the preceding log line to find the actual failure trigger.

output contract

successful skill execution produces:

1. confirmed root cause statement (plain english, one sentence): "root cause is X, evidenced by logs showing Y"
2. minimal fix commit or patch: single source file with change isolated to root cause logic, marked with clear comment explaining the fix
3. cleaned codebase: all DIAG: comments, diagLog() calls, and diagnostic imports removed; source compiles without error
4. log archive (optional but recommended): exported logs from phase 3 in plain text, grouped by hypothesis, named debug-<timestamp>.log for future reference
5. user acknowledgment: user confirms fix resolves bug in their original environment

file locations:

• cleaned source code: original file paths (no new files created except temporary log exports)
• final artifact: ready for production deployment (instrumentation stripped, fix applied)

outcome signal

you know this skill worked when:

• user confirms the bug no longer occurs in their environment after deploying the cleaned artifact
• the fix is minimal and targeted (not a broad refactor or revert of multiple commits)
• source code compiles and passes build checks after cleanup
• you can explain the root cause in one sentence ("X was null because Y didn't initialize it")
• all DIAG: markers are gone from the codebase
• user can see the fix and understand why it solves the bug, without needing to read instrumentation code

anti-patterns that signal failure:

• you shipped instrumentation code to production (phase 6 was skipped)
• the "fix" is a band-aid that masks the real root cause (e.g., adding a null check instead of fixing initialization)
• you can't explain why the bug happened or why the fix works
• user reports the bug still occurs or reoccurs after a few days
• instrumentation was so dense (50+ log points) that logs are unreadable