SuperAPI AI Directory

github-issue-repro-and-fix

Coding & development

View repository

Updated 10-16 09:29

About this skill

GitHub Issue Repro And Fix

Use this skill when the user provides a GitHub issue URL, issue number, copied issue body, or asks whether reported behavior is truly a bug before fixing it.

Workflow

  1. Gather the issue context.

    • If given a URL or issue number, prefer gh issue view <number> --json title,body,comments,labels,author,state,url.
    • If gh is unavailable or unauthenticated, use the GitHub web page or ask the user only when the issue content cannot be accessed.
    • Read the issue comments, not just the opening report. Comments often contain maintainer guidance, reproductions, workarounds, duplicate links, and notes that the issue was fixed elsewhere.
    • Capture the exact reported behavior, expected behavior, environment, reproduction steps, linked repro repository or sandbox, maintainer comments, and any user-confirmed workarounds.
  2. Look for related upstream context.

    • Search repository issues, pull requests, and discussions for the issue number, mentioned APIs, error text, and reproduction keywords.
    • Prefer GitHub search or gh search issues/gh search prs when available.
    • Note related PRs, discussions, duplicate issues, regression reports, and changelog entries before deciding whether to patch.
    • If a related PR already fixed the issue, verify whether the local workspace contains that change before editing.
  1. Map the report to the codebase.

    • Identify the package, adapter, example, docs page, or shared core module involved.
    • Search with rg for mentioned APIs, options, error text, test names, and related implementation files.
    • Read the nearest tests before editing so the existing behavior contract is clear.
  2. Verify whether the reported behavior is real.

    • Reproduce the bug locally before changing implementation when feasible.
    • Prefer the smallest focused failing test over a full example app.
    • If a UI or framework issue cannot be captured by a unit test, use the smallest existing example or fixture that exercises the behavior.
    • Record the failing command and failure mode.
    • If the issue cannot be reproduced, inspect whether it is already fixed, invalid usage, version-specific, or missing information.
  3. Decide whether a fix is the correct library direction.

    • Separate "the reported behavior happens" from "the library should change."
    • Check whether the request conflicts with documented concepts, API semantics, type contracts, backwards compatibility, or maintainer comments.
    • Consider whether the better outcome is a code fix, documentation clarification, warning/error improvement, example update, or closing as intended behavior.
    • When the issue raises a product/API semantics tradeoff, ask the user for a decision before implementing. Present concise pros and cons for each viable path.
  4. Apply a focused fix only when the direction is confirmed.

    • Change the narrowest implementation surface that explains the confirmed failure.
    • Preserve public APIs unless the issue explicitly concerns an intended API change.
    • Follow existing local patterns for feature registration, state handling, adapter behavior, and test style.
    • Avoid broad refactors, unrelated formatting churn, or opportunistic cleanup.
  5. Prove the fix.

    • Run the previously failing test or reproduction first.
    • Run the nearest relevant package test, typecheck, or lint command if available and proportionate.
    • If a regression test was possible, commit the failing scenario as part of the change.
    • If no automated test was practical, document the manual verification steps and remaining risk.
  6. Report the outcome.

    • State whether the GitHub report is a confirmed bug, duplicate/already fixed, unsupported usage, documentation gap, or inconclusive.
    • If the behavior is real but not a bug, say that explicitly and explain the library contract that makes it intended behavior.
    • Summarize the root cause and fix in concrete terms.
    • Include the exact verification commands and results.
    • Call out any test gaps or conditions that could not be reproduced.

Decision Rules

  • Do not patch first and infer the bug later. Establish a failing observation before editing whenever the repo makes that practical.
  • Do not assume a confirmed reproduction means the requested change is desirable. Validate the request against the library's design model before fixing.
  • Treat linked reproductions as evidence, not as proof. Reduce them to a local test or minimal local reproduction before changing shared code.
  • If the issue is caused by misuse but the API makes the misuse easy, consider a docs update, runtime warning, or clearer type error only if it fits existing project conventions.
  • If the report depends on old package versions, compare against the current workspace behavior and say clearly which version was tested.
  • If the issue spans multiple framework adapters, fix shared core behavior first when the root cause is framework-agnostic; otherwise keep adapter-specific changes isolated.
  • Do not run git commands, create commits, push branches, or open pull requests. Leave all git and PR operations to the user.

Useful Commands

gh issue view <number> --json title,body,comments,labels,author,state,url
gh search issues "<query>" --repo TanStack/table
gh search prs "<query>" --repo TanStack/table
rg "<api-or-error-text>"
pnpm test
pnpm typecheck
pnpm lint

Prefer package-specific commands from package.json when they exist. Use the smallest command that validates the touched behavior before running broader checks.