speckit.clarify: Structured Q&A to Clarify Golang Spec Details

speckit.clarify: Structured Q&A to Clarify Spec Details

speckit clarify is the command most often skipped by developers new to Spec Kit — and skipping it is the single biggest mistake they make when they cut speckit clarify golang spec ambiguity out of their workflow. Ten minutes of clarification buys back two hours of debugging.

This article walks through why the stage matters, how the AI analyzes a spec to surface ambiguity, and the answering techniques that turn a vague spec into an implementable one.

07.1 Why Clarification Matters

Every freshly written spec has gaps. Not because the author is incompetent — but because writing a spec means articulating something that hasn’t been built yet. Things that feel “obvious” to the author are ambiguous to everyone else, and to an AI.

Take a concrete example. The spec says “Search shows only active products.” That single sentence hides several unanswered questions:

• What is “active”? Status ACTIVE only, or also stock > 0?
• If a seller deactivates a product while an order is pending — what happens?
• Can “active” become system-calculated, or only a manual seller action?

Without answers, developers make their own decisions — and those decisions may quietly diverge from the business intention. Clarification exists to close that gap before a single line of Go is written.

07.2 Running specify clarify

The entry point is a single command against the feature you already specified. The snippet below runs the clarify pass on the product-search feature.

1specify clarify product-search

Spec Kit analyzes spec.md and surfaces questions grouped by category — Business Logic, Edge Cases, Race Conditions, Scope Boundaries, Performance Implications, and Security. For each question it presents options and saves your answer to both spec.md (as updates) and clarifications.md (as documented decisions). The takeaway: one command turns your prose spec into a guided interview that ends with a decision trail.

07.3 Question Categories

Before answering, it helps to know the six lenses through which the AI inspects a spec. Each category targets a different class of hidden risk:

Business Logic — ambiguities in business rules Edge Cases — scenarios not covered in the spec Race Conditions — concurrency scenarios Scope Boundaries — clarification of feature limits Performance Implications — decisions with performance trade-offs Security — security-related edge cases

Recognizing the category behind each question tells you who should answer it: business logic and security usually need a PM or tech lead, while performance and scope can often be deferred to the plan.

07.4 Answering Techniques

Good answers are not longer answers — they are structured ones. The first technique, STAR, forces you to expose the situation and trade-off behind a choice rather than just naming an option.

1Q: Should out-of-stock products appear in search?
2A: (S) Sellers sometimes deactivate temporarily for restocking
3   (T) Always-hide vs show-with-badge tradeoff
4   (A) Show with "Out of Stock" badge
5   (R) Better UX — customers can wishlist or check back

The value of STAR is that the reasoning survives with the decision, so six months later nobody re-litigates it. The second technique is knowing when an answer does not belong in the spec at all.

1Q: Should search results be cached?
2Good answer: "Delegate to technical plan. Implementation detail."

Deferring keeps the spec focused on behavior, not implementation, so caching can be decided after benchmarking. The third technique is to attach context to any qualitative judgment.

1Q: Speed vs accuracy priority?
2Good: "Speed priority. 95% accurate at 200ms beats 100% at 800ms.
3       Users expect instant search."

By quantifying the trade-off, you give the plan a concrete target instead of a vague preference — the difference between “make it fast” and a real p95 budget.

07.5 Priority of Questions

Not every question deserves equal effort. The tiers below tell you what must be resolved before planning and what can wait:

Priority 1 — MUST answer before plan:

• Business logic ambiguities (affect ACs)
• Security edge cases (affect validation)
• Data integrity scenarios (affect transaction boundary)

Priority 2 — Should answer:

• Edge cases likely to appear in production
• Scope boundaries

Priority 3 — Can defer to technical plan:

• Performance optimization strategy
• Caching decisions
• Infrastructure choices

The rule of thumb: never let a Priority 1 question slip into the plan unanswered, because a wrong assumption there propagates straight into your acceptance criteria and validation logic.

07.6 clarifications.md Content

Answers do not vanish into chat history — Spec Kit records them in a durable file. The document below shows the shape of a real clarifications.md.

 1# Clarifications: Product Search
 2
 3## Q1: Product "Active" Definition
 4**Answer:** ACTIVE status required. stock=0 still appears with "Out of Stock" badge.
 5**Impact:** Added AC2a to spec
 6
 7## Q2: Relevance Ranking
 8**Answer:** PostgreSQL ts_rank score
 9**Impact:** Added to spec: "Results ranked by ts_rank"
10
11## Q4: SKU Search
12**Answer:** Out of scope. Only name + description.
13**Impact:** Added explicit out-of-scope: "SKU search (SHOP-234)"

