Bugfix - Intelligent Bug Debugging and Fixing

When to Use This Skill

Use this skill when:

•The user reports a bug or unexpected behavior
•The user asks to fix an issue or error
•The user says something isn't working correctly
•The user invokes /bugfix [description]

Core Philosophy

Understand, Reproduce, Fix: First consult documentation to understand expected behavior, then establish a reproducible test case, and finally fix the bug. If you can't reproduce it, you can't verify the fix.

Workflow

Step 1: Read Relevant Documentation

Use the read-docs skill to search for and read documentation in ./docs/:

•Search for docs related to the bug component/system
•Read all relevant documentation files
•Follow read-docs skill procedures: log access, score helpfulness, request missing docs

Decision Point - Are docs sufficient?

→ Docs are SUFFICIENT (complete, accurate, helpful):

•You understand the expected behavior
•You know what the bug is deviating from
•Proceed to Step 2

→ Docs are INSUFFICIENT (missing, incomplete, or outdated):

•You logged access with -1 or +0 score
•You added documentation request(s) to ./docs/documentation-requests.md
•Now evaluate: Is the missing information CRITICAL to understanding the bug?

CRITICAL means:

•You cannot determine expected behavior without it
•You don't understand how the component should work
•The bug involves behavior that isn't documented
•You would be guessing at what "correct" means

If CRITICAL → STOP and invoke docs-maintainer:

•DO NOT proceed to Step 2
•DO NOT "examine the code directly"
•DO NOT "work around the gap"
•Instead: Use Task tool with subagent_type=docs-maintainer
•Provide context about what documentation is needed
•Wait for documentation to be created
•Return to Step 1 (read the newly created docs)

If NOT CRITICAL (only minor details missing):

•The overall expected behavior is clear from docs
•You just need minor implementation details from code
•Proceed to Step 2 (use code inspection to fill gaps)

What documentation tells you:

•What the correct behavior should be
•What the bug is deviating from
•Where to look for the root cause
•What test cases to write

See .claude/skills/read-docs/SKILL.md for complete documentation access procedures.

Step 2: Establish a Reproducible Test Case

•
Check for existing failing tests
- •Run the test suite: go test ./...
- •Look for tests related to the bug description
- •If a test is already failing for this issue, use it as the repro
•
If no failing test exists, create one
- •Identify the affected package/module
- •Write a minimal test that demonstrates the bug
- •
  The test should:
  - •Be focused and minimal (test one thing)
  - •Have a clear assertion that fails due to the bug
  - •Include a descriptive name explaining what should happen
- •Run the new test to confirm it fails: go test -v ./pkg/[package]/ -run TestName
•
If you cannot establish a repro
- •STOP immediately
- •Explain to the user what you've tried
- •
  Ask clarifying questions:
  - •What exact steps trigger the bug?
  - •What is the expected vs actual behavior?
  - •Can they provide example inputs/outputs?
  - •Are there specific scenes or parameters that trigger it?
- •Do NOT proceed to debugging without a repro

Step 3: Debug the Issue

•
Analyze the failing test
- •Examine the test output and error messages
- •Identify the root cause (not just symptoms)
- •Use the Read tool to examine relevant source files
- •
  Look for:
  - •Logic errors
  - •Edge cases not handled
  - •Race conditions (if parallel code)
  - •Numerical precision issues (common in raytracers)
  - •Incorrect assumptions
•
Form a hypothesis
- •State clearly what you believe is causing the bug
- •Explain the reasoning
- •
  If uncertain, use debugging techniques:
  - •Add temporary logging/prints
  - •Check intermediate values
  - •Verify assumptions with additional test assertions

Step 4: Implement the Fix

•
Make targeted changes
- •Fix the root cause, not symptoms
- •Keep changes minimal and focused
- •Follow the existing code style
- •Avoid over-engineering or adding unnecessary features
•
Consider edge cases
- •Does the fix handle boundary conditions?
- •Are there similar bugs elsewhere in the codebase?
- •Does the fix introduce new issues?

Step 5: Verify the Fix

•
Run the reproduction test
- •go test -v ./pkg/[package]/ -run TestName
- •The test that was failing must now pass
- •If it still fails, return to Step 3
•
Run the full test suite
- •go test ./...
- •Ensure no regressions were introduced
- •If any other tests fail, investigate and fix
•
Manual verification (if applicable)
- •
  If the bug affects visual output or interactive features:
  - •Test with the CLI: ./raytracer --scene=... --max-samples=10
  - •Or test with the web interface
- •Verify the expected behavior is now correct

Step 6: Clean Up

•
Remove debugging code
- •Remove any temporary logging, prints, or debug statements
- •Keep the test case you created
•
Document if needed
- •If the bug was subtle or non-obvious, add a comment explaining why the fix is necessary
- •Update any relevant documentation

Special Considerations for Raytracer Bugs

Rendering Issues:

•Always verify tests with visual output when fixing rendering bugs
•Be careful with floating-point comparisons (use epsilon for tolerance)
•Consider both path-tracing and BDPT integrators

Performance Issues:

