repro-debug-repo

name

repro-debug-repo

description

Analyze unfamiliar GitHub or local repositories, reproduce them locally from README/setup docs, install the required runtime and dependencies, make the project run, create VS Code `.vscode/launch.json` debug configs, and map an efficient breakpoint tour through the main execution path. Use when Codex is asked to inspect a repo, follow README instructions, fix setup issues, prepare a reproducible dev environment, or show a user where to debug the code flow end to end.

Repro Debug Repo

Use this skill to turn an unfamiliar repository into a runnable, debuggable local project with explicit setup commands, a verified startup path, a VS Code launch configuration, and a breakpoint plan.

Output contract

Produce these deliverables unless the user asks for less:

1. A short environment summary: language/runtime, package manager, required services, env vars, ports.
2. Exact setup and run commands that were actually used.
3. A status statement: running successfully, partially running, or blocked.
4. A .vscode/launch.json file or patch, plus any .env / args assumptions.
5. A breakpoint tour that follows one successful request / CLI invocation / job execution path.
6. A brief logic walkthrough from entrypoint to core business code.

Do not claim the repo is reproducible unless you actually started it, ran its tests, or hit a concrete external blocker that you document.

Workflow

1. Build a fact base before changing anything

If the user gives a GitHub URL and the repo is not present locally, clone it first and check out the requested branch/tag before inspecting files.

Inspect the repo in this order:

1. README*, docs, setup guides, example commands.
2. Runtime markers: .python-version, .nvmrc, .tool-versions, Dockerfile, docker-compose*.yml, .env.example.
3. Build and dependency files: pyproject.toml, requirements*.txt, package.json, pnpm-lock.yaml, yarn.lock, package-lock.json, go.mod, Cargo.toml, pom.xml, build.gradle*, Makefile, justfile.
4. Candidate entrypoints and scripts.

Run scripts/scan_repo.py <repo-path> early to collect a quick manifest/entrypoint report. Treat its output as hints, not ground truth.

If the README conflicts with heuristics, prefer the README and mention the conflict.

2. Choose the narrowest successful reproduction path

Prefer the smallest path that proves the project works:

• CLI repo: run one documented command with sample input.
• Library repo: run the documented example or focused tests.
• Backend service: start the app and hit one health/example route.
• Frontend repo: start dev server and load the main page if feasible.
• Monorepo: pick the package/app the README tells users to start first.

Avoid over-building. Get one path working first, then expand only if needed.

3. Provision the environment conservatively

Use isolated, repo-local setup where possible.

• Python: prefer uv / poetry / pip based on repo files; otherwise use python -m venv .venv.
• Node.js: honor packageManager, lockfiles, .nvmrc, .node-version, or engines.
• Go/Rust/Java: use the repo's standard toolchain and build command first.
• Docker/devcontainer: prefer it only when the README makes it the primary path or native setup is impractical.

Record exact versions when discoverable. Never silently upgrade major runtimes.

For stack-specific reminders, open references/repo-intake-checklist.md.

4. Make the project run and verify it

Capture:

• install command
• env file creation/export commands
• database/cache/broker dependencies
• seed/migration steps
• final run command
• proof of success: log line, test output, endpoint response, or generated artifact

When blocked, stop after producing the smallest actionable blocker report: missing secret, unsupported platform dependency, dead upstream service, bad docs, etc.

5. Create VS Code debug configs

Always create at least one debug config for the successful path you verified.

Rules:

• Write .vscode/launch.json in the repo, not in the skill.
• Prefer launching the real entrypoint over wrapping everything in a shell.
• Set cwd explicitly.
• Use envFile when the repo already uses .env.
• Add arguments that match the verified happy path.
• If the project starts through npm run ..., python -m ..., go test, cargo run, etc., mirror that behavior in the launch config.
• Add a second config only when it materially helps: attach mode, tests, worker process, browser, or alternate service.

Open only the relevant section in references/vscode-debug-recipes.md.

6. Build a breakpoint tour, not a random list

Pick one concrete scenario and order breakpoints from outermost to innermost.

Default sequence:

1. Process bootstrap / main entrypoint.
2. Config/env loading.
3. Router / CLI arg parsing / job dispatch.
4. Request handler / command handler / task runner.
5. Validation/auth boundary.
6. Core service or business logic function.
7. Persistence or external API boundary.
8. Result transformation / serialization / rendering.
9. Error handling / retry / cleanup path.

Prefer repo-specific file:line references when you can verify them. Otherwise cite file + function/class name and say it is an inferred breakpoint.

Open references/breakpoint-playbook.md only for the matching repo shape.

7. Explain the logic in one debug pass

After the app runs, explain the path the debugger should follow:

• how execution enters the program
• where config becomes runtime state
• where user input or request data is normalized
• where core business decisions happen
• where state leaves the process (DB/API/file/output)
• where the final response/result is assembled

Keep this walkthrough short and tied to the breakpoints you recommend.

Quality bar

Before finishing, check that you have:

• followed the README or documented why it was wrong
• used repo-specific commands instead of generic guesses
• verified at least one runnable/debuggable path
• created a launch config that matches that path
• given breakpoint guidance in execution order
• listed unresolved blockers separately from confirmed facts

Resources

• scripts/scan_repo.py: quick repo scan for manifests, version markers, scripts, and candidate entrypoints.
• references/repo-intake-checklist.md: what to inspect and how to infer setup safely.
• references/vscode-debug-recipes.md: minimal launch.json recipes by stack.
• references/breakpoint-playbook.md: breakpoint heuristics by repo shape.