systematic debugging

Engineering Community

Skill notes

Overview

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure. Violating the letter of this process is violating the spirit of debugging.

When to Use

Use for ANY technical issue: Test failures Bugs in production Unexpected behavior Performance problems

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix: Read Error Messages Carefully Don't skip past errors or warnings They often contain the exact solution Read stack traces completely

Phase 2: Pattern Analysis

Find the pattern before fixing: Find Working Examples Locate similar working code in same codebase What works that's similar to what's broken? Compare Against References

Phase 3: Hypothesis and Testing

Scientific method: Form Single Hypothesis State clearly: "I think X is the root cause because Y" Write it down Be specific, not vague

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@obra · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Env read
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Root Cause Investigation

BEFORE attempting ANY fix: Read Error Messages Carefully Don't skip past errors or warnings They often contain the exact solution Read stack traces completely

02
Phase 2: Pattern Analysis

Find the pattern before fixing: Find Working Examples Locate similar working code in same codebase What works that's similar to what's broken? Compare Against References

03
Phase 3: Hypothesis and Testing

Scientific method: Form Single Hypothesis State clearly: "I think X is the root cause because Y" Write it down Be specific, not vague

04
Phase 4: Implementation

Fix the root cause, not the symptom: Create Failing Test Case Simplest possible reproduction Automated test if possible One-off test script if no framework

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.