Updated top sections to reduce duplication

Author: ChrisHowd

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/includes/2-review-spec-driven-development-approach.md

@@ -39,8 +39,8 @@ For enterprise developers, SDD offers the following benefits: consistent alignme
 
 While SDD excels at greenfield development, enterprise developers often work with existing codebases. When adding features to established systems:
 
-- Your **constitution** documents existing architectural patterns and constraints
-- Feature **specifications** acknowledge existing infrastructure and integration points
-- **Plans** show how new features integrate with current architecture rather than proposing isolated implementations
+- Your **constitution** documents existing architectural patterns and constraints.
+- Feature **specifications** acknowledge existing infrastructure and integration points.
+- **Plans** show how new features integrate with current architecture rather than proposing isolated implementations.
 
 This module focuses on applying SDD with GitHub Spec Kit to enhance existing enterprise applications—adding sophisticated features while maintaining consistency with established patterns and organizational standards.

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/includes/3-examine-github-spec-kit.md

@@ -1,11 +1,11 @@
-GitHub Spec Kit is an open-source toolkit that enables spec-driven development by integrating specifications with AI coding assistants. Before exploring advanced features, let's review the foundational concepts.
+GitHub Spec Kit is an open-source toolkit that enables spec-driven development (SDD) by integrating specifications with AI coding assistants. Before exploring advanced features, let's review the foundational concepts.
 
 ## Review GitHub Spec Kit basics
 
 GitHub Spec Kit addresses a fundamental challenge in AI-assisted development: maintaining context and consistency across multiple interactions with coding assistants. It provides three essential capabilities:
 
-- **Persistent artifacts**: Specifications, plans, and tasks are stored as Markdown files in your repository.
-- **Standardized workflow**: A defined process guides you through specification, planning, task breakdown, and implementation.
+- **Persistent artifacts**: Specifications, plans, and tasks are stored as markdown files in your repository.
+- **Standardized workflow**: A defined process guides you through the four SDD phases: specification, planning, task breakdown, and implementation.
 - **Reusable commands**: Built-in slash commands encapsulate best-practice prompting patterns.
 
 ### Core components
@@ -14,9 +14,9 @@ GitHub Spec Kit implements the following core components:
 
 | Component | Purpose |
 |-----------|---------|
-| `specify` CLI | Initializes and manages spec-driven projects |
-| Markdown artifact files | constitution.md, spec.md, plan.md, tasks.md drive development |
-| Slash commands | `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement` |
+| `specify` CLI | Initializes and manages spec-driven projects. |
+| Markdown artifact files | `constitution.md`, `spec.md`, `plan.md`, `tasks.md` drive development. |
+| Slash commands | `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement` invoke GitHub Spec Kit workflows. |
 
 ### AI agents
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/includes/4-establish-project-principles-constitution-file.md

@@ -13,19 +13,17 @@ Key benefits of a well-defined constitution include:
 
 ## Purpose of the constitution
 
-In spec-driven development, the constitution serves as your project's immutable rule set. It documents what must always be true, regardless of which features you build or how requirements evolve.
+The benefits of a well-defined constitution become powerful in practice through automatic enforcement. If the constitution states "All data must be encrypted at rest," the AI agent doesn't suggest storing files in plaintext—it automatically incorporates encryption into designs. When you generate a specification for file uploads, the plan includes Azure Storage encryption configuration. When you generate the code, your implementation uses encrypted storage services.
 
-Think of the constitution as guardrails for AI-assisted development. When AI agent generates a spec, a plan, or code, it references the constitution to verify proposals comply with your standards. If the constitution states "All data must be encrypted at rest," the agent doesn't suggest storing files in plaintext—it automatically incorporates encryption into designs.
+Consider how each benefit manifests in real development scenarios:
 
-The constitution addresses several critical needs:
+- **Consistency enforcement**: Projects spanning months or involving multiple developers can drift from architectural decisions. Without a constitution, one developer might use local file storage while another uses Azure Blob Storage for similar features. The constitution prevents this drift by encoding standards that AI assistants always reference, ensuring uniform technology choices across all features.
 
-- **Consistency enforcement**: Projects spanning months or involving multiple developers can drift from architectural decisions. The constitution ensures alignment by encoding standards that AI assistants always reference.
+- **Compliance documentation**: Regulatory requirements, security policies, and internal governance rules must be followed. The constitution makes requirements explicit, creating an auditable record of how you enforce compliance. When an auditor asks "How do you ensure personal data isn't logged?", you point to the constitution requirement and show that all generated code respects this constraint.
 
