Bug Triage Workflow Extension

A three-step bug triage workflow for Spec Kit: assess, fix, and validate. Each bug lives in its own directory under .specify/bugs/<slug>/, with one Markdown report per stage.

Overview

This extension delivers an opinionated, repeatable bug workflow that any AI coding agent can drive:

1. Assess — read a bug report (pasted text or a URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.
2. Fix — apply the proposed remediation and record exactly what changed.
3. Test — re-run the reproduction and any added tests, then record the verification result.

The three stages communicate through three Markdown files in a single per-bug directory:

.specify/bugs/<slug>/
├── assessment.md   # written by speckit.bug.assess
├── fix.md          # written by speckit.bug.fix
└── test.md         # written by speckit.bug.test

Commands

Slug Conventions

A slug is the per-bug directory name under .specify/bugs/. It is the only handle the three commands share.

• User-provided: any shape the user wants, normalized to lowercase kebab-case (e.g. login-timeout, cve-2026-001, oauth-redirect-500). The slug is preserved verbatim after normalization — no timestamps or numbers are appended automatically.
• Asked for: in interactive use, speckit.bug.assess asks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary.
• Automated: when no human is available to answer, the agent generates a slug itself. The generated slug MUST produce a unique directory — if .specify/bugs/<slug>/ already exists, the agent appends the shortest disambiguating suffix needed (-2, -3, …) or a short date (-20260605). Existing bug directories are never overwritten.

Installation

# Install the bundled bug extension (no network required)
specify extension add bug

Disabling

# Disable the bug extension
specify extension disable bug

# Re-enable it
specify extension enable bug

Typical Flow

# 1. Triage a bug from a pasted stack trace
/speckit.bug.assess "TypeError: cannot read properties of undefined (reading 'token') at /auth/callback"

# 2. Triage a bug from a GitHub issue URL
/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token

# 3. Apply the proposed fix
/speckit.bug.fix slug=callback-token

# 4. Validate the fix
/speckit.bug.test slug=callback-token

Guardrails

• speckit.bug.assess and speckit.bug.test never modify source code. They read the repository and write only inside .specify/bugs/<slug>/.
• speckit.bug.fix is the only command that edits source code, and it stays within the files listed in the assessment unless new evidence requires expanding scope (which is logged in fix.md under Deviations from Assessment).
• None of the commands overwrite an existing report file without explicit confirmation; in automated mode they refuse and pick a new unique slug instead.
• Verdicts and verification results are never over-claimed: a reproduction that was not actually performed is reported as partial or not-run, not verified.

Hooks

This extension registers no hooks. The three commands are always invoked explicitly by the user.