Overview

Chapter 02: Automated Requirements Engineering & Spec-Kit PRD Synthesis

Playbook Track: 04 – AI Coding & Software Engineering (AI-DLC & Autonomous Developer Workflows)
Target Audience: Year 1 Computer Science & Software Engineering Students Core Tooling Stack: Gemini 2.5 Pro, Spec-Kit, Gherkin / Cucumber BDD, JSON Schema Draft 2020-12, Python 3.11+
Delivery Status: 🔍 Ready for Review (Tier 1 Markdown)

1. The Big Picture & Real-World Analogy

The IKEA Blueprint Analogy

Imagine ordering a desk from IKEA. Inside the box, you open the instruction manual:

• The Disaster Version: A single sheet of paper with one sentence: "Build a nice, sturdy, modern desk that holds your laptop comfortably."
  There are no screw measurements, no pre-drilled hole diagrams, and no weight limits. If three different people try to assemble that desk, one will glue the legs on upside down, one will build a wobbly coffee table, and the third will quit in frustration.
• The Production Blueprint: The actual IKEA booklet shows exact diagrams: "Step 4: Insert 4x M6 wooden dowels into holes A, B, C, D on panel 2. Tighten with the included hex wrench until flush." Anyone in the world can build the exact same desk with zero confusion.

In software engineering, when a human manager tells an AI coding agent:

"Build a fast, scalable, user-friendly refund button for our store."

The AI agent will hallucinate random assumptions! It will guess what "fast" means, invent arbitrary database column names, forget to check if the user actually has enough money to refund, and create bugs that cost real money.

Requirements Engineering with Spec-Kit turns fuzzy conversational ideas into an unambiguous, machine-executable blueprint (spec.md) before a single line of code is written.

2. Engineering Jargon Demystifier Table

3. The 5-Minute Micro-Lab: The Ambiguity Linter

Run this zero-dependency Python script to see how an automated linter catches fuzzy words in requirements:

"""
Micro-Lab: Requirements Ambiguity Linter
PB-04 Chapter 2 Micro-Lab (Zero External Dependencies)
"""
import re

VAGUE_TERMS = {
    "fast": "Specify exact latency bound (e.g. P99 < 250ms)",
    "scalable": "Specify exact throughput target (e.g. 5,000 requests/sec)",
    "user-friendly": "Specify UI workflow steps or accessibility standard",
    "seamless": "Specify authentication protocol or token exchange",
    "reliable": "Specify uptime SLA (e.g. 99.9% availability)"
}

def lint_requirement(text: str) -> dict:
    findings = []
    words = re.findall(r"\b[a-zA-Z\-]+\b", text.lower())
    for w in words:
        if w in VAGUE_TERMS:
            findings.append({"term": w, "remediation": VAGUE_TERMS[w]})
    
    score = len(findings) / max(len(words), 1)
    return {
        "text": text,
        "is_acceptable": len(findings) == 0,
        "ambiguity_score": round(score, 3),
        "issues": findings
    }

if __name__ == "__main__":
    vague_req = "We need a fast, scalable and seamless refund endpoint that is user-friendly."
    clean_req = "POST /v1/refunds must settle refunds under 250ms with X-Idempotency-Key support."

    print("=== Analyzing Vague Brief ===")
    res1 = lint_requirement(vague_req)
    print(f"Acceptable: {res1['is_acceptable']} | Ambiguity Score: {res1['ambiguity_score']}")
    for issue in res1["issues"]:
        print(f"  - Flagged '{issue['term']}': {issue['remediation']}")

    print("\n=== Analyzing Precise Production Brief ===")
    res2 = lint_requirement(clean_req)
    print(f"Acceptable: {res2['is_acceptable']} | Ambiguity Score: {res2['ambiguity_score']}")

4. System Architecture & The Spec-Kit Pipeline

The single largest source of failure in software engineering is not compiler syntax errors, but specification ambiguity. When humans write software, ambiguous requirements result in misaligned features discovered during sprint reviews. But when autonomous AI coding agents encounter ambiguous requirements, the consequences are exponentially worse:

• The agent makes silent, arbitrary architectural assumptions to resolve ambiguities.
• It synthesizes code that satisfies the literal text while violating business invariants.
• It fabricates ad-hoc data schemas that break upstream and downstream microservices.

