Spec-Driven Development
PrefaceAI Rulesriazhelp.com
Spec-Driven Development › Module 2: Authoring Machine-Readable Specs
Module 2: Authoring Machine-Readable Specs

Chapter 8: The Interactive Clarification Loop: Using AI to Critique Your Specs

By Muhammad Riaz

The Fallacy of the Perfect First Draft

Human software architects, tech leads, and product managers share a common vulnerability: blind spots.

When drafting a feature specification, a human engineer naturally focuses on the core user journey—the "happy path." We intuitively understand how the system should work when inputs are clean, services are responsive, and networks are stable. However, humans are notoriously poor at anticipating every edge case, race condition, state conflict, or boundary condition across complex, distributed codebases.

If you take a human-authored specification that contains hidden logical gaps and feed it directly into an AI coding agent, the AI will not stop and politely inform you that your spec is incomplete. Instead, it will fill those logical gaps with probabilistic guesses. The result is the exact problem we set out to eliminate: the Ambiguity Tax.

The solution is not to spend days attempting to write flawless specifications in isolation. The solution is The Interactive Clarification Loop.

Before writing a single line of implementation code, you use the AI model's immense pattern-recognition capabilities against your specification file. You turn the AI from an obedient code-generator into an adversarial reviewer whose sole job is to interrogate your spec, expose hidden assumptions, and force you to resolve ambiguities upfront.

Mechanics of the Clarification Loop

The Clarification Loop is an interactive, multi-turn dialogue conducted strictly at the specification level. It sits between drafting your .spec.md file and generating your architecture .plan.md file.

┌─────────────────────────────────────────────────────────────────────────────┐
│                       THE CLARIFICATION LOOP                                │
│                                                                             │
│  [ Human Author ] ──> Drafts Initial `.spec.md`                             │
│                           │                                                 │
│                           ▼                                                 │
│  [ Adversarial AI] ──> Scans Spec & Codebase for Ambiguities & Edge Cases    │
│                           │                                                 │
│                           ▼                                                 │
│  [ Human Author ] ──> Answers Clarifying Questions & Hardens Spec             │
│                           │                                                 │
│                           ▼                                                 │
│  [ Final Spec ]    ──> Approved for Plan & Code Generation                  │
└─────────────────────────────────────────────────────────────────────────────┘

By forcing the AI to critique the specification before generating code, you shift the cost of discovering edge cases from expensive runtime debugging down to cheap text edits.

The Four Diagnostic Probes: How AI Stress-Tests Specs

When conducting a Clarification Loop, instruct the AI model to analyze your specification across four specific operational dimensions:

1. The State Transition Probe The AI identifies unhandled state conflicts.

  • Example AI Critique: "Your spec defines states PENDING, PROCESSING, COMPLETED, and FAILED. What happens if a user submits a cancellation request while the transaction is currently in the PROCESSING state? Should the system issue an immediate roll-back, or block cancellation until processing terminates?"

2. The Data Edge-Case Probe

The AI identifies nullability, boundary limit, and concurrency gaps.

  • Example AI Critique: "Requirement FR-3 specifies that bulk user import accepts up to 1,000 records. What happens if a uploaded CSV contains duplicate email addresses within the same payload? Should the service reject the entire batch, process the first occurrence, or fail silently on duplicates?"

3. The Dependency & Infrastructure Probe

The AI identifies third-party timeout and network failure modes.

  • Example AI Critique: "You specified integrating with the external tax calculation API during checkout. If the tax service times out after 3.0 seconds, should the checkout process throw an error to the customer, fallback to a cached default rate, or allow the order to proceed with zero tax applied?"

4. The Security & Tenant Isolation Probe

The AI identifies missing authorization boundaries.

  • Example AI Critique: "Requirement FR-1 allows fetching order details by order_id. However, the spec does not explicitly state how admin users belonging to parent organizations access child tenant orders. Should authorization be strictly restricted to auth.user.tenant_id, or should role-based multi-tenant override policies apply?"

The Master Clarification Prompt Template

To run an effective Clarification Loop, do not ask open-ended questions like "Is this spec good?" Instead, execute this structured system prompt against your draft .spec.md file using your preferred AI CLI or chat interface:

# SYSTEM ROLE: Adversarial Systems Architect & Spec Auditor

I am providing you with a draft feature specification (`01-spec.md`) and access to our codebase context.

Your objective is NOT to write any code yet. Your sole task is to CRITIQUE and STRESS-TEST this specification to identify hidden gaps, ambiguities, missing edge cases, and architectural risks.

Please analyze the spec and respond with a structured audit addressing:

