Topic: Appendix A. Bridges to Volume One
Difficulty level: Medium
Estimated study time: 4-6 hours of active study + 2-3 hours of practical exercises
Prerequisites: Completion of core parts of Volume One (parts 6, 7, 9, 10, 12, 13, 15, 16, 17, 20, 22)
Understanding of SDD artifact structure: mission.md, tech-stack.md, roadmap.md, requirements.md, plan.md, validation.md
Basic familiarity with the AgentClinic project from Volume One
Understanding of EARS and Given/When/Then formats for requirements specification
Familiarity with Qwen Code hooks (PreToolUse, PostToolUse)
Understanding of agent replaceability concept and references to ACP/AGENTS.md
Learning objectives: Successfully map all 12 production scenarios from Volume Two to corresponding learning components of AgentClinic from Volume One
Perform artifact migration between three SDD dialects (author's, Spec Kit, Kiro) without loss of semantics
Form a minimal Volume Two completion route, distinguishing mandatory artifacts from the full implementation track
Identify and explain which 8 topics from Volume One are critical prerequisites for reading Volume Two
Apply the AgentClinic domain map to interpret production symptoms (node_not_ready, appointment_latency, high_memory_usage, etc.) in the context of specific chapters
Overview: Appendix A serves as an architectural bridge between the educational Volume One and the applied Volume Two of the SDD (Specification-Driven Development) course. It systematizes three critical connections: prerequisites from Volume One (without which Volume Two is unreadable), SDD dialect correspondence (author's, GitHub Spec Kit, AWS Kiro), and the domain map for transforming the educational AgentClinic project into production scenarios. The appendix contains no new methodology — its purpose is to prevent reader cognitive overload by explicitly showing how each "production term" in Volume Two grows out of already familiar educational code. Volume Two builds 14 new layers on top of the Volume One foundation: from spec archaeology and tiered budgets to production SDD antipatterns and the final production exam.
Key concepts: Bridge: An explicit connection between an artifact/concept from Volume One and its production interpretation in Volume Two. Bridges are collected in tabular form for quick cross-referencing when reading any chapter of Volume Two.
Minimal route: A trimmed Volume Two completion track where some artifacts are filled in manually, some examples are run locally, and some blocks belong only to the full implementation track. Described in part 0 (part-00-production-lab.md).
SDD dialect: A concrete implementation of the Specification-Driven Development methodology with a fixed set of artifacts and naming rules. The author's course dialect uses .md files; Spec Kit uses /speckit.* commands; Kiro uses its own artifact structure.
AgentClinic domain map: A correspondence table between educational entities from Volume One (Hono routes, SQLite migrations, feedback forms) and production symptoms from Volume Two (node_not_ready, appointment_latency_spike, rate_limit_breach, etc.).
Production symptom: An observable anomaly sign in production (e.g., high_memory_usage), which in Volume Two is analyzed through the SDD cycle lens: specification → plan → validation → escalation/remediation.
Exam route: The mandatory minimum for passing the applied volume. For the AgentClinic domain map, the exam case is high_memory_usage (SQLite read spike after deployment); other symptoms are used for understanding local examples.
Spec archaeology: The process of recovering specifications from traces of a legacy system without original documentation. Volume Two develops this theme from Part 13 of Volume One.
Shadow specifications: Informal heuristics and implicit requirements that are not captured in explicit artifacts but influence decision-making. Volume Two formalizes them through a selection procedure.
Tiered budgets: A system for distributing LLM model call costs across levels (tiers) of task complexity, preventing budget drain on simple operations.
Anti-Goodhart metrics: Paired guard metrics constructed so that optimization on one metric does not lead to degradation on another (protection against Goodhart's Law effect).
Practice exercises: Name: Exercise 1: Gap Analysis in Prerequisites
Problem: You are given a list of 8 topics from Volume One. For each topic, determine: (a) which SDD artifact it produces, (b) in which chapter of Volume Two this artifact is used, (c) what will happen if you read the chapter without knowing the prerequisite. Topics: Structure of mission.md/tech-stack.md/roadmap.md; Format of requirements.md/plan.md/validation.md; Merge gate facts and EARS; Replanning and roadmap updates; Legacy codebase support; Agent replaceability; Team review and evidence package; Qwen Code hooks.
Solution: Step 1: Create a 3×8 table. Step 2: For 'Structure of mission.md' — artifacts: project constitution; Volume Two chapter: part 3 (Production Constitution); consequence of skipping: misunderstanding the separation of immutable and mutable layers. Step 3: For 'Format of requirements.md/plan.md/validation.md' — artifacts: feature specification; chapter: part 7 (Specification CI); consequence: inability to configure the specification gateway as a mandatory gate. Step 4: For 'Merge gate facts and EARS' — artifacts: validation facts; chapter: part 4 (LLM Duel); consequence: inability to organize adversarial validation between roles. Step 5: For 'Replanning' — artifacts: updated roadmap; chapter: part 9 (Tiered Budgets); consequence: not understanding how budget constraints affect replanning. Step 6: For 'Spec archaeology' — artifacts: recovered specification; chapter: part 1; consequence: inability to apply legacy recovery techniques. Step 7: For 'Agent replaceability' — artifacts: ACP/AGENTS.md; chapter: part 8 (File Arbitration); consequence: not understanding how a multi-agent tribunal preserves role independence. Step 8: For 'Team review' — artifacts: evidence package; chapter: part 13 (Practical Exam); consequence: inability to form a final production exam. Step 9: For 'Qwen Code hooks' — artifacts: PreToolUse/PostToolUse; chapter: part 11 (Production API); consequence: inability to implement auto-remediation through hooks.
Complexity: intermediate
Name: Exercise 2: Translation Between SDD Dialects
Problem: A team works in GitHub Spec Kit. Translate the following artifacts from the author's course dialect into Spec Kit commands: requirements.md for the 'appointment booking' feature, plan.md for a sprint iteration, validation.md for feature verification. Then perform reverse translation: /speckit.analyze → author's dialect.
Solution: Step 1: requirements.md → /speckit.specify (creating requirements specification). Step 2: plan.md → /speckit.plan + /speckit.tasks (plan is split into plan structure and specific tasks). Step 3: validation.md → /speckit.analyze + checklists (validation includes analysis and acceptance checklists). Step 4: Reverse translation: /speckit.analyze → validation.md (validation file containing gate facts, EARS specifications, Given/When/Then scenarios). Step 5: Verify semantic preservation: in Spec Kit commands execute in chat interface, in author's dialect files are versioned in Git; both approaches must produce an identical set of verifiable facts.
Complexity: intermediate
Name: Exercise 3: Interpreting a Production Symptom Through the Domain Map
Problem: In a production system based on AgentClinic, the symptom autoscale_200pct (sharp 200% load increase) is detected. Using the domain map, determine: (a) which educational component from Volume One underlies this symptom, (b) in which project phase (MVP) it occurred, (c) which Volume Two chapters are applicable for analysis, (d) which metrics and budgets are involved.
Solution: Step 1: Per the domain map table, autoscale_200pct corresponds to 'MVP phase (part 12)' of Volume One. Step 2: The MVP phase was characterized by manual deployment and lack of automatic scaling — sharp load increase was unexpected. Step 3: Applicable Volume Two chapters: part 9 (Tiered Budgets — distributing models by task complexity under load increase), part 10 (Anti-Goodhart Metrics — preventing autoscale optimization at the expense of latency), part 11 (Production API — integration with auto-scaling systems). Step 4: Metrics: appointment_latency (response delay), high_memory_usage (resource consumption during scaling). Step 5: Budgets: tiered model budget (do not exhaust expensive calls on routine checks), cdn_error_budget_burn (do not exhaust CDN error budget during sharp traffic increase).
Complexity: intermediate
Name: Exercise 4: Forming a Minimal Route for a Specific Chapter
Problem: You are preparing to study part 5 of Volume Two (Mutation Testing of Specifications). Based on the minimal route structure from part 0, determine: which artifacts are filled in manually, which examples are run locally, which blocks belong only to the full implementation track.
Solution: Step 1: Identify prerequisites from Appendix A: part 9 of Volume One (gate facts, EARS, Given/When/Then) — critically necessary, otherwise there is nothing to check specification mutations against. Step 2: Artifacts filled in manually: requirements.md for a feature in EARS format, a set of mutants (intentionally distorted versions of the specification), an oracle list of expected failures. Step 3: Locally runnable examples: mutation script (introducing controlled defects into the specification), validator run against mutants, mutation coverage analysis. Step 4: Full track blocks: CI/CD integration for automatic mutation testing of every PR, mutation score metrics in dashboard, connection to tiered budgets (part 9). Step 5: Check: if you have not completed part 9 of Volume One — return to it, otherwise mutation testing will become a 'pileup of terms'.
Complexity: intermediate
Case studies: Name: Case: Team Migration from Spec Kit to Author's Dialect in Preparation for Production Exam
Scenario: A team of 4 developers worked with GitHub Spec Kit in a chat interface for 18 months to specify an internal doctor appointment system. When transitioning to the SDD course to prepare for the production exam, it was discovered that specification history was not versioned, /speckit.* commands did not produce verifiable artifacts for audit, and it was impossible to form an evidence package for team review.
Challenge: (1) Semantic loss in translation: /speckit.plan contains implicit assumptions that in file-based plan.md must be explicit. (2) Absence of merge gate facts — in Spec Kit checks were performed manually without EARS formalization. (3) The team did not understand how agent replaceability relates to ACP/AGENTS.md, since in Spec Kit the agent role was fixed in chat context. (4) It was necessary to complete the exam route with high_memory_usage as the main case.
Solution: Step 1: Reverse engineering of all /speckit.* commands into .md file structure with preserved timestamps. Step 2: Formalization of implicit assumptions through shadow specifications (part 6 of Volume Two) with subsequent selection into explicit requirements.md. Step 3: Introduction of EARS and Given/When/Then for all critical paths, completing part 9 of Volume One in accelerated review mode. Step 4: Creation of ACP/AGENTS.md with explicit role separation, configuration of Qwen Code hooks for automatic context capture. Step 5: Application of domain map: high_memory_usage interpreted as SQLite read spike after deployment (part 12 of Volume One), which allowed formulating metrics and budgets for the exam.
Result: In 3 weeks the team formed a complete evidence package for part 13 (production exam). Mutation score for specifications grew from 0% to 73%. Tiered budget allowed reducing LLM call costs by 34% while preserving latency. Critical insight: bridges between volumes proved not to be a formality, but a tool for preventing cognitive collapse when transitioning from chat-oriented specification to production-ready SDD.
Lessons learned: Translation between SDD dialects requires explicit verification of semantic equivalence, not only syntactic correspondence of file names and commands
Shadow specifications accumulated in chat format become a critical risk when scaling — their formalization must precede, not follow, production implementation
The exam route (high_memory_usage) works as an anchor for the entire team: it concretizes abstract Volume Two concepts through already completed educational code
Skipping prerequisites (in this case — parts 15 and 16 of Volume One) increases migration time 2-3 fold due to the need to return
Related concepts: SDD Dialect
Shadow Specifications
AgentClinic Domain Map
Agent Replaceability
Exam Route
Evidence Package
Name: Case: Deploying Specification CI in a Legacy AgentClinic Project Without Original Specification
Scenario: The educational AgentClinic project, deployed by a student after completing Volume One, was enhanced for 6 months without maintaining SDD artifacts. When attempting to apply part 7 of Volume Two (Specification CI) as a mandatory gate, it was discovered that the current system state was not covered by specifications, and the gateway blocked any change.
Challenge: (1) Spec archaeology: it was necessary to recover specifications from existing code and database. (2) Controlled defects: part 2 of Volume Two requires ability to diagnose 'poisoned' specifications — but with no original, there is nothing to diagnose. (3) Production constitution (part 3): immutable layers were violated by ad-hoc changes. (4) It was necessary to determine which parts of Volume One were critical for recovery, and which could be omitted under time constraints.
Solution: Step 1: Application of part 13 of Volume One (Legacy Project Support) for structured collection of system traces: logs, database migrations, commit history, API endpoints. Step 2: Formation of a temporary 'shadow constitution' with explicit separation of what is already immutable (DB schema with data), and what is subject to refactoring (business logic in handlers). Step 3: Use of EARS and Given/When/Then from part 9 to formalize observed system behavior as a temporary specification. Step 4: Gradual introduction of Specification CI: first for new features, then — retrospective coverage of critical paths. Step 5: Application of domain map: symptom node_not_ready used as a test case to verify the recovered specification's functionality.
Result: In 4 weeks Specification CI worked for 60% of critical paths. The remaining 40% were explicitly marked as 'legacy without specification' with a plan for gradual coverage. The recovered specification allowed detecting 3 hidden bugs that did not manifest in the test environment, but were critical in production (related to rate_limit_breach).
Lessons learned: Spec archaeology without knowledge of part 13 of Volume One turns into chaotic reverse engineering; a structured approach saves 40-50% of time
A temporary 'shadow constitution' is an acceptable artifact at an intermediate stage; the key is explicit separation of immutable and mutable
The domain map works both ways: not only 'educational code → production symptom', but also 'production symptom → test case for validating recovered specification'
Attempting to implement Specification CI without completing parts 6-7 of Volume One leads to formalization of incorrect artifact structure
Related concepts: Spec Archaeology
Production Constitution
Controlled Defects
Specification CI
AgentClinic Domain Map
Minimal Route
Study tips: Use the 'Minimum Without Which Volume Two Is Unreadable' table as a checklist before each chapter: if a prerequisite is unfamiliar — immediately return to the corresponding part of Volume One, otherwise subsequent reading becomes passive browsing of a 'pileup of terms'
Print or keep in a separate window the AgentClinic domain map table when reading any chapter of Volume Two — this reduces cognitive load by 30-40% compared to trying to hold all correspondences in memory
For auditory perception: read aloud bridge formulations of the form 'GET / route (Hello Hono) → node_not_ready: replicas not responding to health-check' — the rhythmic 'educational → production' structure aids memorization
For kinesthetic perception: physically check marks in the prerequisites table, manually rewrite 3-4 key bridges in your own wording, create a physical 'bridge map' on an A3 sheet
For visual perception: color the domain map table — green for exam route (high_memory_usage), yellow for local runnable examples, red for full implementation track
Conduct 'translation sessions': take one chapter of Volume Two and explicitly mark which prerequisites from Volume One are used in each paragraph — this transforms passive reading into active connection building
If your team works in Spec Kit or Kiro — create your own correspondence table with the author's dialect and hang it near your workspace; artifact renaming must become an automatic skill
Use the chronological approach: complete Volume One parts in the order they are mentioned in Appendix A (6 → 7 → 9 → 10 → 12 → 13 → 15 → 16 → 17 → 20 → 22), not in numerical order — this corresponds to the logic of increasing complexity in Volume Two
For Volume Two chapters 9-11 (budgets, metrics, Production API) be sure to return to parts 17 and 20 of Volume One — Qwen Code hooks and SDD antipatterns are direct prerequisites for understanding tiered budgets and auto-remediation
Form a 'personal bridge dictionary': when discovering a new correspondence between volumes, record it in a single document — after 2-3 chapters you will create an individual version of Appendix A adapted to your thinking style
Additional resources: Part 0. AgentClinic Production Lab (part-00-production-lab.md): Basic framework for translating AgentClinic into an educational production model; contains the minimal route definition
Appendix A of Volume One (appendix-a-sdd-dialects.md): Detailed comparison of three SDD dialects: artifact correspondence table, migration recommendations, limitations of each format
Appendix B of Volume One (appendix-b-agentclinic-domain.md): Complete description of AgentClinic domain entities: patient agents, ailments, therapies, appointments, reviews, feedback
Applied Volume README (readme.md): Brief reading map for Volume Two and link to Appendix A
Part 6 of Volume One (part-06-constitution.md): Creating constitution: mission.md, tech-stack.md, roadmap.md
Part 7 of Volume One (part-07-feature-specification.md): Feature specification: requirements.md, plan.md, validation.md
Part 9 of Volume One (part-09-feature-validation.md): Feature verification: merge gate facts, EARS, Given/When/Then
Part 13 of Volume One (part-13-legacy-support.md): Legacy project support: spec archaeology
Part 15 of Volume One (part-15-agent-replaceability.md): Agent replaceability, references to ACP/AGENTS.md
Part 17 of Volume One (part-17-qwen-code-hooks.md): Qwen Code hooks: PreToolUse and PostToolUse
Summary: Appendix A is not auxiliary material, but a critical infrastructure component of the course ensuring continuity between the educational and applied volumes. Its three functions: (1) reader readiness diagnosis through a checklist of 8 mandatory prerequisites, (2) SDD multidialect support through explicit translation rules between the author's format, Spec Kit, and Kiro, (3) concretization of abstract production scenarios through the AgentClinic domain map. Key principle: every production symptom in Volume Two (node_not_ready, appointment_latency, high_memory_usage, rate_limit_breach, autoscale_200pct, cdn_error_budget_burn) is a renamed and complicated educational component from Volume One. The exam route fixes high_memory_usage as the anchor case; other symptoms serve for understanding local examples. Without active use of bridges, Volume Two degrades into passive accumulation of terms; with bridges it becomes a meaningful continuation of already built competencies.