To enable deterministic, autonomous software development, requirements engineering must transition from loose natural language prose into a formal compilation process: The Spec-Kit Pipeline.

+---------------------------------------------------------------------------------------------------+
|                                  THE SPEC-KIT COMPILATION PIPELINE                                |
+---------------------------------------------------------------------------------------------------+
|                                                                                                   |
|   +--------------------------+         +--------------------------+                               |
|   |  RAW STAKEHOLDER BRIEF   |         |    AMBIGUITY LINTER      |                               |
|   |  - Unstructured Text     | ------> |    - Adjective Penalty   |                               |
|   |  - Conversational Needs  |         |    - Lexical Scoring     |                               |
|   +--------------------------+         +--------------------------+                               |
|                                                      |                                            |
|                                                      v                                            |
|   +--------------------------+         +--------------------------+                               |
|   |   GHERKIN SCENARIO       |         |   DOMAIN ENTITY MODEL    |                               |
|   |   - Given-When-Then      | <------ |   - JSON Schema Defs     |                               |
|   |   - Happy/Edge/Security  |         |   - Required Invariants  |                               |
|   +--------------------------+         +--------------------------+                               |
|                 |                                                                                 |
|                 v                                                                                 |
|   +---------------------------------------------------------------+                               |
|   |                   FROZEN SPECIFICATION (spec.md)              |                               |
|   |  - Gated Entry to Architecture & Coding Stages (AI-DLC Gate)  |                               |
|   +---------------------------------------------------------------+                               |
|                                                                                                   |
+---------------------------------------------------------------------------------------------------+

The Autonomous Requirements State Machine

The Requirements Analyst Agent operates as an automated compiler, transforming raw input into machine-executable contracts:

stateDiagram-v2
    [*] --> IngestBrief
    IngestBrief --> AmbiguityScoring: Extract Terminology
    AmbiguityScoring --> RejectedAmbiguous: Ambiguity Score > 0.20
    RejectedAmbiguous --> IngestBrief: Solicit Precise Clarification

    AmbiguityScoring --> EntityExtraction: Ambiguity Score <= 0.20
    EntityExtraction --> GherkinSynthesis: Synthesize Invariants
    GherkinSynthesis --> BoundaryAnalysis: Generate Edge & Rate Scenarios
    BoundaryAnalysis --> SpecValidation: Verify Schema & SLO Completeness
    SpecValidation --> FrozenSpec: Pass 100% Structural Check
    FrozenSpec --> [*]: Handoff to Software Architect Agent

5. Freshman Survival Guide: 3 Traps to Avoid

Trap 1: The "It's Obvious What I Meant" Trap

• The Mistake: Writing "User can upload their avatar image" without specifying allowed file extensions, maximum file size in megabytes, or dimensions.
• Why it fails: An AI coding agent might write code allowing a 50GB file upload or accepting .exe executable malware, opening a critical security vulnerability.
• Fix: Always specify exact boundaries: Max size: 5MB, format: JPEG/PNG only, dimensions: 400x400px.

Trap 2: Happy-Path-Only Syndrome

• The Mistake: Specifying only what happens when everything goes right (the user has money, enters the right card, and clicks pay).
• Why it fails: Real software spends 70% of its runtime handling errors (network timeouts, expired cards, duplicate submissions, insufficient balances). If your spec doesn't define edge cases, the AI will invent bad fallbacks.
• Fix: Use the 1:3 Scenario Invariant: every happy path must be paired with at least 1 edge case (idempotency), 1 validation failure, and 1 security/rate-limit scenario.

Trap 3: The Premature Coding Trap

• The Mistake: Jumping straight to writing Python/Java code or asking an AI to generate code before writing and freezing the spec.md specification.
• Why it fails: You end up rewriting the code 4 times because nobody agreed on what the database tables or API responses should look like.
• Fix: Treat the specification as a frozen contract. Only start coding when the spec passes structural validation with zero ambiguity.

6. Naive vs. Production Contrasts

The table below contrasts traditional conversational product management with Spec-Kit automated requirements compilation:

7. Frontier Model Configurations & Spec-Kit Prompt Schemas

Automated requirements engineering requires frontier reasoning capabilities. Gemini 2.5 Pro with low temperature is deployed to prevent creative hallucinations while strictly enforcing domain boundaries.