Notice each entry links an answer to a concrete spec impact. This file preserves institutional knowledge that would otherwise be lost in Slack or chat history — the audit trail for why the system behaves the way it does.

07.7 Useful Flags

The clarify command has flags to scope, filter, and extend the interview. The commands below cover the most common cases.

1specify clarify product-search --priority=high      # High priority questions only
2specify clarify product-search --questions=1,3,5   # Specific questions
3specify clarify product-search --skip=6            # Skip performance questions
4specify clarify product-search --add-question "Should search respect user blocklist?"
5specify clarify product-search --with-code=internal/product/  # Include existing code

The --with-code flag is the underrated one: it lets the AI clarify a spec against code that already exists, which is how you write a retroactive spec for a proof-of-concept without re-deriving its behavior by hand.

07.8 When Clarify Reveals Scope Changes

Sometimes a clarification question exposes that the feature was under-scoped from the start. The exchange below shows how a forgotten requirement resurfaces during clarify.

1Q: Should search also filter by price range?
2Developer: "Actually yes, PM mentioned this during planning..."
3→ Price filter was in scope but forgotten during specify feature!
4
5Correct action:
61. Answer "Yes, price filter is in scope"
72. Spec Kit adds new ACs to spec.md
83. Note: "Scope increased. PM approval needed."
94. Update Jira ticket

The lesson here is that clarify doubles as a scope audit: catching a missing requirement now costs one answer, whereas catching it after implementation costs a rewrite and a re-estimate.

07.9 Clarify as Team Review Mechanism

Beyond a solo activity, a clarify session is one of the cheapest team review tools you have. The snippet below shows two developers running it together.

1# Developer A writes spec, Developer B runs clarify together
2specify clarify product-search
3# (both on screen sharing)
4
5# More productive than:
6# Dev B: "What about edge case X?"
7# Dev A: "What do you mean?"
8# [5 minutes unproductive discussion]

Running clarify on a shared screen replaces an unstructured “what did you mean?” discussion with a structured, question-by-question walkthrough — the same review, but bounded and documented.

07.10 Optimal Timing

Clarify has a right moment in the workflow, and timing changes its value. Run it immediately after specify feature, before specify plan, and budget time by spec complexity:

• Simple CRUD spec: 5-10 minutes
• Business logic spec: 10-20 minutes
• Concurrency/security spec: 20-30 minutes

Never delay clarify. Plans built without clarification carry assumptions that may be wrong, code generated from a wrong plan becomes technical debt, and fixing it after implementation is the most expensive path of all.

07.11 How Clarify Feeds Into Plan

The payoff for clarifying is that the next command consumes your answers directly. The commands below show specify plan reading all three inputs.

1specify plan product-search
2# Reads: constitution.md + spec.md (updated) + clarifications.md
3
4# The plan accurately reflects clarification decisions:
5# - stock=0 handling in repository layer (from Q1 answer)
6# - ts_rank in SQL query (from Q2 answer)
7# - Empty category message in handler (from Q5 answer)

The contrast is stark: without clarify the plan carries assumptions that may be wrong; with clarify the plan is accurate and immediately implementable. Every answer you gave becomes a concrete design decision downstream.

07.12 Clarify Quality Report

Clarify can also grade its own output, which turns a subjective “is the spec good enough?” into a number. The report below summarizes a completed session.

1specify clarify product-search --report
2
3# Clarification Quality Report
4# Questions asked: 6 | Answered: 6
5# ACs added/modified: 3
6# Out-of-scope items clarified: 1
7# Spec completeness: 94% (from 71% before clarify)
8# Estimated implementation risk reduced: 43%

The most useful line is the completeness jump — moving from 71% to 94% is a measurable signal that the spec is now ready for planning rather than a gut feeling.

07.13 Common Questions by Domain

Over time you will notice the same clarify questions recur per domain. Keeping these in mind lets you pre-answer them in the spec and shorten the clarify pass:

E-commerce:

• What happens when a cart expires during checkout?
• How do you handle concurrent orders for a stock=1 product?
• Can prices change while an item is in the cart?

Authentication:

• How long is a JWT valid?
• What happens when a refresh token expires?
• Can users log in from multiple devices?

Notifications:

• What happens if an email bounces?
• How many retry attempts for a failed notification?
• Can users opt out of specific notifications?

The takeaway: these are the questions clarify will ask anyway, so writing them into the spec up front means clarify spends its budget on the genuinely novel ambiguities instead.

07.14 Saving Answers as Institutional Knowledge

Because clarifications are stored as files, they become searchable long after the feature ships. The commands below query past decisions.

