repo-troubleshooting-guide

# Repo Troubleshooting Guide Turn a repository into a structured, professional troubleshooting guide. The guide is grounded in two sources: (1) the **detected stack** (languages, frameworks, services, infra) and (2) **mined evidence** from the actual code (raised exceptions, human-readable error strings, env vars, ports, Docker services, CI, and TODO/FIXME markers). Generic advice is a fallback; repo-specific evidence always wins. ## What you produce A single Markdown file (default `TROUBLESHOOTING.md` at the repo root) with: a quick setup checklist, issue sections organized by subsystem, recovery procedures, a known-gaps section from TODO markers, and a "still stuck" section. Clean professional tone — no emoji, no motivational filler. See `references/output-template.md` for the exact structure. ## Workflow Follow these phases in order. Each phase has a clear endpoint so you can checkpoint. ### Phase 1 — Locate the repo Determine the repository path. If the user uploaded or cloned a repo, use that path. If they named a public repo, clone it (shallow): `git clone --depth 1 <url> /tmp/<name>`. If the path is ambiguous, ask which directory is the repo root before proceeding. ### Phase 2 — Scan for evidence Run the scanner to produce a structured inventory. It is stdlib-only Python and writes JSON describing the stack and failure-mode signals: ```bash python scripts/scan_repo.py <repo-path> --out /tmp/evidence.json ``` Read `/tmp/evidence.json`. Key fields: - `languages`...