Gemini 2.5 Pro Analyst Configuration

REQUIREMENTS_ANALYST_AGENT_CONFIG = {
    "model": "gemini-2.5-pro",
    "temperature": 0.15,
    "top_p": 0.90,
    "max_output_tokens": 8192,
    "system_instruction": """You are the Lead Systems Analyst in an AI-DLC autonomous software organization.
Your sole mission is to ingest raw user requests and emit formal, unambiguous Spec-Kit specifications.
RULES:
1. Strip all unquantified adjectives (e.g. fast, scalable, seamless). Replace with exact numerical SLOs.
2. Formulate explicit domain entities with strict JSON Schema data types.
3. Generate four Gherkin scenario categories for every feature: Happy Path, Edge Case (Idempotency), Validation Failure, and Security/Rate-Limiting.
4. Output must strictly conform to the SpecKitSchema JSON specification."""
}

Spec-Kit Structured Output Schema (JSON Schema Draft 2020-12)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SpecKitSchema",
  "type": "object",
  "properties": {
    "feature_name": {"type": "string"},
    "ambiguity_score": {"type": "number", "minimum": 0.0, "maximum": 1.0},
    "domain_entities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "properties": {"type": "object"},
          "required": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["name", "properties", "required"]
      }
    },
    "scenarios": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "type": {"type": "string", "enum": ["HAPPY_PATH", "EDGE_CASE", "VALIDATION_FAILURE", "SECURITY_RATE_LIMIT"]},
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "keyword": {"type": "string", "enum": ["Given", "When", "Then", "And", "But"]},
                "text": {"type": "string"}
              },
              "required": ["keyword", "text"]
            }
          }
        },
        "required": ["name", "type", "steps"]
      }
    },
    "service_level_objectives": {
      "type": "object",
      "properties": {
        "p99_latency": {"type": "string"},
        "idempotency_ttl": {"type": "string"},
        "rate_limit_policy": {"type": "string"}
      },
      "required": ["p99_latency", "idempotency_ttl", "rate_limit_policy"]
    }
  },
  "required": ["feature_name", "ambiguity_score", "domain_entities", "scenarios", "service_level_objectives"]
}

4. Quantitative Trade-Off Matrix

The choice of requirements representation dictates downstream agentic coding precision, latency, and token efficiency:

5. The 10 Operational Failure Modes in AI Requirements Engineering

1. The Adjective Smuggling Anti-Pattern

• Mechanism: Stakeholders input subjective qualifiers ("Make the dashboard load instantly and look clean"). The LLM copies these words into the requirements without enforcing concrete metrics.
• Defense Mechanism: Lexical Adjective Linter. Any occurrence of unquantified terms (fast, scalable, instant) triggers an immediate linter failure requiring exact numeric thresholds (e.g. < 200ms p95).

2. The Missing Negative Path Void

• Mechanism: Requirements specify what should happen on success, but leave error handling undefined. The coding agent defaults to unhandled 500 server crashes or silent failures.
• Defense Mechanism: Enforce the 1:3 Scenario Invariant. For every Happy Path scenario, the compiler must synthesize at least one Validation Failure, one Boundary Edge Case, and one Security/Rate-Limiting scenario.

3. Implicit State Assumption

• Mechanism: Requirements assume prerequisite database state without explicit declaration (e.g. "When user clicks cancel subscription"). If the user was never subscribed or was already cancelled, the system behavior is indeterminate.
• Defense Mechanism: Explicit Gherkin Given clauses declaring preconditions and entity lifecycle states (Given an active subscription in state 'PAST_DUE').

4. Idempotency Key Neglect

• Mechanism: Requirements for mutating financial or stateful operations (payments, refunds, inventory decoders) omit idempotency definitions, leading to double-billing during network retries.
• Defense Mechanism: Mandatory idempotency contract requirement for all non-safe HTTP methods (POST, PATCH). Every mutating endpoint must define X-Idempotency-Key headers and cache TTLs in the spec.

5. Unbounded Collection Querying

• Mechanism: Requirements specify "Fetch all user transactions" without specifying pagination, sorting, or max limits, causing Out-Of-Memory (OOM) crashes in production.
• Defense Mechanism: Schema-enforced pagination parameters (cursor, limit with max 100) automatically injected into every list-returning endpoint specification.

