skills.rest
catlog22
catlog22COMMUNITY
Explore all skills by this author →
GitHub

debug-with-file

Diagnose bugs through hypothesis-driven debugging with documented exploration and NDJSON logging.

2.1k|165|Updated Sep 7, 2025
Search Tags:#hypothesis testing#instrumentation#Debugging#Root Cause Analysis#Logging#CODEX#NDJSON
One-click install
npx skills add https://github.com/catlog22/Claude-Code-Workflow --skill debug-with-file
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-with-file
Source: https://github.com/catlog22/Claude-Code-Workflow/tree/main/.codex/skills/debug-with-file
Command: npx skills add https://github.com/catlog22/Claude-Code-Workflow --skill debug-with-file

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debugging complex bugs often involves scattered guesswork and lost context between investigation rounds. This Skill structures the process by generating testable hypotheses, instrumenting code with NDJSON logging, and maintaining an evolving understanding document that records evidence, corrections, and lessons learned.

Core Features & Use Cases

  • Hypothesis-Driven Investigation: Generates 3-5 testable hypotheses from the bug description, each with logging points and confirm/reject evidence criteria.
  • Documented Exploration: Maintains understanding.md with an iteration timeline, corrected misunderstandings (strikethrough annotations), and a consolidated current-state summary.
  • Session Persistence: Stores debug.log, hypotheses.json, and understanding.md under .workflow/.debug/ so sessions resume across Explore, Analyze, and Fix modes.
  • Use Case: You hit an intermittent 'config value is None' error. Run the skill to instrument the suspected code paths, reproduce the bug, then let it parse the NDJSON log, confirm the root-cause hypothesis, apply the fix, and clean up all instrumentation.

Quick Start

Ask the AI to debug the error message you are seeing using the debug-with-file workflow, then reproduce the bug and run it again for analysis.

Frequently Asked Questions about debug-with-file

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a bug with hypothesis-driven logging?▼

Provide the bug description or error message, and the skill searches the codebase, generates testable hypotheses, and inserts NDJSON logging at relevant code points. After you reproduce the bug, run it again to parse the log and confirm or reject each hypothesis.

What is NDJSON logging and why use it for debugging?▼

NDJSON (newline-delimited JSON) writes one structured JSON object per line, making debug logs machine-parseable. Each entry records the session ID, hypothesis ID, code location, captured data, and timestamp, enabling automated evidence evaluation.

Does this debugging workflow support Python and JavaScript?▼

Yes, it provides instrumentation templates for both Python and JavaScript/TypeScript. Each template wraps logging in try/catch blocks with region markers so debug code never breaks execution and can be removed cleanly afterward.

What happens if all debugging hypotheses are rejected?▼

The skill analyzes the disproven assumptions, corrects the understanding document with strikethrough annotations, and generates new hypotheses based on what was learned. After more than five iterations it recommends escalating with the full consolidated context.

Where are debug session files stored?▼

Session artifacts are stored in .workflow/.debug/DBG-{date}-{slug}/ under the project root, containing debug.log, understanding.md, and hypotheses.json. The project root is detected via git, falling back to the current directory.

Related Skills

Explore More Software Engineering Skills→
saboteur-labssaboteur-labs

debug-issue

Diagnose software bugs by identifying root causes and delivering minimal, testable fixes.

Official
Advanced
skylarsaboskylarsabo

fix-verified

Fix confirmed bugs at root cause with evidence and regression guards.

Community
Advanced
dorriodorrio

ln-510-quality-coordinator

Analyze code quality, clean tech debt, and run regression tests.

Community
Advanced
cslsoftwarescslsoftwares

developer-delphi-assembly-debugging

Enable Delphi assembly debugging with CPU View, breakpoints, and benchmarking tooling.

Community
Advanced