One Claude Code Tip a Day: Turn GitHub Issues into a Verified Workplan

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

A vague GitHub issue is one of the easiest ways to waste a Claude Code session. The ticket says “fix checkout loading state” or “add export button,” you paste it into Claude, and the model confidently edits the first file that looks relevant. Ten minutes later you have a patch, but not necessarily the right patch: maybe the bug only happens behind a feature flag, the export endpoint already exists, or the failing behavior lives in a shared hook used by three screens.

Today’s habit is to make Claude Code decompose the issue before it writes code. Treat the issue as a case file, not an instruction. The goal is a verified workplan: what needs to change, where the evidence is, what can be tested, and what should be deliberately ignored.

The real task: a ticket that is underspecified

Imagine this issue: “CSV export on the orders page sometimes downloads an empty file. Add a fix and tests.” That sounds small, but it hides several questions. Is the empty file caused by filters, pagination, permissions, a race in the export job, or the frontend clicking before data is ready? If you ask Claude Code to “fix it,” it may choose the nearest button component and add a loading spinner. That might improve the UI while leaving the actual export bug untouched.

Start by giving Claude the issue and asking for a read-only decomposition. In Claude Code, I would begin from the repository root and write:

Prompt: “Read this GitHub issue and inspect the likely files. Do not edit anything yet. First, identify the user-visible failure, the code paths that could cause it, the missing assumptions, and the smallest verification commands we can run. Return a workplan with checkpoints, not a patch.”

If the issue references files, routes, or stack traces, include them explicitly with @file or @folder. For example: “Use @app/orders/export.ts, @app/orders/OrdersPage.tsx, and @tests/orders. Explain how export currently works before proposing changes.” This prevents Claude from roaming the whole repo and inventing architecture from filenames.

What the first response should contain

A useful decomposition has four parts. First, Claude should restate the failure in testable language: “When active filters are applied, the export request may be sent before filter state is committed, producing a CSV with headers only.” Second, it should list evidence: the component that builds export params, the API route that streams the CSV, and any test fixtures that create orders. Third, it should name uncertainties: “I do not yet know whether the backend accepts page filters or only full query filters.” Fourth, it should propose verification commands: “run npm test -- orders-export” or “run the API route test with the filtered-order fixture.”

This is where the TonBisa-style loop matters: prompt, inspect, find the gap, correct, verify. Do not reward Claude for sounding organized. Check whether the plan points at real files and executable commands. If it says “add tests” without naming the test file, ask for a narrower pass.

Second-pass correction before editing

The most valuable prompt comes after Claude gives you the first workplan:

Prompt: “Challenge this plan. Which step is most likely wrong? Which assumption would make the patch useless? Before editing, inspect the exact request payload and the existing tests. If the issue is frontend-only, explain why the backend is not involved; if not, split the fix.”

This second pass often catches the real problem. In our export example, Claude may discover that the frontend sends the right filters, but the backend ignores one field when building the CSV query. Or it may find the opposite: the backend is fine, but the button reads stale React state immediately after a filter change. Either way, you have prevented a cosmetic patch.

Turn the issue into a patch queue

Once the plan survives critique, ask Claude Code to convert it into a small queue. A good queue is not “implement export fix.” It is: 1) add or update a failing test that reproduces empty exports with filters, 2) run the focused test and confirm the failure, 3) patch the smallest file, 4) rerun the focused test, 5) run a broader related test, 6) review git diff for unrelated changes.

Use concrete commands inside the session. Ask Claude to run: !git status --short, !npm test -- orders-export, and !git diff -- app/orders tests/orders. The shell checks make the workplan accountable. If the focused test cannot run because the repo uses pnpm, Docker, or a different package name, that is not a minor detail; it is part of the plan and should be corrected before code changes continue.

Failure modes to watch for

The first failure mode is over-broad decomposition. Claude may turn one issue into a mini-roadmap touching auth, UI, API, tests, docs, and analytics. Push back: “Limit the first patch to the smallest behavior change that can close this issue. Move follow-ups into a separate note.”

The second failure mode is evidence-free confidence. Claude may infer a bug from a component name without reading the data flow. Fix that with: “Cite the exact files and functions that prove this path. If you have not read them, say so and read them now.”

The third failure mode is skipping the reproduction. If there is no failing test, log, screenshot, or manual reproduction step, the patch is a guess. Tell Claude: “Before editing, show me the failure signal we expect to change.”

Rule of thumb

A GitHub issue is not a command; it is an investigation brief. Use Claude Code to turn it into evidence, assumptions, verification commands, and a scoped patch queue. If the workplan cannot name the files, the failure signal, and the second-pass critique, it is too early to edit.