From 423e104835f981bfd79417e2fc8173646823a03f Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:25:24 -0500 Subject: [PATCH 01/11] docs: define Articles IV, V, VI in spec-driven.md Article IV (Requirement Quality and Coverage): driven by the clarify/checklist/analyze pipeline that validates requirement completeness, ambiguity, and traceability before planning. Article V (Non-Functional Standards): ensures projects explicitly specify performance, security, observability, and accessibility requirements rather than defaulting to functional-only output. Article VI (Governance and Versioning): codifies constitution versioning and cross-artifact consistency propagation via the /speckit.constitution command. These three articles were missing from the original document despite being actively enforced by existing templates and commands. Derived by mapping every template and command back to constitutional principles and identifying enforcement mechanisms with no article. --- spec-driven.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/spec-driven.md b/spec-driven.md index 090071a3c4..f453424a9a 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -318,6 +318,46 @@ No implementation code shall be written before: This completely inverts traditional AI code generation. Instead of generating code and hoping it works, the LLM must first generate comprehensive tests that define behavior, get them approved, and only then generate implementation. +#### Article IV: Requirement Quality and Coverage + +Specifications must be complete, unambiguous, and verifiable before planning begins: + +```text +All requirements MUST be: +- Testable: each requirement has measurable acceptance criteria +- Unambiguous: no vague qualifiers without quantified thresholds +- Traceable: mapped from user stories through tasks to implementation +``` + +This article drives the clarification, checklist, and analysis pipeline. The `/speckit.clarify` command scans for ambiguity across functional scope, data modeling, interaction flows, and edge cases. The `/speckit.checklist` command generates "unit tests for English"—validating requirement quality rather than implementation correctness. The `/speckit.analyze` command performs cross-artifact consistency checks, catching coverage gaps, terminology drift, and duplicate or conflicting requirements before any code is written. + +#### Article V: Non-Functional Standards + +Every project must explicitly address operational and quality concerns beyond functional correctness: + +```text +Non-functional requirements MUST be specified for: +- Performance: quantified metrics and thresholds +- Security: authentication, data protection, and failure response +- Observability: structured logging, monitoring, and debuggability +- Accessibility: interaction standards for all user interfaces +``` + +Without this article, LLMs default to functional-only implementations—code that works but cannot be monitored, secured, or maintained in production. The clarification pipeline explicitly scans for non-functional coverage gaps, and checklists can target specific quality dimensions (security, performance, UX) to ensure these concerns are captured in requirements before implementation begins. + +#### Article VI: Governance and Versioning + +The constitution itself must be versioned, and changes must propagate consistently across all project artifacts: + +```text +Constitution amendments MUST: +- Follow semantic versioning (MAJOR.MINOR.PATCH) +- Include a sync impact report across all templates +- Maintain cross-artifact consistency after every change +``` + +This article ensures that governance is not static. When principles evolve, the `/speckit.constitution` command validates that plan templates, spec templates, task templates, and command files remain aligned. Version bumps are classified by impact—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. + #### Articles VII & VIII: Simplicity and Anti-Abstraction These paired articles combat over-engineering: From 8f87999dafbd3f9ae6a7d01db5c5bad1d78eda2c Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:26:13 -0500 Subject: [PATCH 02/11] docs: remove /speckit.* command references from Articles IV-VI Match the style of existing articles which state principles and rationale without referencing specific Spec Kit commands. --- spec-driven.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index f453424a9a..3b4a852f8d 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -329,7 +329,7 @@ All requirements MUST be: - Traceable: mapped from user stories through tasks to implementation ``` -This article drives the clarification, checklist, and analysis pipeline. The `/speckit.clarify` command scans for ambiguity across functional scope, data modeling, interaction flows, and edge cases. The `/speckit.checklist` command generates "unit tests for English"—validating requirement quality rather than implementation correctness. The `/speckit.analyze` command performs cross-artifact consistency checks, catching coverage gaps, terminology drift, and duplicate or conflicting requirements before any code is written. +This article drives the clarification, checklist, and analysis pipeline. Before planning begins, specifications are scanned for ambiguity across functional scope, data modeling, interaction flows, and edge cases. "Unit tests for English" validate requirement quality rather than implementation correctness. Cross-artifact consistency checks catch coverage gaps, terminology drift, and duplicate or conflicting requirements before any code is written. #### Article V: Non-Functional Standards @@ -343,7 +343,7 @@ Non-functional requirements MUST be specified for: - Accessibility: interaction standards for all user interfaces ``` -Without this article, LLMs default to functional-only implementations—code that works but cannot be monitored, secured, or maintained in production. The clarification pipeline explicitly scans for non-functional coverage gaps, and checklists can target specific quality dimensions (security, performance, UX) to ensure these concerns are captured in requirements before implementation begins. +Without this article, LLMs default to functional-only implementations—code that works but cannot be monitored, secured, or maintained in production. The clarification pipeline explicitly scans for non-functional coverage gaps, and checklists can target specific quality dimensions to ensure these concerns are captured in requirements before implementation begins. #### Article VI: Governance and Versioning @@ -356,7 +356,7 @@ Constitution amendments MUST: - Maintain cross-artifact consistency after every change ``` -This article ensures that governance is not static. When principles evolve, the `/speckit.constitution` command validates that plan templates, spec templates, task templates, and command files remain aligned. Version bumps are classified by impact—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. +This article ensures that governance is not static. When principles evolve, plan templates, spec templates, task templates, and command files must remain aligned. Version bumps are classified by impact—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. #### Articles VII & VIII: Simplicity and Anti-Abstraction From 85fc96b284ac51a012ab95104f9112043905bf36 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:27:02 -0500 Subject: [PATCH 03/11] docs: align Articles IV-V language with existing article style Replace 'clarification pipeline' tooling references with principle-effect language matching Articles I-III and VII-IX. --- spec-driven.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index 3b4a852f8d..621e55a984 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -329,7 +329,7 @@ All requirements MUST be: - Traceable: mapped from user stories through tasks to implementation ``` -This article drives the clarification, checklist, and analysis pipeline. Before planning begins, specifications are scanned for ambiguity across functional scope, data modeling, interaction flows, and edge cases. "Unit tests for English" validate requirement quality rather than implementation correctness. Cross-artifact consistency checks catch coverage gaps, terminology drift, and duplicate or conflicting requirements before any code is written. +This forces the LLM to treat requirement quality as a first-class engineering concern. Before planning begins, specifications must be scanned for ambiguity across functional scope, data modeling, interaction flows, and edge cases. "Unit tests for English" validate requirement quality rather than implementation correctness. Cross-artifact consistency checks catch coverage gaps, terminology drift, and duplicate or conflicting requirements before any code is written. #### Article V: Non-Functional Standards @@ -343,7 +343,7 @@ Non-functional requirements MUST be specified for: - Accessibility: interaction standards for all user interfaces ``` -Without this article, LLMs default to functional-only implementations—code that works but cannot be monitored, secured, or maintained in production. The clarification pipeline explicitly scans for non-functional coverage gaps, and checklists can target specific quality dimensions to ensure these concerns are captured in requirements before implementation begins. +Without this article, LLMs default to functional-only implementations—code that works but cannot be monitored, secured, or maintained in production. Specifications must explicitly address non-functional coverage gaps, and quality checklists can target specific dimensions to ensure these concerns are captured in requirements before implementation begins. #### Article VI: Governance and Versioning From 058256758fa807dba6d187c0182d52643e711982 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:28:59 -0500 Subject: [PATCH 04/11] docs: broaden Article VI beyond constitution-only versioning Article VI now covers governance and versioning of all project artifacts (constitution, specs, plans, tasks), not just constitution amendments. This matches what spec-driven.md itself describes: specifications versioned in branches, requirement changes propagating across artifacts, and cross-artifact consistency. --- spec-driven.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index 621e55a984..177bef4c9f 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -347,16 +347,16 @@ Without this article, LLMs default to functional-only implementations—code tha #### Article VI: Governance and Versioning -The constitution itself must be versioned, and changes must propagate consistently across all project artifacts: +All project artifacts—constitution, specifications, plans, and tasks—must be versioned, and changes must propagate consistently across dependent artifacts: ```text -Constitution amendments MUST: -- Follow semantic versioning (MAJOR.MINOR.PATCH) -- Include a sync impact report across all templates +Artifact changes MUST: +- Be versioned and traceable through version control +- Propagate to all dependent artifacts when modified - Maintain cross-artifact consistency after every change ``` -This article ensures that governance is not static. When principles evolve, plan templates, spec templates, task templates, and command files must remain aligned. Version bumps are classified by impact—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. +This article ensures that governance is not static and that drift between artifacts is caught rather than silently accumulated. When a specification changes, affected plans and tasks must be re-evaluated. When principles evolve, templates and command files must remain aligned. Version bumps are classified by impact—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. #### Articles VII & VIII: Simplicity and Anti-Abstraction From fbb41195b4be21ef161bb9f94dad2e68566647f9 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:36:12 -0500 Subject: [PATCH 05/11] docs: revise Article VI to establish spec as source of truth Constitution and specifications are the versioned sources of truth. Plans and tasks are derived execution artifacts. Implementation gaps are addressed through new specifications, preserving the feed-forward dependency direction rather than retrofitting code back into specs. --- spec-driven.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index 177bef4c9f..0ceaad1316 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -347,16 +347,16 @@ Without this article, LLMs default to functional-only implementations—code tha #### Article VI: Governance and Versioning -All project artifacts—constitution, specifications, plans, and tasks—must be versioned, and changes must propagate consistently across dependent artifacts: +The constitution and specifications are the authoritative sources of truth. Plans and tasks are derived execution artifacts: ```text -Artifact changes MUST: -- Be versioned and traceable through version control -- Propagate to all dependent artifacts when modified -- Maintain cross-artifact consistency after every change +Governance MUST ensure: +- Constitution and specifications are versioned and traceable +- Derived artifacts (plans, tasks) remain consistent with their source specifications +- Implementation gaps are addressed through new specifications, not by retrofitting code back into existing specs ``` -This article ensures that governance is not static and that drift between artifacts is caught rather than silently accumulated. When a specification changes, affected plans and tasks must be re-evaluated. When principles evolve, templates and command files must remain aligned. Version bumps are classified by impact—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. +This article ensures that governance is not static and that the dependency direction is preserved—specifications drive implementation, never the reverse. When a gap or requirement emerges during implementation, it is addressed through a new specification rather than patching artifacts in place. Constitution amendments follow semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. #### Articles VII & VIII: Simplicity and Anti-Abstraction From 6fec3aa13d5bb8d22de3532acdcf9b51ae48fac3 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:38:17 -0500 Subject: [PATCH 06/11] docs: make Article VI neutral across workflow approaches Support all three schools: new spec, update existing spec, or regenerate derived artifacts. The only invariant is that specs drive implementation, not the reverse, and gaps are addressed through specifications rather than untracked code changes. --- spec-driven.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index 0ceaad1316..2169065170 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -353,10 +353,10 @@ The constitution and specifications are the authoritative sources of truth. Plan Governance MUST ensure: - Constitution and specifications are versioned and traceable - Derived artifacts (plans, tasks) remain consistent with their source specifications -- Implementation gaps are addressed through new specifications, not by retrofitting code back into existing specs +- Implementation gaps are addressed through specifications, not through untracked code changes ``` -This article ensures that governance is not static and that the dependency direction is preserved—specifications drive implementation, never the reverse. When a gap or requirement emerges during implementation, it is addressed through a new specification rather than patching artifacts in place. Constitution amendments follow semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. +This article ensures that governance is not static and that specifications remain the authoritative source. When a gap or requirement emerges during implementation, teams may create a new specification, update an existing one, or regenerate derived artifacts—whichever approach fits their workflow—as long as the specification continues to drive implementation rather than the reverse. Constitution amendments follow semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. #### Articles VII & VIII: Simplicity and Anti-Abstraction From 25175e212164203882db8088e0c108e08be26006 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:39:31 -0500 Subject: [PATCH 07/11] docs: recommend versioning models for constitution and specs Constitution uses semantic versioning (major/minor/patch). Specifications use branch-based workflows (feature branches, reviewed and merged like code). Consistent with the existing description in spec-driven.md line 21. --- spec-driven.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec-driven.md b/spec-driven.md index 2169065170..c97439a1a1 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -356,7 +356,9 @@ Governance MUST ensure: - Implementation gaps are addressed through specifications, not through untracked code changes ``` -This article ensures that governance is not static and that specifications remain the authoritative source. When a gap or requirement emerges during implementation, teams may create a new specification, update an existing one, or regenerate derived artifacts—whichever approach fits their workflow—as long as the specification continues to drive implementation rather than the reverse. Constitution amendments follow semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications—creating an auditable trail of architectural decisions. +This article ensures that governance is not static and that specifications remain the authoritative source. When a gap or requirement emerges during implementation, teams may create a new specification, update an existing one, or regenerate derived artifacts—whichever approach fits their workflow—as long as the specification continues to drive implementation rather than the reverse. + +The constitution follows semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications. Specifications are versioned through branch-based workflows—each feature specification lives in its own branch and is reviewed and merged like code. Together, these models create an auditable trail of architectural and product decisions. #### Articles VII & VIII: Simplicity and Anti-Abstraction From e3bcefdfcb22fe50f89b6b01595ea7eaffaae134 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:40:24 -0500 Subject: [PATCH 08/11] docs: remove git branch implementation detail from Article VI Spec versioning is now tool-agnostic: 'versioned and reviewable before acceptance' rather than prescribing branch-based workflows. --- spec-driven.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-driven.md b/spec-driven.md index c97439a1a1..42427d81c8 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -358,7 +358,7 @@ Governance MUST ensure: This article ensures that governance is not static and that specifications remain the authoritative source. When a gap or requirement emerges during implementation, teams may create a new specification, update an existing one, or regenerate derived artifacts—whichever approach fits their workflow—as long as the specification continues to drive implementation rather than the reverse. -The constitution follows semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications. Specifications are versioned through branch-based workflows—each feature specification lives in its own branch and is reviewed and merged like code. Together, these models create an auditable trail of architectural and product decisions. +The constitution follows semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications. Specifications must be versioned and reviewable before acceptance. Together, these practices create an auditable trail of architectural and product decisions. #### Articles VII & VIII: Simplicity and Anti-Abstraction From cce77e999ef1949f2f74bfbb6853cd0c88b99a67 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:44:53 -0500 Subject: [PATCH 09/11] docs: fix consistency across spec-driven.md - Remove git branch references from conceptual sections (lines 21, 152) - Remove memory/constitution.md file path from principles section - Replace 'immutable principles' with 'governing principles' to reconcile with Article VI semantic versioning - Constitutional Evolution section now acknowledges principles themselves can evolve through governed process, not just their application --- spec-driven.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index 42427d81c8..b4ba0fc958 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -18,7 +18,7 @@ The development team focuses in on their creativity, experimentation, their crit ## The SDD Workflow in Practice -The workflow begins with an idea—often vague and incomplete. Through iterative dialogue with AI, this idea becomes a comprehensive PRD. The AI asks clarifying questions, identifies edge cases, and helps define precise acceptance criteria. What might take days of meetings and documentation in traditional development happens in hours of focused specification work. This transforms the traditional SDLC—requirements and design become continuous activities rather than discrete phases. This is supportive of a **team process**, where team-reviewed specifications are expressed and versioned, created in branches, and merged. +The workflow begins with an idea—often vague and incomplete. Through iterative dialogue with AI, this idea becomes a comprehensive PRD. The AI asks clarifying questions, identifies edge cases, and helps define precise acceptance criteria. What might take days of meetings and documentation in traditional development happens in hours of focused specification work. This transforms the traditional SDLC—requirements and design become continuous activities rather than discrete phases. This is supportive of a **team process**, where team-reviewed specifications are expressed, versioned, reviewed, and accepted. When a product manager updates acceptance criteria, implementation plans automatically flag affected technical decisions. When an architect discovers a better pattern, the PRD updates to reflect new possibilities. @@ -149,7 +149,7 @@ In 15 minutes, you have: - A detailed implementation plan with technology choices and rationale - API contracts and data models ready for code generation - Comprehensive test scenarios for both automated and manual testing -- All documents properly versioned in a feature branch +- All documents properly versioned and reviewable ### The Power of Structured Automation @@ -273,7 +273,7 @@ The templates transform the LLM from a creative writer into a disciplined specif ## The Constitutional Foundation: Enforcing Architectural Discipline -At the heart of SDD lies a constitution—a set of immutable principles that govern how specifications become code. The constitution (`memory/constitution.md`) acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality. +At the heart of SDD lies a constitution—a set of governing principles that define how specifications become code. The constitution acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality. ### The Nine Articles of Development @@ -413,9 +413,9 @@ The implementation plan template operationalizes these articles through concrete These gates act as compile-time checks for architectural principles. The LLM cannot proceed without either passing the gates or documenting justified exceptions in the "Complexity Tracking" section. -### The Power of Immutable Principles +### The Power of Governing Principles -The constitution's power lies in its immutability. While implementation details can evolve, the core principles remain constant. This provides: +The constitution's power lies in its stability. While implementation details can evolve freely, changes to core principles require deliberate governance—explicit rationale, review, and versioning. This provides: 1. **Consistency Across Time**: Code generated today follows the same principles as code generated next year 2. **Consistency Across LLMs**: Different AI models produce architecturally compatible code @@ -424,7 +424,7 @@ The constitution's power lies in its immutability. While implementation details ### Constitutional Evolution -While principles are immutable, their application can evolve: +While principles are stable, both their application and the principles themselves can evolve through a governed process: ```text Section 4.2: Amendment Process From 515baba6ad29c3139f61acb3b5e20a8b42ca1bbd Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:45:54 -0500 Subject: [PATCH 10/11] docs: rename 'The SDD Workflow in Practice' to 'The SDD Process in Practice' --- spec-driven.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-driven.md b/spec-driven.md index b4ba0fc958..c10a6822bd 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -16,7 +16,7 @@ Debugging means fixing specifications and their implementation plans that genera The development team focuses in on their creativity, experimentation, their critical thinking. -## The SDD Workflow in Practice +## The SDD Process in Practice The workflow begins with an idea—often vague and incomplete. Through iterative dialogue with AI, this idea becomes a comprehensive PRD. The AI asks clarifying questions, identifies edge cases, and helps define precise acceptance criteria. What might take days of meetings and documentation in traditional development happens in hours of focused specification work. This transforms the traditional SDLC—requirements and design become continuous activities rather than discrete phases. This is supportive of a **team process**, where team-reviewed specifications are expressed, versioned, reviewed, and accepted. From 2116770d4d1eb03397337b7e5100af2361487bca Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 11 May 2026 09:46:39 -0500 Subject: [PATCH 11/11] docs: replace 'workflow' with 'process' throughout spec-driven.md --- spec-driven.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index c10a6822bd..378ae4149e 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -12,13 +12,13 @@ This transformation is now possible because AI can understand and implement comp In this new world, maintaining software means evolving specifications. The intent of the development team is expressed in natural language ("**intent-driven development**"), design assets, core principles and other guidelines. The **lingua franca** of development moves to a higher level, and code is the last-mile approach. -Debugging means fixing specifications and their implementation plans that generate incorrect code. Refactoring means restructuring for clarity. The entire development workflow reorganizes around specifications as the central source of truth, with implementation plans and code as the continuously regenerated output. Updating apps with new features or creating a new parallel implementation because we are creative beings, means revisiting the specification and creating new implementation plans. This process is therefore a 0 -> 1, (1', ..), 2, 3, N. +Debugging means fixing specifications and their implementation plans that generate incorrect code. Refactoring means restructuring for clarity. The entire development process reorganizes around specifications as the central source of truth, with implementation plans and code as the continuously regenerated output. Updating apps with new features or creating a new parallel implementation because we are creative beings, means revisiting the specification and creating new implementation plans. This process is therefore a 0 -> 1, (1', ..), 2, 3, N. The development team focuses in on their creativity, experimentation, their critical thinking. ## The SDD Process in Practice -The workflow begins with an idea—often vague and incomplete. Through iterative dialogue with AI, this idea becomes a comprehensive PRD. The AI asks clarifying questions, identifies edge cases, and helps define precise acceptance criteria. What might take days of meetings and documentation in traditional development happens in hours of focused specification work. This transforms the traditional SDLC—requirements and design become continuous activities rather than discrete phases. This is supportive of a **team process**, where team-reviewed specifications are expressed, versioned, reviewed, and accepted. +The process begins with an idea—often vague and incomplete. Through iterative dialogue with AI, this idea becomes a comprehensive PRD. The AI asks clarifying questions, identifies edge cases, and helps define precise acceptance criteria. What might take days of meetings and documentation in traditional development happens in hours of focused specification work. This transforms the traditional SDLC—requirements and design become continuous activities rather than discrete phases. This is supportive of a **team process**, where team-reviewed specifications are expressed, versioned, reviewed, and accepted. When a product manager updates acceptance criteria, implementation plans automatically flag affected technical decisions. When an architect discovers a better pattern, the PRD updates to reflect new possibilities. @@ -42,7 +42,7 @@ Third, the pace of change accelerates. Requirements change far more rapidly toda SDD can support what-if/simulation experiments: "If we need to re-implement or change the application to promote a business need to sell more T-shirts, how would we implement and experiment for that?" -SDD transforms requirement changes from obstacles into normal workflow. When specifications drive implementation, pivots become systematic regenerations rather than manual rewrites. Change a core requirement in the PRD, and affected implementation plans update automatically. Modify a user story, and corresponding API endpoints regenerate. This isn't just about initial development—it's about maintaining engineering velocity through inevitable changes. +SDD transforms requirement changes from obstacles into normal process. When specifications drive implementation, pivots become systematic regenerations rather than manual rewrites. Change a core requirement in the PRD, and affected implementation plans update automatically. Modify a user story, and corresponding API endpoints regenerate. This isn't just about initial development—it's about maintaining engineering velocity through inevitable changes. ## Core Principles @@ -65,14 +65,14 @@ Today, practicing SDD requires assembling existing tools and maintaining discipl - AI assistants for iterative specification development - Research agents for gathering technical context - Code generation tools for translating specifications to implementation -- Version control systems adapted for specification-first workflows +- Version control systems adapted for specification-first processes - Consistency checking through AI analysis of specification documents The key is treating specifications as the source of truth, with code as the generated output that serves the specification rather than the other way around. ## Streamlining SDD with Commands -The SDD methodology is significantly enhanced through three powerful commands that automate the specification → planning → tasking workflow: +The SDD methodology is significantly enhanced through three powerful commands that automate the specification → planning → tasking process: ### The `/speckit.specify` Command @@ -104,7 +104,7 @@ After a plan is created, this command analyzes the plan and related design docum ### Example: Building a Chat Feature -Here's how these commands transform the traditional development workflow: +Here's how these commands transform the traditional development process: **Traditional Approach:** @@ -356,7 +356,7 @@ Governance MUST ensure: - Implementation gaps are addressed through specifications, not through untracked code changes ``` -This article ensures that governance is not static and that specifications remain the authoritative source. When a gap or requirement emerges during implementation, teams may create a new specification, update an existing one, or regenerate derived artifacts—whichever approach fits their workflow—as long as the specification continues to drive implementation rather than the reverse. +This article ensures that governance is not static and that specifications remain the authoritative source. When a gap or requirement emerges during implementation, teams may create a new specification, update an existing one, or regenerate derived artifacts—whichever approach fits their process—as long as the specification continues to drive implementation rather than the reverse. The constitution follows semantic versioning—major for removed or redefined principles, minor for additions, patch for clarifications. Specifications must be versioned and reviewable before acceptance. Together, these practices create an auditable trail of architectural and product decisions.