•Use benchmarks, not just tests: go test -bench=. ./pkg/[package]/
•Profile if needed: --profile=cpu.prof then go tool pprof cpu.prof

Parallel/Concurrency Bugs:

•These are hard to reproduce - run tests multiple times
•Look for race conditions: go test -race ./...
•Check for proper synchronization in worker pools

BVH/Acceleration Structure Bugs:

•Test with scenes that stress the BVH: spheregrid, trianglemesh, dragon
•Verify both correctness and performance

Examples

Example 1: Visual Rendering Bug

code

User: "/bugfix The cornell box scene has black artifacts in the corners"

Response:
1. First, let me check documentation about the Cornell box scene and rendering...
   [Uses read-docs skill: searches, reads ./docs/scenes.md and ./docs/rendering.md]
   [Logs access per read-docs procedures]

2. Based on the docs, Cornell box should have uniform lighting. Let me check for
   existing tests...
   [Checks test files]

3. I don't see a failing test. Let me create a test that renders the cornell
   scene and checks for black pixels (RGB values below a threshold in expected
   areas):
   [Creates test in pkg/scene/cornell_test.go]

4. Running the test...
   [Test fails, confirms the bug]

5. Now analyzing the cornell scene setup and rendering code...
   [Investigates light sources, material properties, ray intersection]

6. Found the issue: [explains root cause]
   [Implements fix]

7. Re-running the test...
   [Test passes]

8. Running full test suite...
   [All tests pass]

The bug is fixed! The issue was [explanation].

Example 2: Cannot Reproduce

code

User: "/bugfix Random crashes when rendering"

Response:
1. Let me check documentation about the rendering system and known issues...
   [Uses read-docs skill: reads ./docs/renderer.md]
   [Logs access, scores +0 - found general overview only]

2. Documentation doesn't mention crashes. Let me check for existing tests and
   try to reproduce...
   [Attempts to create a test, runs various scenarios]

3. I cannot establish a reliable reproduction of this crash. I need more
   information:

   - Which scene(s) cause the crash?
   - What command line arguments are you using?
   - Does it happen after a certain number of passes/samples?
   - Are you using CLI or web interface?
   - What does the error message say (if any)?

   Once I can reproduce it, I'll be able to debug and fix it.

Example 3: Existing Failing Test

code

User: "/bugfix Tests are failing in pkg/geometry"

Response:
1. First, let me check documentation about the geometry package and BVH...
   [Uses read-docs skill: reads ./docs/bvh.md]
   [Logs access, scores +1 - found helpful info]

2. Documentation explains BVH should use median-split. Running the test suite
   to identify which test is failing...
   [go test ./pkg/geometry/]

3. Found failing test: TestBVHIntersection
   [Shows test output]

4. This test is our repro. Analyzing why it fails based on expected behavior
   from docs...
   [Investigates the code]

5. Root cause: [explanation]
   [Implements fix]

6. Verifying fix...
   [Test now passes, full suite passes]

Fixed! The issue was [explanation].

Example 4: Missing Documentation (Critical)

code

User: "/bugfix BDPT integrator produces incorrect brightness"

Response:
1. Let me check documentation about BDPT implementation...
   [Uses read-docs skill: reads ./docs/integrators.md]
   [Logs access, scores -1 - missing MIS and brightness details]
   [Adds documentation request per read-docs procedures]

2. The missing documentation on MIS weighting is critical to understanding the
   expected behavior. Let me invoke the docs-maintainer agent to create this
   documentation before proceeding...
   [Uses Task tool with subagent_type=docs-maintainer]
   [Agent creates documentation on BDPT MIS weighting]

3. Now reading the newly created documentation...
   [Reads updated ./docs/integrators.md]
   [Logs access, scores +1 - found needed MIS details]

4. Based on the documentation, I now understand the expected MIS calculation.
   Creating a test that verifies brightness values...
   [Creates test that checks brightness values]
   [Test fails, confirms bug]

5. Analyzing code against documented behavior...
   [Investigates BDPT implementation]

6. Found the issue: MIS weights not properly normalized per the documented formula
   [Implements fix]

7. Verifying fix...
   [Test passes, full suite passes]

Fixed! The bug was in the MIS weight normalization.

Common Pitfalls to Avoid

•Don't skip documentation - Always check docs first (follow read-docs skill procedures)
•
DON'T PROCEED TO STEP 2 WHEN DOCS ARE CRITICAL - This is the most common mistake:
- •If you can't determine expected behavior from docs, STOP
- •If you say "let me examine the code directly" when docs are missing, you're doing it wrong
- •Invoke docs-maintainer first, wait for docs, then proceed
- •Code inspection is NOT a substitute for understanding expected behavior
•Don't guess at fixes - Always understand the root cause first
•Don't skip the repro - "It seems to work now" is not sufficient
•Don't introduce regressions - Always run the full test suite
•Don't over-complicate - Simple, targeted fixes are better
•Don't leave debug code - Clean up before finishing

Integration with Project Testing

This raytracer project has:

•Unit tests in each package: pkg/*/[package]_test.go
•Test helper utilities
•Benchmark support
•Race detection available

Use these existing tools and patterns when creating reproduction tests.