-- **Compliance documentation**: Regulatory requirements, security policies, and internal governance rules must be followed. The constitution makes requirements explicit, creating an auditable record of how you enforce compliance.
+- **Institutional knowledge capture**: Experienced architects and security teams make decisions based on hard-won lessons—like discovering that certain API patterns cause performance issues or that specific authentication flows create security vulnerabilities. The constitution preserves this wisdom in a form that guides AI code generation, preventing new team members from repeatedly rediscovering the same constraints.
 
-- **Institutional knowledge capture**: Experienced architects and security teams make decisions based on hard-won lessons. The constitution preserves this wisdom in a form that guides AI code generation, preventing repeatedly rediscovering the same constraints.
-
-- **Reduced cognitive load**: Developers don't need to remember every organizational standard while prompting AI. The constitution automates enforcement of policies like "use Azure Key Vault for secrets" or "authenticate via Microsoft Entra ID."
+- **Reduced cognitive load**: Developers don't need to remember every organizational standard while prompting AI. The constitution automates enforcement of policies like "use Azure Key Vault for secrets" or "authenticate via Microsoft Entra ID." Instead of manually checking each generated plan against a checklist of requirements, the AI incorporates them automatically.
 
 In enterprise development environments, constitutions often encode:
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/includes/5-write-effective-spec-file.md

@@ -1,11 +1,11 @@
-The specification file (`spec.md`) is the single source of truth for what your feature should do. This unit covers advanced techniques for writing enterprise-grade specifications.
+The specification file (`spec.md`) is the single source of truth for what your software should do. This unit covers advanced techniques for writing enterprise-grade specifications.
 
 ## Review spec fundamentals
 
 In spec-driven development, the specification defines exactly what the software should do, and every implementation decision traces back to it. A well-structured specification includes:
 
-- **Summary**: Concise description of the feature from an end-user perspective.
-- **User stories**: Brief narratives of how users interact with the feature.
+- **Summary**: Concise description of the application (or new feature) from an end-user perspective.
+- **User stories**: Brief narratives of how users interact with the application.
 - **Acceptance criteria**: Specific, testable conditions that must be true for completion.
 - **Functional requirements**: Detailed descriptions of system behavior.
 - **Nonfunctional requirements**: Quality attributes like performance, security, and scalability.
@@ -17,7 +17,7 @@ In spec-driven development, the specification defines exactly what the software
 
 This approach represents a mindset shift: writing the spec is as important as writing code. The spec isn't a formality to satisfy project management—it's the artifact that drives AI code generation. Invest the same care in crafting specs as you would in implementing features manually.
 
-Think of the spec as executable documentation. When you modify requirements, you update the spec and regenerate the plan and tasks. The spec version-controlled in Git becomes the authoritative record of what each feature should accomplish.
+Think of the spec as executable documentation. When you modify requirements, you update the spec and regenerate the plan and tasks. The spec, which is version-controlled in Git, becomes the authoritative record of what each feature should accomplish.
 
 For enterprise developers accustomed to agile workflows, the spec serves the same purpose as detailed user stories and acceptance criteria, but with machine-readable structure that AI assistants can consume directly.
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/includes/6-create-technical-plan-file.md

@@ -10,17 +10,13 @@ The plan.md file serves as your design document, bridging the gap between high-l
 - **Constitution verification**: Explicit check that proposed solutions comply with project principles.
 - **Assumptions and open questions**: Documentation of assumptions and unresolved questions.
 
-This separation of concerns is fundamental—specifications remain stable and focused on "what," while plans can evolve as you experiment with different "how" approaches. If you later switch technologies, you update plan.md while spec.md remains largely unchanged.
-
 With these fundamentals in mind, let's explore advanced planning considerations for enterprise development.
 
-## Examine the purpose of a technical plan
-
-The plan.md file serves as your design document. It bridges the gap between high-level requirements in spec.md and the concrete implementation tasks that follow. While the specification remains stable and focused on "what," the plan can evolve as you experiment with different "how" approaches.
+## Separation of concerns - spec versus plan
 
-This separation of concerns is fundamental to spec-driven development. If you later switch from one technology to another—say, moving from Azure Blob Storage to Azure Files—you update plan.md while spec.md remains largely unchanged. The feature requirements aren't changed; only the implementation approach is changed.
+The separation of concerns between specification and technical plan is crucial. While the specification remains stable and focused on "what," the plan can evolve as you experiment with different "how" approaches.
 
