✨ feat: add doctor diagnostics and layered GraphQL error hints

README.md

@@ -133,6 +133,20 @@ gh-llm pr thread-resolve PRRT_xxx --pr 77900 --repo PaddlePaddle/Paddle
 gh-llm pr thread-unresolve PRRT_xxx --pr 77900 --repo PaddlePaddle/Paddle
 ```
 
+### Environment Diagnosis
+
+```bash
+gh-llm doctor
+gh llm doctor
+```
+
+`doctor` prints the current entrypoint, resolved executable paths, `gh` / `gh-llm` versions,
+active-host `gh auth status`, a REST probe, a minimal GraphQL probe, and proxy-related environment variables.
+
+When `gh-llm` hits transport errors such as GraphQL `EOF` / timeout failures, the CLI now reports the
+retry count and suggests concrete follow-up commands such as `gh auth status`,
+`gh api graphql -f query='query{viewer{login}}'`, and `gh-llm doctor`.
+
 ## PR Review Workflow
 
 ### 1) Start from diff hunks

skills/github-conversation/SKILL.md

@@ -48,6 +48,17 @@ Command prefix mapping:
 1. If installed via `uv tool`, use `gh-llm ...`.
 2. If installed as `gh` extension, use `gh llm ...`.
 
+### Environment preflight / troubleshooting
+
+When `gh-llm` fails with unclear transport or auth symptoms (for example GraphQL `EOF`, timeout, or an environment mismatch between `gh-llm` and `gh llm`), run:
+
+```bash
+gh-llm doctor
+gh llm doctor
+```
+
+`doctor` prints the current entrypoint, resolved executable paths, active-host `gh auth status`, a REST probe, a minimal GraphQL probe, and proxy-related environment variables. Use this before guessing whether the issue is auth, network, proxy, or GitHub-side.
+
 ## Fast start
 
 ### Read a PR

src/gh_llm/cli.py

@@ -5,12 +5,14 @@
 import sys
 
 from gh_llm import __version__
+from gh_llm.commands.doctor import register_doctor_parser
 from gh_llm.commands.issue import register_issue_parser
 from gh_llm.commands.pr import (
     parse_event_indexes as _parse_event_indexes,
     parse_review_ids as _parse_review_ids,
     register_pr_parser,
 )
+from gh_llm.diagnostics import GhCommandError, format_command_error
 from gh_llm.invocation import detect_prog_name
 
 
@@ -25,6 +27,10 @@ def run(argv: list[str]) -> int:
 
     try:
         return int(handler(args))
+    except GhCommandError as error:
+        for line in format_command_error(error):
+            print(line, file=sys.stderr)
+        return 1
     except (RuntimeError, ValueError) as error:
         print(f"error: {error}", file=sys.stderr)
         return 1
@@ -54,6 +60,7 @@ def _build_parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="command")
     register_pr_parser(subparsers)
     register_issue_parser(subparsers)
+    register_doctor_parser(subparsers)
 
     return parser