/squid-triage-issue

name: squid-triage-issue
description: >-
  Bug intake — localise the suspected code, capture a deterministic reproducer, and emit a groomed
  bug task with a regression-test acceptance criterion, ready for /squid-implement-task or the
  full pipeline.
disable-model-invocation: true
argument-hint: <bug-description | path/to/report.md | #issue-or-NNN-slug>

Triage — turn a bug report into a groomed, fixable task

`/squid-implement-task` and `/squid-implement-night` both assume the spec is already shaped right. Bug reports rarely are: they read "X is broken" and need a reproducer, expected-vs-actual, code localisation, and a regression-test acceptance criterion before SWE / Tester can do anything useful with them. This skill produces that groomed bug task, then hands off.

You are the **triage orchestrator** — you may delegate exploration to sub-agents (Explore, general-purpose), but you do NOT write production code, do NOT write the regression test, and do NOT start the fix. Your output is the spec.

`$ARGUMENTS` is one of:

• A free-form bug description (paste-in customer report, stack trace, "X is broken when Y").
• A path to a markdown report (`docs/bugs/foo.md`).
• A tracker reference (`NNN-slug` in file mode, `#N` in gh mode).

If empty, ask the user for one before proceeding.

Read `AGENTS.md` first to confirm the active **tracker mode** (`file` or `gh`).

When NOT to use

• A feature request — use `/squid-plan` (PA grooming) directly.
• A refactor with no observable user impact — use `/squid-refactor`.
• A trivial typo or one-line bug you can fix right now in chat — just fix it.
• An incident still in progress — stabilise first, triage after.

Step 1 — Resolve the report

Identify what to triage from `$ARGUMENTS`:

1. **File path** → `cat` the report. 2. **Tracker reference** (`NNN-slug` file mode, `#N` gh mode) → load the existing record (`tasks/NNN-*.md` or `gh issue view N --json number,title,body,labels`). 3. **Free-form text** → use as-is. 4. **Empty** → ask: "What bug should I triage? (Paste the report, give me a path, or a tracker reference.)"

Echo the resolved report back to the user in one paragraph as confirmation. Don't block — proceed.

Step 2 — Localise

Spawn ONE Explore agent (or general-purpose if the report is vague enough that exploration needs interview-style breadth). Prompt sketch (adapt as needed):

Agent(
  subagent_type="Explore",
  prompt="""Bug report: {one-paragraph summary}.

  Find: (1) the module(s) most likely responsible — rank top-3 with file:line and a one-sentence reason; (2) existing tests covering this behaviour, by file:line; (3) recent commits touching the implicated files (`git log --since='4 weeks ago' -- <file>`) — recent changes correlate with regressions; (4) related closed PRs / issues (`gh search issues "<keyword>" --state closed`).

  Be specific. Report back as four bulleted lists. Do NOT propose fixes."""
)

Read the top-3 candidate file(s) yourself (cheap) before moving on — you want firsthand familiarity, not just the agent's summary. If localisation surfaces other bugs, file each as its own triage task — one bug per task.

Step 3 — Build the reproducer

A reproducer is the load-bearing artefact. Without one, the Tester can't verify a fix and the SWE is guessing.

Try, in this order:

1. **Re-derive from the report** — if the user already pasted exact steps, formalise them as a numbered list with concrete inputs. 2. **Ask the user** — if the report is vague ("the page is slow sometimes"), use `AskUserQuestion`. Two questions max:

• What exact input / state triggers it?
• What's the smallest path to observing it (URL, command, test invocation)?

3. **Synthesise from code** — if the user can't repro and the code makes the failure mode obvious, draft the reproducer as a failing test case (described in prose; you don't write it).

The reproducer must be **deterministic**. If it's only intermittent, mark it explicitly as `flaky-repro` and capture the conditions correlating with reproduction (load, state, time-of-day) — the AC then becomes "instrument so we can capture it next time," not "fix the bug." Be explicit about the difference.

Step 4 — Write the groomed bug task

Use this exact template. Frontmatter follows `squid-scaffold/specs/tracker-workflow.md`, so `/squid-implement-task` and `/squid-implement-night` accept it without re-grooming.

# Bug: {one-line title — observable user-visible symptom}

**Severity:** {S1 outage / S2 broken feature / S3 degraded / S4 cosmetic}
**Affected component(s):** {file paths or module names}
**First observed:** {date or commit ref, if knowable}

## Summary

One paragraph. What the user sees. Don't speculate on the cause here.

## Reproducer (deterministic)

1. {exact command / URL / inputs}
2. {next step}
3. ...

Expected: {what should happen}
Actual: {what does happen — include exact error message, status code, or output}

> If the bug is non-deterministic, replace this section with a `Flaky-repro` block listing the correlating conditions.

## Suspected localisation

- `path/to/file.py:42` — {one-sentence reason}
- `path/to/other.py:117` — {one-sentence reason}

> Hypotheses, not conclusions. The SWE will confirm or refute during fix.

## Out of scope

- {Things that look related but aren't part of this bug — explicit so the SWE doesn't expand scope.}

## Acceptance criteria

- [ ] **Regression test** added at `tests/.../test_<slug>.py` that fails on `main` and passes on the fix branch. Test name describes the symptom, not the implementation.
- [ ] Reproducer steps from above produce the expected behaviour after the fix.
- [ ] No unrelated behaviour changes (full unit + integration suite green).
- [ ] If `Severity ≤ S2`, a one-line note added to the project changelog / release notes.

## Notes for the SWE

- {Optional: hints from your localisation — e.g. "the bug appears only when feature flag X is on; check the branching in module Y".}
- {Optiona