6. Currency & Floating-Point Drift

• Mechanism: Requirements define monetary amounts as generic floats (e.g. $19.99), causing IEEE 754 precision loss during billing calculations.
• Defense Mechanism: Currency Invariant Rule. All monetary fields must be defined as integer cents (amount_cents: integer) alongside ISO-4217 three-letter currency codes.

7. Authorization Boundary Blur

• Mechanism: Spec specifies authentication ("User must be logged in") but omits tenant multi-tenancy isolation ("User can only access resources belonging to their organization").
• Defense Mechanism: Explicit Access Control Matrix (RBAC/ABAC) embedded directly into domain entity schemas and Gherkin security scenarios.

8. Timestamp Ambiguity & Timezone Drift

• Mechanism: Requirements specify "expire after 24 hours" without defining UTC anchoring, leading to clock skew errors across distributed nodes.
• Defense Mechanism: Enforce ISO-8601 UTC representation (YYYY-MM-DDTHH:MM:SSZ) across all domain timestamps and test assertions.

9. Cascade Deletion Omission

• Mechanism: Spec defines entity deletion (e.g. "Delete user profile") without specifying behavior for associated orders, audit logs, and payment tokens.
• Defense Mechanism: Mandatory Referential Integrity Policy (e.g. Soft-delete, restrict, or cascade) specified in the Entity Data Model.

10. Breaking Schema Mutation without Versioning

• Mechanism: Modifying existing requirements without explicit API version prefixes, causing downstream client crashes upon deployment.
• Defense Mechanism: URI version namespace enforcement (/v1/, /v2/) verified during spec compilation.

10. Mandatory Hands-On Lab: Spec-Kit Requirements Compiler & Ambiguity Linter

Lab Objective

In this hands-on lab, you will:

1. Ingest an intentionally flawed, vague stakeholder brief ("Build a fast, scalable, seamless and reliable refund endpoint that is user-friendly").
2. Run the SpecKitRequirementsCompiler to evaluate its Ambiguity Penalty Score and observe the gate rejecting the specification.
3. Compile a clean, contract-grade payment refund brief into formal Domain Entities, JSON Schemas, and Gherkin Acceptance Scenarios covering Happy Path, Idempotency Edge Case, Balance Overdraw, and Rate-Limiting.
4. Export the finalized specification to a production-ready Markdown document ready for the Architecture phase.

Lab Step-by-Step Instructions

Step 1: Run Ambiguity Detection on Vague Brief

Execute the linter against the ambiguous text. Verify that the ambiguity score exceeds the strict 0.20 threshold, correctly triggering is_ready_for_architecture=False.

Step 2: Ingest Valid Domain Request

Pass a precise technical brief specifying POST /v1/refunds with X-Idempotency-Key headers and settled Stripe charge balances.

Step 3: Verify Domain Entity Schemas

Inspect the extracted RefundRequest and RefundAuditLog schemas. Ensure all critical financial fields (amount_cents, currency, idempotency_key) are present in required_fields.

Step 4: Verify Gherkin Scenarios

Verify that the compiler synthesizes all 4 mandatory scenario types:

• HAPPY_PATH: Full refund of settled charge.
• EDGE_CASE: Idempotent replay returning cached HTTP 200 without duplicate ledger entries.
• VALIDATION_FAILURE: Amount exceeds remaining refundable balance returning HTTP 422.
• SECURITY_RATE_LIMIT: Exceeding 100 req/min returning HTTP 429.

Step 5: Export Markdown & Verify Self-Tests

Run the built-in unit test suite to certify 100% test passing and zero-dependency Python 3.11+ compliance.

11. Mandatory Recommended Answer & Executable Solution

The following complete, zero-dependency Python 3.11+ program implements the SpecKitRequirementsCompiler and automated test suite.

"""
test_ch02_engine.py
Zero-dependency Python 3.11+ engine for Chapter 2:
SpecKitRequirementsCompiler & GherkinScenarioSynthesizer
"""

import re
import json
from dataclasses import dataclass, field, asdict
from enum import Enum
from typing import List, Dict, Any, Optional

class ScenarioType(str, Enum):
    HAPPY_PATH = "HAPPY_PATH"
    EDGE_CASE = "EDGE_CASE"
    SECURITY_RATE_LIMIT = "SECURITY_RATE_LIMIT"
    VALIDATION_FAILURE = "VALIDATION_FAILURE"

