speckit-bugfix-report
Skill1 starsChanged 3 days agoApache-2.0View on GitHub
Capture a bug and trace it back to the relevant spec, plan, and task
In this repository28 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- autopilot-supervisorSkill
- reclaim-diskSkill
- speckit-analyzeSkill
- speckit-autopilotSkill
- speckit-bugfix-patchSkill
- speckit-bugfix-switchSkill
- speckit-bugfix-verifySkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-docguard-diagnoseSkill
- speckit-docguard-fixSkill
- speckit-docguard-generateSkill
- speckit-docguard-guardSkill
- speckit-docguard-reviewSkill
- speckit-docguard-scoreSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-tdd-planSkill
- speckit-tdd-runSkill
- speckit-tdd-setupSkill
- speckit-tdd-verifySkill
- visual-passSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
Verify a spec-kit project exists by checking for .specify/ directory
- Very specific: line 31
Verify at least spec.md exists
- Distinctive: line 35
Load artifacts: Read from the current feature directory:
- Very specific: line 92
Save report: Write the bug report to specs/{feature}/bugs/BUG-{NNN}.md where {NNN} is the next sequential bug number.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Bugfix Report Skill
Report Bug
Capture a bug discovered during implementation and trace it back to the relevant specification artifacts. Produces a structured bug report that maps the issue to spec requirements, plan sections, and tasks.
User Input
$ARGUMENTSYou MUST consider the user input before proceeding (if not empty). The user describes the bug — what went wrong, error messages, unexpected behavior, or a gap discovered during implementation.
Prerequisites
- Verify a spec-kit project exists by checking for
.specify/directory - Locate the current feature's spec directory (by branch name or most recently modified)
- Verify at least
spec.mdexists
Outline
- Load artifacts: Read from the current feature directory:
- Required:
spec.md(the specification) - Optional:
plan.md,tasks.md,research.md,data-model.md
- Required:
Analyze the bug: From the user's description, classify the bug:
Bug Type Description Example Spec gap Requirement missing from spec Auth flow doesn't handle expired tokens Spec conflict Two requirements contradict "Must be stateless" vs "Must track sessions" Implementation drift Code diverges from spec Spec says REST, code uses GraphQL Untested flow Edge case not covered in success criteria Concurrent user updates not handled Dependency issue External dependency behaves differently than assumed API response format changed - Trace to artifacts: Map the bug to specific sections in each artifact:
- spec.md: Which user story, requirement, or success criterion is affected?
- plan.md: Which plan section covers this area?
- tasks.md: Which task(s) relate to this area? Are any marked complete that shouldn't be?
Generate bug report: Output a structured report:
# Bug Report: [Short Title] **Type**: [Spec gap | Spec conflict | Implementation drift | Untested flow | Dependency issue] **Severity**: [Critical | High | Medium | Low] **Feature**: [Feature name/branch] **Reported**: [DATE] ## Description [User's bug description, clarified and structured] ## Artifact Traceability ### spec.md - **Affected user story**: [Story N — title] - **Affected requirements**: [List specific requirements] - **Gap identified**: [What is missing or wrong in the spec] ### plan.md - **Affected sections**: [List plan sections] - **Impact**: [What needs to change in the plan] ### tasks.md - **Affected tasks**: [Task IDs and descriptions] - **False completions**: [Tasks marked done that need reopening] - **Missing tasks**: [New tasks needed to fix the bug] ## Root Cause Analysis [Why this bug exists — was it a spec oversight, changed requirement, or implementation error?] ## Recommended Fix 1. Run `/speckit.bugfix.patch` to update spec artifacts 2. Run `/speckit.bugfix.verify` to confirm consistency 3. Resume `/speckit.implement` to apply the code fix- Save report: Write the bug report to
specs/{feature}/bugs/BUG-{NNN}.mdwhere{NNN}is the next sequential bug number. Create thebugs/directory if it does not exist. - Report: Output the bug report and suggest next steps.
Rules
- Always trace to artifacts — every bug must map to at least one spec section
- Never modify spec artifacts — this command only reports, use
/speckit.bugfix.patchto make changes - Sequential numbering — bug reports are numbered BUG-001, BUG-002, etc.
- Classify accurately — distinguish between spec gaps (missing requirements) and implementation drift (code doesn't match spec)
- Be specific — reference exact user story numbers, requirement text, and task IDs
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

