debug-surface-map

name	debug-surface-map
description	Discover and document a repository's run, health, logs, traces, screenshots, network capture, state reset, and artifact bundle surfaces for agent debugging.

Debug Surface Map

Use this skill when a user wants a single entry point for debugging or wants to understand how an agent can observe a running app.

Discovery Order

1. Read AGENTS.md, README, package scripts, Makefile, justfile, Taskfile, and tool docs.
2. Identify the canonical run command.
3. Identify the canonical health check.
4. Identify evidence locations: logs, screenshots, traces, network captures, test reports, crash reports.
5. Identify state surfaces: database, filesystem, browser storage, queues, caches, external providers.
6. Identify reset and bundle commands.

Desired Debug Contract

debug:start -> debug:doctor -> debug:reset -> debug:bundle

Names should follow the repo's existing convention. For example:

• npm run debug
• just debug
• make debug
• cargo xtask debug
• tools/debug/start

Artifact Paths

Prefer ignored repo-local paths:

.debug/
.artifacts/
tmp/debug/

Do not write evidence into tracked source directories unless the repo already has a documented artifact convention.