𝗦𝗽𝗲𝗰 𝗗𝗲𝗯𝘁 𝗗𝗼𝗲𝘀𝗻'𝘁 𝗗𝗶𝘀𝗮𝗽𝗽𝗲𝗮𝗿 𝗪𝗵𝗲𝗻 𝗬𝗼𝘂 𝗙𝗶𝘅 𝗜𝘁. 𝗜𝘁 𝗠𝗶𝗴𝗿𝗮𝘁𝗲𝘀.

Fixing a problem does not always kill it. Sometimes, you just move it somewhere else.

I recently audited a project to find spec debt. These are gaps in instructions that lead to bugs or bad AI behavior. I fixed seven specific items. After the fixes, the tests passed. Everything looked green.

But the debt did not vanish. It migrated from the feature files into the step definitions.

Here is what I learned from fixing these items:

  • Precision matters. Instead of saying "the response is fast," say "the response returns within 12 seconds of the order submission." This anchors the timing.
  • Avoid ambiguity. "Retried 2 times" is unclear. Does that mean 2 total attempts or 3? Use "no more than 2 charge requests total" to be certain.
  • Name the mechanism. Saying "the inventory is released" is vague. Specify that "the inventory service receives a release request for item X."
  • Remove false guarantees. If a step passes because a feature does not exist yet, remove the step. A passing test for a non-existent flow is a lie.
  • Define "correct." Never use words like "correct" or "proper" without hard values. Use "contains order_id 123" instead of "contains the right id."

I built a framework to find these issues. Ask these five questions for every scenario:

  • Who owns this scenario?
  • What decisions does this leave open?
  • Are all terms defined here?
  • Does this describe behavior or implementation?
  • What is missing from this description?

The biggest trap is the gap between text and code. You can write a perfect, precise instruction in your spec. But if your underlying code uses a shortcut to pass that test, you still have debt.

The spec says "create an order via API." The code actually just injects an order directly into a database to save time. The test passes, but the debt moved from the requirement to the implementation.

Do not try to write perfect specs the first time. Write them, audit them, and fix them.

Source: https://dev.to/diyaburman/spec-debt-doesnt-disappear-when-you-fix-it-it-migrates-d25

Optional learning community: https://t.me/GyaanSetuAi