code-debug-skill（代码调试技能）

Bug Investigation Skill

Investigation mindset (how to think)

• Treat facts as primary. Separate observations from inferences at all times.
• Keep multiple competing hypotheses and rank them by likelihood and impact.
• For each hypothesis, define:

- prediction (what must be observed if true), - falsifier (what would disprove it), - required instrumentation (what to measure or log).

• Prefer decisive signals over narratives. Do not ask for reproduction without a plan to capture evidence.
• Narrow with comparisons (fail vs pass) and a binary-search style approach when possible.
• Add debug instrumentation generously to capture decisive signals in a single reproduction run.

- Assume each reproduction is costly; instrument enough to narrow root cause without requiring additional runs.

• Never fix code speculatively. Confirm root cause with evidence before any production code change.

Tool selection (what to use)

• Primary tool for new instrumentation: local HTTP ingest logger (debugsk).

- AI MUST start the server via npx debugsk@latest server start --json before instrumentation. - Use the JSON output to copy the snippet and endpoint. - The server accepts CORS preflight (OPTIONS), so the default JSON snippet works across origins.

• AI MUST auto-generate sessionId/runId and embed them directly into instrumentation code.

- Do NOT ask the user to set these via console.

• If reproduction is possible, prioritize logs/metrics that directly test predictions.
• If reproduction is not possible, pivot to existing signals:

- logs/metrics/traces, config diffs, data snapshots, dumps, and deterministic probes.

• If native signals do not answer the question, prefer debugsk for new observations.

- This avoids contaminating native logging and keeps investigation logs isolated.

• Use native logs as reference in addition to new instrumentation.

Operating principles

• Separate facts (observed) from hypotheses (inferred).
• Maintain multiple competing hypotheses until evidence eliminates them.
• For each hypothesis, define predictions, falsifiers, and required instrumentation.
• AI performs all automatable tasks: server start, ID generation, log collection, analysis.
• User performs ONLY non-automatable UI actions (clicks, form inputs, etc.).
• Do not ask for reproduction until an instrumentation plan is ready.

Core loop

1. Clarify the bug precisely:

- Environment (local/staging/production), version/commit, frequency, impact. - Minimal reproduction steps, expected vs actual, errors and timestamps.

1. Identify candidate code paths:

- Search by endpoint/route/feature/config key/error text. - Map request → handler → data/dependencies.

1. Generate at least three hypotheses:

- Client/input, server logic, data/state, concurrency, config, dependency, resource.

1. Start debug server and generate IDs:

- Run npx debugsk@latest server start --json to get endpoint. - Auto-generate sessionId/runId and embed in instrumentation code.

1. Instrument to validate hypotheses:

- Add logs/metrics at decision points and boundaries. - Include auto-generated correlation keys (no user action required).

1. Execute controlled reproduction:

- AI starts servers if needed. - Provide ONLY UI steps to the user (click, drag, submit, etc.). - NO console commands, NO file operations.

1. Collect and analyze logs:

- AI reads log files directly using Read/Grep tools. - Compare successful vs failing runs. - Prefer binary search-style narrowing when possible.

1. Iterate until root cause is confirmed.

Instrumentation policy

• Prefer a local HTTP ingest logger when available; otherwise integrate with existing logging.
• If native signals are insufficient, prioritize debugsk over adding more native logs.
• Use native logs as reference alongside the added instrumentation.
• Logs must never throw, avoid secrets/PII, and be easy to remove.
• Record location, message, timestamp, and correlation fields in every event.
• YOU MUST ALWAYS include all log fields (timestamp, message, sessionId, runId, hypothesisId, location) in every log event. Never omit any field.
• Do not guard instrumentation behind environment flags. Write logs for the investigation, then remove them after completion.
• AI starts the debug server, generates IDs, inserts instrumentation, and collects/analyzes logs.
• User performs ONLY UI actions (clicks, form inputs, etc.). NO console commands, NO file operations.

User interaction rules

• MINIMIZE user burden. AI performs all automatable tasks:

- Start/stop debug server - Generate and embed sessionId/runId - Read and analyze log files - Determine if tunneling is needed (inspect environment, don't ask)

• User performs ONLY non-automatable UI actions:

- Click buttons, drag elements, fill forms - Navigate screens - Observe visible behavior

• When reproduction is required, provide ONLY UI steps. NO console commands, NO file operations.
• If reproduction is not possible, pivot to existing logs, metrics, traces, config diffs, or safe probes.
• For external/mobile access, AI determines tunneling need based on environment inspection:

- If remote/staging: check existing tunnels or propose specific setup - Do NOT ask open-ended "should we use tunnel?" questions

Cleanup policy

• When the user confirms the issue is resolved or the investigation is closed, stop the debug server and delete all investigation logs (e.g., .logs/).
• Do not use git checkout, git clean, or other bulk git cleanup for log deletion. Remove files explicitly and safely.
• If deletion could affect unrelated files, confirm the exact paths before removal.

Reporting format

Use the template in assets/report-template.md. Headings are bilingual (English / Japanese); write content in the user's language.

References

• Use references/logging-schema.md when adding or validating instrumentation.
• Use references/hypothesis-template.md to structure hypotheses and predictions.