Debug With File

What it does

This skill, "Debug With File," enhances debugging workflows by providing an evidence-based exploration process. It records and consolidates insights during debugging sessions, corrects misunderstandings, and preserves learned information even from failed attempts. The core workflow involves exploring the error source, documenting understanding, logging analysis results, correcting hypotheses, fixing the code, and verifying the solution.

When to use it

• When encountering a bug that requires detailed investigation and root cause analysis.
• For complex debugging scenarios where initial assumptions might be incorrect or require refinement.
• To maintain a documented record of the debugging process for future reference or collaboration.
• When needing assistance in validating hypotheses and identifying potential fixes.
• To leverage previously recorded insights from similar bugs (using ccw spec load --category debug).

Key capabilities

• Session Management: Automatically detects existing debugging sessions and resumes them, or starts a new session if one doesn't exist.
• Understanding Documentation: Creates and updates an understanding.md file to track the evolution of understanding during the debugging process.
• Hypothesis Generation & Validation: Generates testable hypotheses and uses analysis to validate them.
• Logging Instrumentation: Adds NDJSON logging instrumentation for detailed error tracking.
• Analysis-Assisted Correction: Validates and corrects initial hypotheses based on analysis of debug logs.
• Consolidation: Simplifies proven-wrong understanding within the understanding.md file to avoid clutter.

Example prompts

• "Debug this bug: $BUG." (This will initiate a new debugging session for the specified bug.)
• "Continue debugging session for bug $BUG." (Resumes an existing debugging session for the specified bug.)
• "Analyze the debug log and update my understanding of the problem." (Triggers the analysis mode to evaluate hypotheses and correct misunderstandings.)

Tips & gotchas

• The skill relies on a project root directory, determined by Git if available, otherwise falling back to the current working directory. Ensure your project has a .workflow/ directory in this location.
• Running ccw spec load --category debug can provide known issues, workarounds, and root-cause notes for common bugs.