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.
2. Identify candidate code paths:
   • Search by endpoint/route/feature/config key/error text.
   • Map request → handler → data/dependencies.
3. Generate at least three hypotheses:
   • Client/input, server logic, data/state, concurrency, config, dependency, resource.
4. 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.
5. Instrument to validate hypotheses:
   • Add logs/metrics at decision points and boundaries.
   • Include auto-generated correlation keys (no user action required).
6. 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.
7. 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.
8. 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.