Hypothesis-driven debugging

Updated Oct 17, 2026

The hypothesis-debugging skill plans a debugging investigation rather than performing it. It writes a falsification plan and hands execution to a sub-agent, preferring alchemist.

Plans are written under docs/debugging/, which the skill creates when it is missing. Each plan is named debugging-plan-<year>-<month>-<day>-<problem-slug>.md: a four-digit year, zero-padded month and day, then a lower-case, hyphen-separated slug naming the problem under investigation. For example, a plan opened on 20 August 2026 for a faulty ACP skill agent menu is debugging-plan-2026-08-20-acp-skill-agent-menu.md.

The slug is required. The date alone sorts plans chronologically but leaves a directory of indistinguishable filenames, so the slug is what makes a plan identifiable without opening it. Earlier plans used an opaque debugging-plan-{timestamp}.md name; see the migration guide for renaming them.