-For the document upload feature, the specification defines user requirements: file size limits, supported formats, upload feedback, and access controls. The plan translates these requirements into concrete decisions: which Azure storage service to use, how to structure the API, which authentication mechanism to implement, and how to validate files.
+Suppose your specification requires a document upload feature for an internal employee portal. The spec defines user requirements: file size limits, supported formats, upload feedback, and access controls. The technical plan translates these requirements into concrete architectural decisions: which Azure storage service to use, how to structure the API, which authentication mechanism to implement, and how to validate files. If you decide to switch from one technology to another, such as moving from Azure Blob Storage to Azure Files, you update plan.md while spec.md remains largely unchanged. The feature requirements aren't changed; only the implementation approach is changed.
 
 ## Examine plan structure and content
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/includes/7-generate-implementation-tasks-file.md

@@ -2,7 +2,7 @@ Technical plans provide architectural direction, but implementation requires con
 
 ## Review task fundamentals
 
-The `/speckit.tasks` command converts high-level architectural decisions into specific work items in the tasks.md file. Each task represents a discrete unit of work that can be implemented, tested, and verified independently.
+GitHub Spec Kit's `/speckit.tasks` command converts high-level architectural decisions into specific work items in the tasks.md file. Each task represents a discrete unit of work that can be implemented, tested, and verified independently.
 
 Key characteristics of well-scoped tasks:
 
@@ -17,8 +17,6 @@ Complex features benefit from organizing tasks into phases. For example: Setup,
 
 ## Benefits of task breakdown
 
-The `/speckit.tasks` command converts high-level architectural decisions into specific work items in the tasks.md file. Each task represents a discrete unit of work that can be implemented, tested, and verified independently. This granular approach prevents overwhelming complexity and provides clear checkpoints throughout the implementation process.
-
 Task breakdowns serve multiple purposes beyond just organizing work. They help the AI generate focused code for specific objectives rather than attempting to implement entire features in single operations. They create natural verification points where you can test partial implementations before proceeding. They enable accurate progress tracking by showing exactly what's complete and what remains. They facilitate team coordination by making dependencies explicit.
 
 For the document upload feature, the plan describes the overall architecture and technology choices. The task list translates architectural decisions into specific actions: create a database table, implement an API endpoint, build a React component, add validation logic, write tests. Each task is small enough to complete in a reasonable timeframe while large enough to represent meaningful progress.

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-enterprise-developers/index.yml

@@ -2,24 +2,26 @@
 uid: learn.spec-driven-development-github-spec-kit-microsoft-internal
 metadata:
   title: Implement Spec-Driven Development using the GitHub Spec Kit
-  description: "Implement the Spec-Driven Development methodology using GitHub Spec Kit and GitHub Copilot in Visual Studio Code. Training covers a brownfield scenario for enterprise developers, emphasizing intent-first philosophy with living specifications."
+  description: "Implement the spec-driven development methodology using GitHub Spec Kit and GitHub Copilot in Visual Studio Code. Training covers a brownfield scenario for enterprise developers, emphasizing intent-first philosophy with living specifications."
   ms.date: 1/28/2026
   author: chrishowd
   ms.author: cahowd
   ms.topic: module-standard-task-based # Please don't edit, used for our analytics
   ms.service: github-copilot
 title: Implement spec-driven development using the GitHub Spec Kit
-summary: "Implement the Spec-Driven Development methodology using GitHub Spec Kit and GitHub Copilot in Visual Studio Code. Training covers a brownfield scenario for enterprise developers, emphasizing intent-first philosophy with living specifications."
+summary: "Implement the spec-driven development methodology using GitHub Spec Kit and GitHub Copilot in Visual Studio Code. Training covers a brownfield scenario for enterprise developers, emphasizing intent-first philosophy with living specifications."
 abstract: |
   By the end of this module, you're able to:
-    - Explain Spec-Driven Development principles and why they benefit large-scale enterprise projects (upfront clarity, fewer regressions, easier maintenance).
+    - Explain spec-driven development methodology and why it benefits large-scale enterprise projects (upfront clarity, fewer regressions, easier maintenance).
     - Implement the GitHub Spec Kit and GitHub Copilot in Visual Studio Code to generate project artifacts (specifications, plans, tasks) aligned with enterprise development standards.
     - Apply the GitHub Spec Kit in an Azure-integrated scenario, encoding internal engineering guidelines (security, performance, compliance) in a project "Constitution" and ensuring generated plans adhere to these constraints.
     - Execute a spec-driven workflow to build a new feature, from spec creation through automated code generation and iteration.
     - Describe how to integrate GitHub Spec Kit into team workflows, how to use it alongside Azure DevOps/GitHub Enterprise, and how to extend it for advanced scenarios (such as multi-agent collaboration and CI/CD integration).
 prerequisites: |
   - Experience using GitHub Copilot in Visual Studio Code.
   - Experience developing applications.
+  - General understanding of spec-driven development is recommended.
+  - Familiarity with GitHub Spec Kit is recommended.
 iconUrl: /learn/achievements/generic-badge.svg
 levels:
   - intermediate