| 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 | |
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:
- File path →
cat the report.
- 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).
- Free-form text → use as-is.
- 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:
- Re-derive from the report — if the user already pasted exact steps, formalise them as a numbered list with concrete inputs.
- 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)?
- 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".}
- {Optional: explicitly forbidden fix shapes — e.g. "do not add a try/except that swallows the underlying exception; surface it properly".}
Severity heuristic (don't over-think — the user can correct):
- S1 — production outage / data loss / security exposure.
- S2 — a documented feature is broken; users hit it on the golden path.
- S3 — a documented feature is degraded; workarounds exist.
- S4 — cosmetic / docs / typo.
Step 5 — File the task
Where it lands depends on tracker mode (read from AGENTS.md).
File mode
Allocate NNN per squid-scaffold/specs/tracker-workflow.md. Write to:
tasks/NNN-bug-<slug>.md
Open the file with YAML frontmatter (status: pending, feature: bug-<slug>), then the groomed body from Step 4.
gh mode
gh issue create \
--title "Bug: {one-line title}" \
--label "bug,triaged" \
--body "$(cat <<'EOF'
{the entire groomed-bug body, minus the # H1}
EOF
)"
Capture the issue number for Step 6.
Step 6 — Hand-off recommendation
Surface a single decision block to the user:
## Triage complete — {bug title}
**Filed:** {tracker path or issue URL}
**Severity:** {S1–S4}
**Suspected files:** {top 1–3}
### Recommended next step
{Pick ONE based on severity + scope:}
- **Severity S1 / S2, narrow scope (≤2 files), reproducer is deterministic** → `/squid-implement-task {ref}` — supervise the fix in real time. Fastest path; you watch the diff.
- **Severity S3 / S4, OR scope spans multiple files / tasks, OR a regression test will need its own design conversation** → `/squid-plan {ref}` then `/squid-implement-night` — full pipeline. The PA decomposes into tasks; you only gate the plan and the merge.
- **Severity S1 production-down** → fix live yourself; this groomed task becomes the postmortem record, not the entry point.
### Open questions for the human
- {if any — list them. Otherwise omit this section.}
Hand control back. Do NOT auto-invoke /squid-implement-task or /squid-implement-night — the user approves the groomed task first; this skill stops at filing.
