Every ambiguity in your spec
is a token your agent burns.

What goes wrong without it.

• 🌀 Specs drift.

  The spec in the doc, the thread in Slack, and the code in the PR quietly disagree for weeks. Nobody can find which version of the conversation is canonical.

  The fix

  One canonical spec, in the repo, versioned with the code.specscore lint runs in CI on every push; git history is the audit trail. The spec, the thread, and the PR can't quietly disagree — they share the same file under review.

• 🌫️ AC stay vague.

  "Handles errors gracefully" was supposed to mean"show a toast and roll back." Or was it"log and retry?" The agent has to guess.

  The fix

  The linter catches ambiguous criteria before any code is written. The verb fails lint because it has no concrete object or condition. Fixing the warning forces you to write what "handles" actually means.

• 🤖 Agents ship the wrong thing.

  Humans interpolate, ask, clarify. AI agents don't — they implement whatever pattern was most common in their training data. The code passes review because it doessomething sensible. It's just not what you meant.

  The fix

  Structured input. AI agents parse REQ IDs, AC IDs andGIVEN / WHEN / THENscenarios deterministically — there's nothing to interpolate. Plans must cite the AC IDs each task satisfies, so what was built is always checkable against what was specified.

• 🔁 You pay twice for a vague spec.

  The agent builds something from an ambiguous brief, you notice it's wrong, and you re-prompt — four different ways. Every half-built feature and every retry is billed in tokens. The vaguer the spec, the more rounds before it lands.

  The fix

  Lint the spec before the agent runs. specscore lintrejects vague verbs and missing acceptance criteria up front, so the agent implements a concrete brief once instead of guessing across retries. The cheapest agent run is the one you don't repeat.

• 💸 Agents pay to re-read your specs.

  An AI agent answering "what depends on this feature?"reads the whole feature README. Then every parent index. Then sibling features just in case. Every query is a re-parse. Tokens evaporate; latency rises; the bill rises with them.

  The fix

  Structured queries instead of file reads.specscore feature tree returns the hierarchy as YAML; feature deps walks the transitive dependency chain; feature info exposes status, owner, and open questions — each in one call. The agent navigates the graph, not the prose.

• 🔗 Code forgets its spec.

  Six months later, you're debugging a function and nobody remembers which feature it implements. The link between code and spec lived in someone's head, and that person left. The PR that introduced it is in the archive.

  The fix

  Source annotations. Comments like// specscore: features/checkout/apply-discount/R1.AC-2make the link machine-readable and survive every refactor.specscore code deps answers"what spec does this file implement?" in one call; the linter flags references that point at deleted specs.

• 🏷️ Status changes leak.

  You move a feature from Draft to Approvedin its README, but the parent features-index still lists it as Draft. Three weeks later, an agent reading the index thinks it's still in flux. The status lives in two places now, and they disagree.

  The fix

  specscore feature change-status rewrites the feature's Status field and re-syncs the features-index row in one atomic step — lint failure rolls the rewrite back. The status exists in one canonical place; the index is a generated view of it.

• 📋 Specs forget what they don't know.

  A spec reads as if it's settled — until you remember the"and what about timezones?" question got lost in a Slack thread two months ago and never made it into the doc. Now you're in implementation, and nobody can say what the answer was.

  The fix

  Every SpecScore feature has a mandatoryOutstanding Questions section. The linter rejects features that omit it — empty is fine ("None at this time."), but missing isn't. Unresolved questions are visible in the doc, queryable from the CLI, and impossible to forget.