The 3 Bug Types That Point Back to Your Spec

Closing the Ticket Isn't the Same as Closing the Problem

Most teams handle a bug report the same way: reproduce, fix, close. That flow is fine on its own, but the moment you close the ticket, the context behind the bug disappears with it. Three months later, the same root cause shows up again on a different screen.

The reason is simple: teams look at how to fix the bug, not why it happened. Fixing the code without tracing back to where the spec had a gap only stops that one instance — not the pattern.

Three Ways a Bug Can Happen

Before you fix anything, every bug report fits into one of three categories. Which one it falls into determines where the fix belongs and what prevents it from recurring.

1. Implementation Bugs

The spec is correct, but the code doesn't follow it.

Example: the spec says "deleting requires a confirmation dialog," but the app deletes immediately with no confirmation.

Where it goes: code review and expanded test coverage. The spec itself doesn't change.

2. Spec Bugs

The implementation matches the spec exactly, but the spec doesn't match how the product is actually used. This is the trickiest category — it gets reported as a bug, but treating it as an implementation issue only guarantees the same problem in the next similar feature.

Example: the spec allows ordering when stock is zero. Implemented exactly as written, but in practice this generates a steady stream of manual cancellation work.

Where it goes: update the acceptance criteria in SPEC.md or the ticket, then schedule the implementation change for the next release cycle.

3. Expectation Bugs

Neither the spec nor the implementation is wrong — the reporter's mental model just doesn't match the system's design. Usually a copy or feedback problem, not a logic problem.

Example: "Nothing happens when I click Save" — the app actually autosaves, but the screen never shows that it happened.

Where it goes: a small UI feedback or copy fix. No spec change needed.

A Quick Routing Checklist

• Implementation bug → assign to the engineer who owns that code; prevent recurrence with a new test case
• Spec bug → PM/PO updates the acceptance criteria, revises SPEC.md, then tickets the re-implementation
• Expectation bug → designer/frontend improves UI feedback; no spec change required

When you're unsure which bucket a bug belongs in, start with one question: "Does it behave exactly as the spec describes?" If yes, it's a spec bug or an expectation bug. If no, it's an implementation bug.

A Quarterly Retro Template

Once bugs are classified, tallying them quarterly reveals where your spec is weakest. Track three numbers each quarter:

• The ratio of implementation bugs to spec bugs to expectation bugs
• How many spec bugs actually made it into an updated SPEC.md or ticket
• Why the rest didn't (low priority, scope too large for this cycle, etc.)

Feature areas with a high spec-bug ratio need heavier acceptance-criteria review in the next design phase. Areas dominated by implementation bugs respond better to stronger test coverage instead.

Doing This With Bugoon

Bugoon's widget captures screenshots, annotations, and recorded interaction steps for every bug report, and pushes them straight into a GitHub Issue. The exact inputs you need to classify a bug — reproduction steps, actual behavior, and what the reporter expected — are already captured as structured fields, so you can revisit the classification later without reconstructing it from memory.

Bugoon's kanban board lets you track in-flight bugs at a glance; labeling the ones you've classified as spec bugs separately makes them easy to pull into the quarterly retro. Being able to tag the root-cause category directly on the report is one direction that could make that rollup even less manual.