spec-kit-bugfix

A Spec Kit extension that adds a structured bugfix workflow — capture bugs discovered during implementation, trace them to spec artifacts, and surgically patch specs without regenerating from scratch.

Problem

When bugs surface during implementation, the SDD workflow breaks down:

• No structured way to capture bugs and trace them back to spec requirements
• Spec gaps and conflicts are discovered but not recorded anywhere
• Developers fix code without updating spec, plan, or tasks — causing artifact drift
• Tasks marked complete turn out to be wrong, but there is no reopen mechanism
• No way to verify that bugfix changes are consistent across all artifacts

Solution

The Bugfix Workflow extension adds four commands that close the gap between bug discovery and spec correction:

Installation

specify extension add bugfix --from https://github.com/Quratulain-bilal/spec-kit-bugfix/archive/refs/tags/v1.1.0.zip

Bug Types

The extension classifies bugs into five categories:

Workflow

Bug discovered during /speckit.implement
       │
       ▼
/speckit.bugfix.report     ← Capture bug, trace to artifacts, classify
       │
       ▼
/speckit.bugfix.patch      ← Surgically update spec, plan, tasks
       │
       ▼
/speckit.bugfix.verify     ← Confirm all artifacts are consistent
       │
       ▼
/speckit.implement         ← Resume implementation with corrected specs

Use /speckit.bugfix.switch <spec-id> if the bug is discovered after the feature branch has been destroyed.

Commands

/speckit.bugfix.report

Captures a bug and produces a structured report with full artifact traceability:

• Classifies the bug type (spec gap, conflict, drift, untested flow, dependency)
• Maps to affected user stories, requirements, and tasks by ID
• Identifies root cause (spec oversight, changed requirement, or implementation error)
• Saves report to specs/{feature}/bugs/BUG-{NNN}.md

/speckit.bugfix.patch

Surgically updates spec artifacts based on a bug report:

• Adds missing requirements to spec.md under the affected user story
• Marks conflicting text with strikethrough and reason (never deletes)
• Reopens falsely completed tasks with (reopened — BUG-NNN) annotation
• Adds new tasks with sequential IDs and proper dependencies
• Updates Wave DAG if present
• Tracks all changes with bugfix notes and dates

/speckit.bugfix.switch

Switches the active bugfix context when working with multiple bugs:

• Lists all available bug reports for the current feature
• Allows selection of a different bug to make active
• Updates the bugfix context to the selected bug
• Enables working on multiple bugs sequentially without losing progress
• Restores previous context when switching back

/speckit.bugfix.verify

Read-only consistency check after patching:

• Verifies all bug reports are patched
• Checks spec requirements have corresponding plan sections and tasks
• Confirms reopened tasks are properly annotated
• Validates task ID sequencing and dependency DAG
• Reports cross-artifact traceability status

Hooks

The extension registers an optional hook:

• after_implement: Runs bugfix consistency check after implementation completes

Design Decisions

• Report before patch — always capture and classify the bug before modifying artifacts
• Surgical updates — only change what is necessary, never regenerate from scratch
• Never delete content — superseded text gets strikethrough, preserving history
• Reopen, don't delete tasks — falsely completed tasks are reopened with annotation
• Bug report files — each bug gets its own file for traceability and history
• Consistent with Spec Kit patterns — uses the same refinement note format and staleness tracking

Requirements

• Spec Kit >= 0.4.0

Related

• Issue #619 — New /bugfix Slash Command (25+ upvotes, maintainer-approved as extension)

License

MIT