@dataclass
class GherkinStep:
    keyword: str  # Given, When, Then, And, But
    text: str

@dataclass
class GherkinScenario:
    name: str
    scenario_type: ScenarioType
    steps: List[GherkinStep]

@dataclass
class DomainEntity:
    name: str
    fields: Dict[str, str]  # field_name -> type
    required_fields: List[str]

@dataclass
class CompiledSpec:
    feature_name: str
    summary: str
    domain_entities: List[DomainEntity]
    scenarios: List[GherkinScenario]
    slo_constraints: Dict[str, str]
    ambiguity_score: float
    is_ready_for_architecture: bool

class SpecKitRequirementsCompiler:
    """Compiles raw feature requests into formal, deterministic Gherkin specifications and schemas."""

    VAGUE_ADJECTIVES = [
        "fast", "scalable", "instant", "reliable", "user-friendly",
        "seamless", "robust", "high-performance", "secure enough"
    ]

    def __init__(self, feature_name: str, raw_brief: str):
        self.feature_name = feature_name
        self.raw_brief = raw_brief

    def calculate_ambiguity_score(self) -> float:
        """Calculates ambiguity penalty based on unquantified adjectives in raw brief."""
        matches = 0
        for adj in self.VAGUE_ADJECTIVES:
            pattern = rf'\b{re.escape(adj)}\b'
            found = re.findall(pattern, self.raw_brief, re.IGNORECASE)
            matches += len(found)
        # Ambiguity score scaled 0.0 (pristine) to 1.0 (unusable)
        return min(1.0, round(matches * 0.20, 2))

    def extract_domain_entities(self) -> List[DomainEntity]:
        """Extracts canonical domain entities required for transaction processing."""
        # Detect monetary / refund semantics
        entities = []
        if any(w in self.raw_brief.lower() for w in ["refund", "payment", "charge", "transaction"]):
            refund_entity = DomainEntity(
                name="RefundRequest",
                fields={
                    "refund_id": "string (UUIDv4)",
                    "charge_id": "string (ch_*)",
                    "amount_cents": "integer (positive)",
                    "currency": "string (ISO-4217, e.g. USD)",
                    "idempotency_key": "string (header X-Idempotency-Key)",
                    "reason": "string (enum: requested_by_customer, fraudulent, duplicate)"
                },
                required_fields=["charge_id", "amount_cents", "currency", "idempotency_key"]
            )
            entities.append(refund_entity)

            audit_entity = DomainEntity(
                name="RefundAuditLog",
                fields={
                    "log_id": "string (UUIDv4)",
                    "refund_id": "string (UUIDv4)",
                    "caller_identity": "string (service/user ID)",
                    "timestamp_utc": "string (ISO-8601)",
                    "status": "string (succeeded, rejected, processing)"
                },
                required_fields=["log_id", "refund_id", "caller_identity", "timestamp_utc", "status"]
            )
            entities.append(audit_entity)
        else:
            generic_entity = DomainEntity(
                name="ResourcePayload",
                fields={
                    "resource_id": "string (UUIDv4)",
                    "created_at": "string (ISO-8601)",
                    "payload": "object"
                },
                required_fields=["resource_id", "created_at"]
            )
            entities.append(generic_entity)

        return entities

    def synthesize_gherkin_scenarios(self) -> List[GherkinScenario]:
        """Synthesizes deterministic Given-When-Then scenarios anchored to acceptance criteria."""
        scenarios: List[GherkinScenario] = []

        # 1. Happy Path
        scenarios.append(GherkinScenario(
            name="Successful full refund for settled charge",
            scenario_type=ScenarioType.HAPPY_PATH,
            steps=[
                GherkinStep("Given", "a settled charge with ID 'ch_109283' of amount 5000 USD cents"),
                GherkinStep("And", "the caller presents a valid idempotency key 'idem-uuid-9901'"),
                GherkinStep("When", "the caller dispatches a POST request to '/v1/refunds' with amount 5000 USD cents"),
                GherkinStep("Then", "the HTTP response status code must be 201 Created"),
                GherkinStep("And", "the response body must contain status 'succeeded' and refund_id matching UUIDv4"),
                GherkinStep("And", "an immutable audit log entry must be persisted to the audit ledger")
            ]
        ))

        # 2. Idempotency Edge Case
        scenarios.append(GherkinScenario(
            name="Idempotent duplicate refund request returns cached response",
            scenario_type=ScenarioType.EDGE_CASE,
            steps=[
                GherkinStep("Given", "a previously executed refund with idempotency key 'idem-uuid-9901'"),
                GherkinStep("When", "the caller resubmits an identical POST request with idempotency key 'idem-uuid-9901'"),
                GherkinStep("Then", "the HTTP response status code must be 200 OK"),
                GherkinStep("And", "the response payload must exactly match the initial 201 response"),
                GherkinStep("And", "no duplicate financial debit or duplicate ledger entry must occur")
            ]
        ))

        # 3. Validation / Business Rule Invariant
        scenarios.append(GherkinScenario(
            name="Refund amount exceeds settled charge balance",
            scenario_type=ScenarioType.VALIDATION_FAILURE,
            steps=[
                GherkinStep("Given", "a settled charge with ID 'ch_109283' of remaining refundable balance 2000 USD cents"),
                GherkinStep("When", "the caller attempts to refund 3000 USD cents"),
                GherkinStep("Then", "the HTTP response status code must be 422 Unprocessable Entity"),
                GherkinStep("And", "the error code must be 'AMOUNT_EXCEEDS_REMAINING_BALANCE'")
            ]
        ))

        # 4. Security & Rate Limiting
        scenarios.append(GherkinScenario(
            name="Burst rate limit exceeded on refund endpoint",
            scenario_type=ScenarioType.SECURITY_RATE_LIMIT,
            steps=[
                GherkinStep("Given", "an authenticated client exceeding 100 refund requests per minute"),
                GherkinStep("When", "the client dispatches the 101st POST request within the 60-second window"),
                GherkinStep("Then", "the HTTP response status code must be 429 Too Many Requests"),
                GherkinStep("And", "the response headers must include 'Retry-After' with integer seconds")
            ]
        ))

        return scenarios

    def compile(self) -> CompiledSpec:
        ambiguity = self.calculate_ambiguity_score()
        entities = self.extract_domain_entities()
        scenarios = self.synthesize_gherkin_scenarios()

        slos = {
            "p99_latency": "<= 250ms for cold requests, <= 45ms for cached idempotency hits",
            "idempotency_ttl": "86400 seconds (24 hours) retention in Redis cluster",
            "audit_guarantee": "Strict synchronous persistence before returning HTTP 201",
            "rate_limit_policy": "Token bucket: 100 req/min burst, 30 req/min sustained per API tenant"
        }

        # Ready for Architecture Gate if ambiguity <= 0.20 and at least 3 scenarios present
        is_ready = (ambiguity <= 0.20) and (len(scenarios) >= 3) and (len(entities) >= 1)

        return CompiledSpec(
            feature_name=self.feature_name,
            summary=f"Spec-Kit compiled specification for {self.feature_name}",
            domain_entities=entities,
            scenarios=scenarios,
            slo_constraints=slos,
            ambiguity_score=ambiguity,
            is_ready_for_architecture=is_ready
        )

    def export_markdown(self, spec: CompiledSpec) -> str:
        """Exports the compiled specification into formal Spec-Kit Markdown."""
        lines = []
        lines.append(f"# Spec: {spec.feature_name}")
        lines.append("")
        lines.append(f"> **Compilation Status**: {'READY FOR ARCHITECTURE' if spec.is_ready_for_architecture else 'REJECTED - HIGH AMBIGUITY'}")
        lines.append(f"> **Ambiguity Score**: {spec.ambiguity_score:.2f} (Threshold: <= 0.20)")
        lines.append("")
        lines.append("## 1. Domain Entities & Schemas")
        for ent in spec.domain_entities:
            lines.append(f"### Entity: {ent.name}")
            lines.append("```json")
            schema_dict = {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "title": ent.name,
                "type": "object",
                "properties": {k: {"type": v} for k, v in ent.fields.items()},
                "required": ent.required_fields
            }
            lines.append(json.dumps(schema_dict, indent=2))
            lines.append("```")
            lines.append("")

        lines.append("## 2. Gherkin Acceptance Scenarios")
        for sc in spec.scenarios:
            lines.append(f"### Scenario: [{sc.scenario_type.value}] {sc.name}")
            for step in sc.steps:
                lines.append(f"  {step.keyword} {step.text}")
            lines.append("")

        lines.append("## 3. Service Level Objectives (SLOs)")
        for metric, slo in spec.slo_constraints.items():
            lines.append(f"- **{metric}**: {slo}")

        return "\n".join(lines)


