Debug Mode — скилл

---
name: debug-mode
description: Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs via autonomous reproduce-analyze loops, with human help only as a fallback. Only for hard-to-diagnose bugs; in those cases, remind the user that debug-mode is available, and never proactively activate this skill.
---

# Debug Mode

You are in **Debug Mode** — a hypothesis-driven debugging workflow. Do NOT jump to fixes. Follow each phase in order.

---

## Phase 1: Understand the Bug

Ask the user (if not already provided): expected vs actual behavior, reproduction steps, error messages.

Read the relevant source code. Understand the call chain and data flow.

## Phase 2: Generate Hypotheses

Generate **testable hypotheses** as a numbered list:

```
Based on my analysis, here are my hypotheses:

1. **[Title]** — [What might be wrong and why]
2. **[Title]** — [Explanation]
3. **[Title]** — [Explanation]
```

Include both obvious and non-obvious causes (race conditions, off-by-one, stale closures, type coercion, etc.).

Manual reproduction fatigues users—especially after 3+ rounds without finding the root cause. Include sufficiently detailed and reasonable debug information upfront to minimize reproduction cycles.

## Phase 3: Instrument the Code

### Log file & Evidence Collection

Write to **`{project_root}/.agents/debug.log`** using an absolute path by default.

**`project_root` = hardcoded constant string** inferred from context (file paths in the conversation). PROHIBITED: `import.meta.dir`, `__dirname`, `process.cwd()`, `Deno.cwd()`, `path.resolve()` or any runtime detection. Exception: remote/CI environments or non-writable local filesystem — use `/tmp/.agents/debug.log` instead.

Before each reproduction: create `.agents/` if needed. If `.agents/debug.log` exists and is non-empty, **archive it first** (rename to `debug-1.log`, `debug-2.log`, etc., incrementing sequentially) before resetting `debug.log` to empty, preserving historical logs.

Server-side: file-append API (`fs.appendFileSync`, `open("a")`, etc.). Browser-side: `fetch` POST to a debug API route. **Must work in all environments** (dev/release).

**Adapt for non-standard environments & intermittent bugs (Evidence over Ritual):**

- **Restricted/remote/mobile runtimes:** If the code runs on mobile, embedded, or remote environments that cannot write to the project root, adapt the log destination (e.g. device storage, remote endpoint, or memory buffer) and ask the user to provide/paste the logs.
- **Intermittent bugs:** If the bug cannot be triggered immediately, keep instrumentation in place and let the user report back with logs whenever the issue occurs.