investigate-issue

name	investigate-issue
description	Investigate a GitHub issue end to end — reproduce the reporter's repo or code snippet in an isolated sandbox outside the monorepo, trace the root cause in the source, and draft a reply back to the reporter for the maintainer to confirm before posting. Use when the user says "investigate issue <n>", "look into issue <n>", "can you reproduce this", or wants a triage answer rather than a fix.

Turn a reported issue into a verified verdict: does it reproduce, why, and what should we tell the reporter? This skill owns reproduction, root-cause analysis, and drafting the response. It does not fix the bug (fix-issue) and it does not post anything to GitHub without explicit approval.

Take the issue number/URL from the user. If none is given, ask for it.

1. Read the issue

• gh issue view <n> --json title,body,state,labels,comments,author,createdAt. Plain gh issue view <n> may fail on this repo with a Projects-classic GraphQL error — use the --json form. gh api repos/analogjs/analog/issues/<n> also works.
• Pull out the facts that decide the investigation:
  • Versions — Analog, Angular, Vite, Nx, Node, and the package manager. The bug report template asks for an environment; if it's vague, note the gap now rather than guessing later.
  • Affected package — the reporter's dropdown answer is a hint, not a verdict. Confirm it from the stack trace and the code you end up reading.
  • The reproduction — a git repo, a StackBlitz link, a code snippet, or nothing.
• Search for prior art before spending time: gh issue list --search "<keywords>" --state all and git log --oneline --grep "<keywords>". An issue that a recent commit already fixed on beta is the single most common outcome — check that early.

2. Get the reproduction into an isolated sandbox

Never install or run a reporter's project inside this monorepo. pnpm-workspace.yaml will absorb it, its dependencies will resolve to workspace packages, and whatever you observe will be an artifact of your setup rather than their bug. Work in a scratch directory outside the repo (the session scratchpad, or mktemp -d).

By what the reporter gave you:

• Git repo → git clone --depth 1 <url> <sandbox>/repro, then install with the lockfile they committed (pnpm i --frozen-lockfile, npm ci, …). Their lockfile is evidence; replacing it changes the experiment.
• StackBlitz / CodeSandbox link → these can't be driven from here. If the project is backed by a git repo, clone that. Otherwise scaffold the equivalent locally: npm create analog@latest in the sandbox (template-minimal for a bare case, template-latest for a full app), then transplant the reporter's files.
• Code snippet only → build the smallest project that exercises it, same scaffold route. If the snippet is really about compiler or plugin behavior, a focused spec in the affected package (packages/<pkg>/src/**/*.spec.ts) is a faster and more durable reproduction than an app — prefer it when it can express the bug.
• Nothing → don't invent one. Try a good-faith minimal reproduction from the description; if it doesn't reproduce, that's a legitimate finding and the draft reply should ask for a repro rather than assert the bug isn't real.

Pin the reported versions first. Reproducing against the versions they named is the experiment; anything else is a different one.

3. Reproduce, and record what you actually ran

• Run the command from the issue — dev, build, test, storybook, whatever they reported — and capture the real output, not a paraphrase.
• Record the verdict plainly: reproduced, not reproduced, or partially reproduced (e.g. the error appears but only on build, not dev). "Partially" is a real answer and usually the most informative one.
• If it doesn't reproduce, vary one thing at a time — package manager, Node version against .node-version, Vite major, jit vs AOT, dev vs build vs SSR — and say which variable flipped it. A bug that only appears under one of these is a scoping fact the reporter needs.

4. Trace the root cause in this repo

• Once you can see the failure, find the code that causes it. Read the source — don't infer from the stack trace alone. Delegate broad searches to the Explore agent when the cause could live in several places.
• Cite evidence as file:line. A verdict without a line number is a hypothesis.
• Decide where the bug actually lives, and be willing to conclude it isn't ours:
  • Analog bug — our code does the wrong thing. Note every call path that hits it; a util with two callers usually needs both fixed.
  • Upstream (Angular, Vite/Rolldown, Nx, Nitro, Storybook) — say which project, and whether we can still be resilient to it on our side. Both can be true, and "we should tolerate this even though it's their bug" is a fine recommendation.
  • Usage / configuration — then the reply is documentation, not a patch. Check whether apps/docs-analog actually covers it; if it doesn't, that gap is the real finding.
• Check the current beta too, not just the reported version. If it's already fixed, identify the commit that fixed it — that's the whole answer.

5. Validate the diagnosis against local changes when it matters

When the diagnosis implies a specific fix and you want confidence before recommending it:

• Build the package into the workspace node_modules (that's its outputPath): nx build <package>.
• Pack it and install the tarball into the sandbox so the repro runs against your build: npm pack node_modules/@analogjs/<package> → install the resulting .tgz in the sandbox project.
• Re-run the failing command. A diagnosis that survives this is worth reporting as confirmed; one that doesn't is a hypothesis you should label as such.

This step is optional — skip it when the root cause is unambiguous from reading the source, and say you skipped it.

6. Draft the response — don't post it

Write the reply as a draft for the maintainer to review. Do not run gh issue comment, add labels, close, or reopen anything until the user explicitly approves.

Keep it short and concrete, in the maintainer's voice — direct, no filler thanks-for-the-report padding:

• Whether it reproduced, and under exactly what versions/commands.
• The root cause in one or two sentences, with the file:line evidence.
• Where it lives: our bug, upstream, or usage — and for upstream, whether we plan to be resilient anyway.
• What happens next: a fix is coming, a repro is needed, a doc will be updated, or it's already fixed on beta (name the commit).
• Any question the reporter has to answer for this to move.

Present the draft inline for approval. On approval, post with gh issue comment <n> --body-file <path>. If the reporter needs to supply something, say so once and clearly rather than hedging.

7. Report to the user, then hand off

• Summarize: reproduced or not, root cause with evidence, where it belongs, and your recommendation.
• If it's a real Analog bug and the user wants it fixed, hand off to fix-issue — it owns branching and implementation. Don't start editing packages/ from this skill.
• If the investigation turns up something adjacent (a second bug, a missing doc, a flaky path), flag it as its own issue instead of folding it in.

Notes

• Clean up sandboxes when you're done, and never point a sandbox's dependencies at the working monorepo except via a packed tarball.
• Report reproduction attempts faithfully. "I couldn't get their repo to install" is useful; a confident verdict built on a broken sandbox is not.
• Timebox variable-hunting. After a few honest attempts at reproducing, the better answer is a draft asking the reporter for the missing piece.