repo-troubleshooting-guidelisted

Generate a clean, professional troubleshooting guide (a TROUBLESHOOTING.md) by analyzing a code repository — detecting its tech stack and mining real evidence (raised exceptions, error strings, env vars, ports, Docker services, CI) to document common failure modes with step-by-step fixes. Use this whenever the user wants to create, build, or generate a troubleshooting doc, guide, runbook, or ops reference for a repo, codebase, or project; wants to document common errors, setup problems, failure modes, or "how to fix X"; or points Claude at a repository and asks for a debugging/operations reference. Trigger even if the user doesn't say the exact word "troubleshooting" — e.g. "document the common errors in this repo", "make a debugging runbook", "build a setup-issues guide", "write an ops doc for this project".
scoobydrew83/skills · ★ 0 · Code & Development · score 78

Install: claude install-skill scoobydrew83/skills

# 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`