# ==========================================
# Self-Test Verification Suite
# ==========================================
if __name__ == "__main__":
    import unittest

    class TestSpecKitCompiler(unittest.TestCase):
        def test_ambiguity_scoring_high(self):
            vague_brief = "Build a fast, scalable, seamless and reliable refund endpoint that is user-friendly."
            compiler = SpecKitRequirementsCompiler("VagueRefund", vague_brief)
            score = compiler.calculate_ambiguity_score()
            self.assertTrue(score >= 0.6, f"Expected high ambiguity, got {score}")

        def test_ambiguity_scoring_clean(self):
            clean_brief = "Implement POST /v1/refunds with X-Idempotency-Key header, debiting settled Stripe charge balance."
            compiler = SpecKitRequirementsCompiler("CleanRefund", clean_brief)
            score = compiler.calculate_ambiguity_score()
            self.assertEqual(score, 0.0)

        def test_domain_entity_extraction(self):
            brief = "Process charge refunds with idempotency keys and persist audit ledger."
            compiler = SpecKitRequirementsCompiler("StripeRefund", brief)
            entities = compiler.extract_domain_entities()
            entity_names = [e.name for e in entities]
            self.assertIn("RefundRequest", entity_names)
            self.assertIn("RefundAuditLog", entity_names)
            refund_req = next(e for e in entities if e.name == "RefundRequest")
            self.assertIn("idempotency_key", refund_req.required_fields)

        def test_gherkin_scenario_synthesis(self):
            brief = "Payment refund processing"
            compiler = SpecKitRequirementsCompiler("PaymentRefund", brief)
            scenarios = compiler.synthesize_gherkin_scenarios()
            self.assertEqual(len(scenarios), 4)
            types = {s.scenario_type for s in scenarios}
            self.assertIn(ScenarioType.HAPPY_PATH, types)
            self.assertIn(ScenarioType.EDGE_CASE, types)
            self.assertIn(ScenarioType.VALIDATION_FAILURE, types)
            self.assertIn(ScenarioType.SECURITY_RATE_LIMIT, types)

        def test_full_compilation_and_markdown_export(self):
            clean_brief = "Implement POST /v1/refunds with idempotency key and audit log"
            compiler = SpecKitRequirementsCompiler("RefundGateway", clean_brief)
            compiled = compiler.compile()
            self.assertTrue(compiled.is_ready_for_architecture)
            self.assertEqual(compiled.ambiguity_score, 0.0)

            md = compiler.export_markdown(compiled)
            self.assertIn("# Spec: RefundGateway", md)
            self.assertIn("READY FOR ARCHITECTURE", md)
            self.assertIn("Given a settled charge", md)
            self.assertIn("X-Idempotency-Key", md)

    suite = unittest.TestLoader().loadTestsFromTestCase(TestSpecKitCompiler)
    runner = unittest.TextTestRunner(verbosity=2)
    test_result = runner.run(suite)
    if not test_result.wasSuccessful():
        exit(1)
    print("\n[PASS] All Chapter 2 Unit Tests Passed Successfully (100% Conformance).")

12. Summary & Next Steps

This chapter established deterministic requirements engineering for Playbook 04:

• Replaced informal PRDs with the automated Spec-Kit Compilation Pipeline.
• Instituted the 1:3 Scenario Invariant (Happy Path + Idempotency + Validation + Rate Limiting).
• Formalized the lexical Ambiguity Linter to block unquantifiable adjectives.
• Provided and verified the zero-dependency Python 3.11+ SpecKitRequirementsCompiler.

Upcoming Chapters in Playbook 04:

• Chapter 03: AI-Assisted System Architecture & C4 Modeling.
• Chapter 04: Interface Design, API Contracts & Schema Synthesis.
• Chapter 05: Agentic Coding, Context Gathering & Tree-sitter AST Mechanics.
• Chapter 06: Autonomous Verification, Testing & Self-Healing Code Loops.