1. AMBIGUITY IDENTIFICATION: Point out any requirements that could be interpreted in more than one way by an automated coding agent.
2. MISSING EDGE CASES: Identify at least 3 edge cases (network failure, bad inputs, concurrency, null states) that this spec fails to handle.
3. CONTRADICTIONS: Highlight any business rules that conflict with existing codebase patterns or invariants.
4. SCOPE BOUNDARY GAPS: Point out areas where an unguided AI might attempt to over-engineer or add unrequested features.

End your response with a numbered list of up to 5 concise, direct questions that I (the human architect) MUST answer to make this specification 100% deterministic.

Real-World Case Study: Refining an Auth Service Spec

To see the Clarification Loop in action, let us review an actual refactoring session for a Password Reset Feature.

Step 1: Initial Human Spec (Draft 1)

The developer writes a brief draft spec:

"Users can request a password reset email. The email contains a link with a token. Clicking the link lets the user set a new password."

Step 2: The AI Clarification Critique

The developer runs the Master Clarification Prompt against Draft 1. The AI responds:

Spec Audit Findings:

  1. Expiration Ambiguity: How long is the password reset token valid?

  2. Security Vulnerability (Enumeration): If an unregistered email is submitted, should the API return HTTP 404 (revealing registered users) or HTTP 200 with a generic message?

  3. Token Reuse: Can a password reset token be used multiple times before expiration?

  4. Session Invalidation: When a password is successfully reset, should existing active JWT refresh tokens for that user be revoked immediately across all devices?

Step 3: Human Resolution & Spec Hardening

The developer reads the AI’s critique and updates 01-spec.md directly:

<!-- Hardened Spec Additions resulting from Clarification Loop -->

- **FR-SEC-1 (Anti-Enumeration):** Submitting an unregistered email to `/api/v1/auth/reset-request` MUST return `202 Accepted` with payload `{ "message": "If the email exists, a reset link has been dispatched." }`.

- **FR-SEC-2 (Token Lifetime):** Tokens MUST expire exactly 15 minutes after generation and MUST be single-use. Successful token consumption MUST set `used_at = NOW()`.

- **FR-SEC-3 (Global Session Invalidation):** Upon password update confirmation, the service MUST revoke all active refresh tokens associated with `user_id` in Redis.

The Outcome

By spending 6 minutes reviewing the AI’s clarification critique and updating the markdown file, the developer eliminated four major security flaws and edge-case failures before any code was generated.

The Rule of One Turn: Avoiding "Spec Paralysis"

While the Clarification Loop is extremely powerful, it is important not to fall into Spec Paralysis —spending hours endlessly refining specifications for simple, low-risk features.

To maintain maximum velocity, follow The Rule of One Turn:

  • For Low-Risk / Isolated Features (Level 1 SDD): Execute one turn of the Clarification Loop. Ask the AI for edge cases, answer the top 3 questions, update your spec, and immediately move to planning (02-plan.md).

  • For High-Risk / Architecture-Critical Features (Level 2/3 SDD): Execute up to two turns. Conduct a formal review of the hardened spec with a human teammate before approving plan generation.

If an AI tool asks questions that delve into hyper-specific implementation syntax or framework choices during the Clarification Loop, defer those answers to the Architecture Plan (02-plan.md) phase. Keep the specification focused purely on What, Why, and Boundaries.

Practical Exercises: Conducting a Clarification Loop

  1. Audit a Draft Spec: Take the .spec.md file you created in Chapter 5. Run the Master Clarification Prompt Template against it using your AI tool.

  2. Identify Your Top 3 Blind Spots: Review the AI’s diagnostic questions. How many of the edge cases pointed out by the AI had you omitted from your original draft?

  3. Refactor and Lock: Update your .spec.md file with explicit answers to the AI’s questions. Verify that all requirements are now 100% deterministic before proceeding to module execution.

Module 2 Summary & Looking Ahead

Congratulations! You have completed Module 2: Authoring Machine-Readable Specifications.

Across these chapters, you have learned:

  • How to construct the 7 core elements of a production-grade .spec.md file (Chapter 5).

  • How to set hard scope boundaries, dependency prohibitions, and file access restrictions (Chapter 6).

  • How to enforce technical precision using interface contracts, Zod/Pydantic schemas, and system invariants (Chapter 7).

  • How to use AI adversarially through The Interactive Clarification Loop to expose blind spots before generating code (Chapter 8).

In Module 3, we move from Intent to Execution. We will explore From Spec to Plan—Systematic Execution: learning how to architect .plan.md files, construct atomic .tasks.md execution lists, establish human review gates, and leverage modern open-source toolkits like GitHub Spec Kit (specify).

How would you like to proceed?

We can now begin Module 3: From Spec to Plan—Systematic Execution with Chapter 9: Architecting the .plan.md : Mapping File Impact and Systems. Let me know when you are ready!