1# clarifications.md is automatically saved and searchable
2specify search "stock=0 visibility"
3# → Finds: product-search/clarifications.md Q1
4# → Finds: cancel-order/clarifications.md Q3

Six months from now, when someone asks “why does a stock=0 product still show in search?”, the answer is one search away in clarifications.md — not lost in a Slack thread nobody can find.

07.15 Tips & Gotchas

A few habits separate a clarify pass that adds value from one that just burns time:

💡 Tip 1: Don’t skip clarify even for “simple” features — apparently simple features often have hidden edge cases.

💡 Tip 2: Answer business logic questions with the PM and tech lead — don’t make business decisions alone.

💡 Tip 3: Use “Delegate to plan” for technical decisions — cache strategy, database indexes, and event schemas belong in the plan.

💡 Tip 4: Share “surprising” answers in standup — if an answer surprised you, it may surprise others too.

⚠️ Gotcha 1: Rushing clarify = missing edge cases — take time to think through each question.

⚠️ Gotcha 2: Answers contradicting the constitution — flag this; the constitution may need updating.

⚠️ Gotcha 3: Not all questions are relevant to the current sprint — mark out-of-scope items clearly.

⚠️ Gotcha 4: Clarify ≠ design session — if clarify becomes a redesign discussion, stop and schedule a proper design meeting.

07.16 The Clarification → Plan Connection

To see why clarify quality matters so much, trace how a single answer ripples through the plan. The flow below shows two answers expanding into concrete plan decisions.

1Q1 answer: stock=0 shows "Out of Stock" badge
2→ Plan: handler maps stock=0 to "OUT_OF_STOCK" enum
3→ Plan: SQL adds stock column to SELECT list
4→ Plan: response DTO adds is_available bool field
5
6Q2 answer: PostgreSQL ts_rank for relevance
7→ Plan: SQL uses ts_rank(to_tsvector(...), query) AS rank ORDER BY rank DESC
8→ Plan: GIN index on (tsvector_column)

Each terse answer fans out into multiple design decisions across layers. That amplification is exactly why the quality of your clarification answers determines the quality of your technical plan.

07.17 Clarify for Microservice Boundaries

Features that cross service boundaries get their own class of clarification question — usually about data ownership. The exchange below resolves who owns product data.

1Q: Who owns canonical product data — Product Service or Search Service?
2A: Search Service maintains its own optimized read model, synchronized via Kafka events.
3→ Plan will show Kafka consumer setup for product created/updated events
4→ Plan will show a separate search_products table optimized for text search

Answering the ownership question at spec time pins down the integration pattern — event-driven read model versus shared database — before the plan commits to a schema you cannot easily undo.

07.18 Post-Clarify Spec Quality

A well-clarified spec looks visibly different: it carries an explicit status and a decision table. The excerpt below shows the ideal end state.

 1## Status: CLARIFIED (ready for plan)
 2
 3## Key Decisions from Clarification
 4
 5| Decision | Choice | Rationale |
 6|----------|--------|-----------|
 7| stock=0 visibility | Show with badge | Better UX for wishlist |
 8| Relevance ranking | PostgreSQL ts_rank | Sufficient for phase 1 |
 9| SKU search | Out of scope | Seller-only feature (SHOP-234) |
10| Cache strategy | Delegate to plan | Implementation decision |

The decision table is the artifact reviewers actually read — it compresses the whole clarify session into a scannable summary of what was decided and why, which is what makes the spec “ready for plan.”

07.19 Integrating with Project Management

Clarify decisions can flow straight into your tracker so non-engineers see the outcome. The commands below post a summary to Jira.

1# Save clarification decisions to a Jira comment
2specify clarify product-search --jira=SHOP-123
3
4# Auto-comment: "Spec clarification completed. Key decisions:
5# - stock=0 products show 'Out of Stock' but visible
6# - Ranking uses PostgreSQL ts_rank
7# - SKU search is out of scope (SHOP-234)"

Pushing the decisions to Jira closes the loop with product management — the people who need the “what did we decide” summary rarely open clarifications.md, but they will read a ticket comment.

07.20 Summary

specify clarify is the most underestimated but highest-value stage in the Spec Kit cycle. Ten to twenty minutes of clarification produces a significantly more complete spec and a significantly more accurate plan.

What Spec Kit does: analyzes spec.md, identifies ambiguities across business logic, edge cases, and concurrency scenarios, then asks structured questions.

Best answers: concrete, backed by rationale, and aware of when to defer to the technical plan.

Output: an updated spec.md plus a clarifications.md that documents every decision.

Never skip this step. The time saved from clarification always exceeds the time spent answering its questions — and the plan you build next inherits every bit of that clarity.