debug

Debug Code

Operating Principle

Treat errors as symptoms until evidence shows the cause. Work from the most concrete signal available: exact command, full output, local code, recent changes, tests, current docs/source for external dependencies, then the smallest fix that explains all observed behavior.

Do not jump straight from an error string to an edit. First reproduce, isolate, explain, then change.

Tool Priority

Use the best available tool for the evidence needed. Do not block debugging just because a preferred tool is missing.

• Local CLI first: rg, rg --files, git status, git diff, focused tests, logs, dependency manifests, lockfiles, and local dependency source.
• Context7: use for current, version-aware library/framework documentation and code examples when dependency behavior matters.
• GitHub CLI (gh): use for GitHub-native evidence such as issues, PRs, checks, releases, repo metadata, source files, and API calls from the terminal.
• Web Search MCP: 10 tools total — the most relevant ones for debugging are organized into two tiers below. Use the cheapest tool that answers the question.

Web Search MCP — Tool Reference (10 tools)

Tier 1 — Direct Search & Retrieval (start here)

Tool	What It Does	When To Use
search_web	DuckDuckGo or Exa web/news search (via provider param)	Broad search for error messages, known bugs, solutions, release notes
search_web (domain)	DuckDuckGo (site:) or Exa (include_domains) scoped to domain	Targeted search on official docs (e.g. docs.python.org, react.dev)
fetch_page	Clean HTML-to-markdown extraction from any URL	Reading docs, changelogs, error pages, issue threads cleanly; Exa fallback handles JS/bot-blocked pages
search_wikipedia	Wikipedia article search via MediaWiki API	Fact-checking, background reference, terminology lookups
search_arxiv	Academic paper search via arXiv API	Finding research papers, literature reviews, citations

Tier 2 — Community & Issue Mining

Tool	What It Does	When To Use
search_github	GitHub Issues/PR search via GitHub Search API	Find upstream bug reports, fix PRs, changelog discussions, feature flags, deprecation notices across any repo
get_github_issue	Full GitHub Issue/PR thread with all comments	Read complete conversation context with sorted comments
search_hackernews	Hacker News search via Algolia with comment enrichment	Tech community discussions about bugs, regressions, architectural root causes, known workarounds
search_reddit	Reddit search via RSS + shreddit enrichment	Real-world troubleshooting threads, niche library issues, configuration gotchas
search_x	X/Twitter search via Bird CLI	Real-time announcements, outage reports, release alerts, short workaround threads

Not Used

Tool Sources

• Context7 for current library/framework docs and examples. Source: https://github.com/upstash/context7
• GitHub CLI gh for issues, PRs, checks, releases, source/API access. Source: https://cli.github.com/
• Web Search MCP for web search, docs search, page extraction, and community mining (10 tools). Source: https://github.com/sydasif/web-search-mcp

CLI Workflow

1. Capture The Failure

• Record the exact command, inputs, environment assumptions, full error output, file paths, line numbers, versions, and current working directory.
• Re-run once when safe to confirm the failure is reproducible. For flaky failures, run enough times to identify the pattern.
• Separate expected behavior from actual behavior in one sentence.
• If the user provided only a fragment, inspect logs/tests/code before asking for more.

2. Check Local State First

Use local evidence before external lookup:

• Inspect nearby code, call sites, config, fixtures, generated files, dependency manifests, lockfiles, and recent diffs.
• Prefer fast shell tools: rg, rg --files, git diff, git status, targeted test commands, and focused log inspection.
• Read enough context around each relevant symbol to understand the contract, not just the failing line.
• Check local dependency source when available before assuming external behavior.
• Protect unrelated user changes. Do not revert or overwrite changes you did not make.

3. Form Testable Hypotheses

Maintain a small hypothesis list:

• What could produce this exact symptom?
• What observation would prove or disprove each candidate?
• Which candidate best explains all evidence, including edge cases?

