create-issue

name	create-issue
description	Captures a defect as a Bug Report work item ready for /do, running the investigator first if the root cause isn't already established.
argument-hint	[bug title or one-line summary]
disable-model-invocation	true

Create Issue

Issue: $ARGUMENTS

Turn a defect the conversation has surfaced (typically via /discussion) into a lean Bug Report that /do can fix autonomously. The completion artifact is ./tmp/<id>/item.md with status: ready — diagnosis captured, fix delegated. This skill documents; it never fixes code.

Steps

1. Take stock of the investigation

Check what the conversation already established: reproduction, root cause + evidence, confidence level. A root-cause finding from an investigator dispatch during /discussion is the ideal input — reuse it, don't redo it.

If the root cause is not yet established, run the investigation now:

• Dispatch the investigator via the codex skill (role investigator) with the full report (expected vs actual, environment, known repro steps, traces); it returns its standard root-cause finding.
• If reproduction requires driving the running app, dispatch frontend-verifier first to exercise the flow and capture evidence, then pass its transcript along with the defect report.
• If the investigator cannot reproduce: say so plainly. Do not invent a cause. Either gather more from the user (logs, exact environment) and re-dispatch, or proceed with root cause marked Hypothesis: and what-was-tried captured in refs/.

Success criteria: a root-cause finding in hand with an honest confidence level (confirmed | likely | hypothesis) — or a documented failed-to-reproduce with the attempts listed.

2. Confirm impact and severity

Where judgment is needed, confirm with the user: who is affected, how widespread, why it matters now, and whether the suggested resolution path should be locked as a direction or left to /do. Skip the ceremony when severity is obvious.

Success criteria: severity (critical | high | medium | low) and business impact agreed with the user.

3. Write the Bug Report

Draft ./tmp/<id>/item.md per ~/.references/draft-work-item.md, using this skill's references/bug-report.md as the template. Bug specifics:

• Reproduction steps go in the report — deterministic enough for the verify stage to re-run them. Raw traces, logs, and long transcripts go to ./tmp/<id>/refs/ (e.g. refs/error-trace.txt), linked not inlined. If the investigation produced a current-state deep-dive worth keeping, save it per ~/.references/system-analysis.md as refs/system-analysis.md.
• Verification criteria must include:
  • AC1: the reproduction flipping from fail to pass — the repro steps double as the failing case the fix must flip.
  • Prevention criteria: what stops this class of bug recurring — a regression test, a custom lint/static rule (the most durable guard), or an invariant — verifiable, not aspirational.

Success criteria: item.md exists; repro is re-runnable; AC1 maps to the repro; prevention criteria present; raw material linked from refs/.

4. Socratic gate

Run the gate per ~/.references/socratic-gate.md. For a bug report it bears down on root cause vs symptom (does the cause survive another "why"?), evidence, whether the fix prevents the class or just this instance, and completeness — sibling instances of the same defect class elsewhere, or follow-up work this fix implies. A confirmed cause with a contained fix fast-passes with zero to two questions. If the dialogue surfaces a deeper cause to chase, re-dispatch the investigator before proceeding.

Success criteria: gate procedure complete — socrates returned pass (or the cap was reached, or the user waived); ## Justification written into item.md.

5. Mark ready and publish

Publish per ~/.references/publish-work-item.md — issue title fix: <bug title>, issue body = summary, severity, reproduction steps, root cause + confidence, and the Justification section. Exception: leave status: draft if the cause is still a hypothesis and the user wants more evidence first — publish happens either way, so the evidence trail lives with the issue.

Success criteria: published and cross-linked per the shared procedure.

Suggested next steps:
- `/do <issue # or ./tmp/<id>/item.md>` — run the autonomous pipeline to fix and verify
- `/discussion [topic]` — if the bug exposed a design question bigger than the fix