agentleFS
jaroslawherodjaroslawherod/micold-ai-ide/.claude/skills/speckit-bugfix-report/SKILL.md

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

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
  1. Very specific:

    Verify a spec-kit project exists by checking for .specify/ directory

    line 29
  2. Very specific:

    Verify at least spec.md exists

    line 31
  3. Distinctive:

    Load artifacts: Read from the current feature directory:

    line 35
  4. Very specific:

    Save report: Write the bug report to specs/{feature}/bugs/BUG-{NNN}.md where {NNN} is the next sequential bug number.

    line 92

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

$ARGUMENTS

You 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

  1. Verify a spec-kit project exists by checking for .specify/ directory
  2. Locate the current feature's spec directory (by branch name or most recently modified)
  3. Verify at least spec.md exists

Outline

  1. Load artifacts: Read from the current feature directory:
    • Required: spec.md (the specification)
    • Optional: plan.md, tasks.md, research.md, data-model.md
  2. Analyze the bug: From the user's description, classify the bug:

    Bug TypeDescriptionExample
    Spec gapRequirement missing from specAuth flow doesn't handle expired tokens
    Spec conflictTwo requirements contradict"Must be stateless" vs "Must track sessions"
    Implementation driftCode diverges from specSpec says REST, code uses GraphQL
    Untested flowEdge case not covered in success criteriaConcurrent user updates not handled
    Dependency issueExternal dependency behaves differently than assumedAPI response format changed
  3. 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?
  4. 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
  5. Save report: Write the bug report to specs/{feature}/bugs/BUG-{NNN}.md where {NNN} is the next sequential bug number. Create the bugs/ directory if it does not exist.
  6. 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.patch to 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.