Prefer experiments that narrow the search space quickly: focused tests, minimal reproduction commands, temporary logging/inspection that can be removed, or reading the implementation path.

4. Pull Current External Evidence

Use external sources when the issue depends on dependency, framework, CLI, API, OS, or standards behavior that may have changed, or when local code delegates behavior to something outside the repo.

4a. Dependency & API Docs — Context7

For library/framework docs, APIs, configuration, version-specific examples, and known edge cases.

4b. GitHub-Native Evidence — gh

gh issue list, gh issue view, gh pr view, gh pr checks, gh release view, gh repo view, and gh api for upstream GitHub issues, PRs, releases, metadata, checks, and raw source.

4c. General Search — Tier 1

Scenario	Tool	Why
"Does this error message have a known cause?"	search_web with the exact error string	Broadest coverage of blog posts, Stack Overflow, docs, forums
"What does the official docs say about this API?"	search_web with domain="docs.python.org"	Skips noise from unofficial sources
"Read this changelog / issue / PR in full"	fetch_page with the URL	Clean extraction without JS or paywalls

4d. Issue & Community Mining — Tier 2

Scenario	Tool	Why
"Is there a GitHub issue for this?"	search_github with keywords + repo filter	Direct access to upstream bug tracker, fix PRs, and discussion
"Has this been discussed on Hacker News?"	search_hackernews	Often surfaces deep architectural analysis and workarounds from core devs
"What are real users saying about this?"	search_reddit for niche/subreddit-specific chatter	Practical troubleshooting, config fixes, version-specific gotchas
"Any breaking news about this outage/incident?"	search_x for real-time posts	Time-sensitive: service outages, zero-days, urgent releases

Prefer primary sources: official docs, changelogs, release notes, source code, and upstream issues. Use community posts only as leads unless they include reproducible evidence.

5. Confirm Root Cause Before Editing

Before making code changes, be able to state:

• The root cause.
• Why the observed failure follows from that cause.
• What evidence ruled out the main alternatives.
• Which behavior the fix must preserve.

If the root cause is still uncertain, keep investigating. If uncertainty remains after reasonable investigation, report the evidence, the uncertainty, and the next best diagnostic step instead of shipping a speculative fix.

6. Implement The Smallest Correct Fix

• Fix the cause, not only the immediate symptom.
• Follow the repository's existing style, abstractions, and ownership boundaries.
• Keep changes scoped. Avoid opportunistic refactors unless they are necessary to fix safely.
• For dependency limitations, adapt at your boundary: validate, normalize, wrap, pin, or document behavior in code/tests as appropriate.
• Remove temporary debug prints, probes, and scratch artifacts before finishing.

7. Verify The Fix

Verification should match risk:

• Re-run the original failing command or reproduction.
• Run the narrowest relevant test first, then broader tests if the change touches shared behavior.
• Add or update a regression test when the bug is non-trivial, user-facing, shared, or likely to recur.
• Cover edge cases that were part of the root cause.
• Run static checks when the repository has an obvious command for them.
• Use gh pr checks or gh run view when CI state is part of the failure or verification.

If a verification command cannot be run, say exactly why and what remains unverified.

Flaky Or Intermittent Failures

For flakiness, do not rely on a single pass:

• Run repeated attempts or targeted subsets to estimate frequency.
• Look for ordering, timing, randomness, shared state, network, timezone, locale, filesystem, cache, and parallelism dependencies.
• Capture seed, timestamps, worker count, and environment details when available.
• Check upstream issues/releases with search_github, gh, and community search (search_hackernews, search_reddit) when the flake may come from a dependency or hosted service.
• Prefer deterministic fixes over retries. Retries are acceptable only when the underlying operation is inherently unreliable and the retry policy is bounded and justified.

Reporting Back

When finished, keep the summary evidence-based:

• Root cause in plain language.
• Files changed and why.
• Verification commands and outcomes.
• External sources used, with the specific tool that found each (e.g., "found via search_github").
• Remaining risk or unverified areas, if any.