Updated the units that were affected by the new introductory module. Includes additional Acrolinx pass.

Author: ChrisHowd

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

@@ -4,7 +4,7 @@ Spec-driven development (SDD) represents a fundamental shift in how software is
 
 In traditional development, code is the source of truth—specifications serve code, often becoming outdated as implementation evolves. SDD inverts this relationship: **specifications become the primary artifact, and code serves specifications**. This paradigm shift enables AI-assisted development that maintains alignment between intent and implementation.
 
-**Core SDD principles to remember:**
+Core SDD principles to remember:
 
 - **Specifications as the primary artifact**: The spec is the central source of truth. Code becomes its expression in a particular language and framework. Maintaining software means evolving specifications, not just patching code.
 
@@ -14,12 +14,12 @@ In traditional development, code is the source of truth—specifications serve c
 
 - **AI-human collaboration**: AI transforms specs to code, but raw AI generation without structure produces chaos. SDD provides that structure through well-defined specifications and implementation plans.
 
-**The four-phase SDD workflow:**
+The four-phase SDD workflow:
 
 1. **Specify**: Define *what* the software should do and *why*—user stories, acceptance criteria, requirements, and edge cases.
-2. **Plan**: Decide *how* to build it—architecture, technology stack, and implementation approach.
-3. **Tasks**: Break down the plan into discrete, actionable development tasks organized by phase.
-4. **Implement**: Write code guided by the spec, plan, and task list, verifying each task against the specification.
+1. **Plan**: Decide *how* to build it—architecture, technology stack, and implementation approach.
+1. **Tasks**: Break down the plan into discrete, actionable development tasks organized by phase.
+1. **Implement**: Write code guided by the spec, plan, and task list, verifying each task against the specification.
 
 Each phase produces artifacts that feed into the next, creating a traceable path from requirements to working code.
 
@@ -33,7 +33,7 @@ Three trends make SDD essential for enterprise teams:
 
 - **Pace of change**: Requirements change rapidly. SDD transforms requirement changes from obstacles into normal workflow—update the spec, and affected artifacts regenerate systematically.
 
-For enterprise developers, SDD offers additional benefits: consistent alignment with organizational standards, auditable documentation of requirements and decisions, and systematic enforcement of security and compliance policies through the specification process.
+For enterprise developers, SDD offers the following benefits: consistent alignment with organizational standards, auditable documentation of requirements and decisions, and systematic enforcement of security and compliance policies through the specification process.
 
 ## Applying SDD in brownfield scenarios
 

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

@@ -4,21 +4,23 @@ GitHub Spec Kit is an open-source toolkit that enables spec-driven development b
 
 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
-- **Reusable commands**: Built-in slash commands encapsulate best-practice prompting patterns
+- **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.
+- **Reusable commands**: Built-in slash commands encapsulate best-practice prompting patterns.
 
-**Core components:**
+### Core components
+
+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` |
 
-**Supported AI agents:** GitHub Copilot, Claude Code, Cursor, Windsurf, Amazon Q Developer, and others. Each agent receives templates formatted for its specific prompt format while using the same underlying artifact files.
+### AI agents
 
-This module assumes you understand these basics and focuses on advanced techniques for enterprise development. If you need a detailed introduction to GitHub Spec Kit installation and basic usage, refer to the introductory module on spec-driven development.
+GitHub Spec Kit supports the following AI agents: GitHub Copilot, Claude Code, Cursor, Windsurf, Amazon Q Developer, and others. Each agent receives templates formatted for its specific prompt format while using the same underlying artifact files.
 
 ### Environment variables for feature tracking
 

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

@@ -2,15 +2,14 @@ The constitution is the foundation of spec-driven development with GitHub Spec K
 
 ## Review constitution basics
 
-A constitution file captures non-negotiable principles, constraints, and standards that govern your project. It serves as guardrails for AI-assisted development—when AI generates specs, plans, or code, it references the constitution to verify proposals comply with your standards.
+A constitution file captures non-negotiable principles, constraints, and standards that govern your project. It also serves as a guardrail for AI-assisted development. When the agent generates specs, plans, tasks, or code, it references the constitution to verify proposals comply with your standards.
 
-**Key purposes:**
-- **Consistency enforcement**: Ensures alignment with architectural decisions across long projects and multiple developers
-- **Compliance documentation**: Makes regulatory requirements and security policies explicit and auditable
-- **Institutional knowledge capture**: Preserves hard-won lessons in a form that guides AI code generation
-- **Reduced cognitive load**: Automates enforcement of organizational policies during development
+Key benefits of a well-defined constitution include:
 
-With this foundation in mind, let's explore how to structure constitutions for enterprise development scenarios.
+- **Consistency enforcement**: Ensures alignment with architectural decisions across long projects and multiple developers.
+- **Compliance documentation**: Makes regulatory requirements and security policies explicit and auditable.
+- **Institutional knowledge capture**: Preserves hard-won lessons in a form that guides AI code generation.
+- **Reduced cognitive load**: Automates enforcement of organizational policies during development.
 
 ## Purpose of the constitution
 

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

@@ -4,14 +4,12 @@ The specification file (`spec.md`) is the single source of truth for what your f
 
 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
-- **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
-- **Edge cases**: Unusual scenarios, error conditions, and boundary behaviors
-
-With these fundamentals in mind, let's explore enterprise-specific considerations for specification writing.
+- **Summary**: Concise description of the feature from an end-user perspective.
+- **User stories**: Brief narratives of how users interact with the feature.
+- **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.
+- **Edge cases**: Unusual scenarios, error conditions, and boundary behaviors.
 
 ## The spec as the single source of truth
 

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

@@ -4,17 +4,17 @@ A specification defines what you need to build. A technical plan defines how you
 
 The plan.md file serves as your design document, bridging the gap between high-level requirements in spec.md and the concrete implementation tasks that follow. A comprehensive technical plan contains:
 
-- **Architecture overview**: High-level view of how components interact
-- **Technology stack and key decisions**: Explicit documentation of technology choices with rationales
-- **Implementation sequence**: Logical progression of implementation steps
-- **Constitution verification**: Explicit check that proposed solutions comply with project principles
-- **Assumptions and open questions**: Documentation of assumptions and unresolved questions
+- **Architecture overview**: High-level view of how components interact.
+- **Technology stack and key decisions**: Explicit documentation of technology choices with rationales.
+- **Implementation sequence**: Logical progression of implementation steps.
+- **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.
 
-## Understand the purpose of a technical plan
+## 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.
 

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

@@ -4,15 +4,16 @@ Technical plans provide architectural direction, but implementation requires con
 
 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.
 
-**Key characteristics of well-scoped tasks:**
-- **Actionable**: Clearly states what needs to be done
-- **Testable**: Verification of completion is straightforward
-- **Independent**: Can be completed without waiting for unrelated work
-- **Time-bounded**: Completable in a reasonable timeframe (hours to a day)
+Key characteristics of well-scoped tasks:
 
-**Phase-based organization:** Complex features benefit from organizing tasks into phases—Foundation, Core Functionality, UI/Integration, Security, and Testing. Each phase represents a logical grouping that builds toward a milestone.
+- **Actionable**: Clearly states what needs to be done.
+- **Testable**: Verification of completion is straightforward.
+- **Independent**: Can be completed without waiting for unrelated work.
+- **Time-bounded**: Can be completed in a reasonable timeframe (hours to a day).
 
-With these fundamentals in mind, let's explore advanced task management techniques for enterprise development.
+### Phase-based organization
+
+Complex features benefit from organizing tasks into phases. For example: Setup, Foundation, Core Functionality, UI/Integration, Security, and Testing. Each phase represents a logical grouping that builds toward a milestone.
 
 ## Benefits of task breakdown
 
@@ -38,15 +39,15 @@ For the document upload feature, a typical phase structure might include:
     - Create the DocumentMetadata table in SQL database with appropriate schema.
     - Add the Azure.Storage.Blobs NuGet package to the back-end project.
     - Create the DocumentService class that encapsulates storage operations.
-    
+
 - **Phase 2: Core Upload Functionality**
 
     - Implement POST /api/documents/upload endpoint in DocumentsController.
     - Add file validation logic (size, type) to DocumentService.
     - Implement blob storage upload method with error handling.
     - Save document metadata to database after successful upload.
     - Return upload result with document ID and URL to client.
-    
+
 - **Phase 3: Front-end Implementation**
 
     - Create DocumentUpload React component with file input.
@@ -90,7 +91,7 @@ This task is specific about what to build (an endpoint), what it accepts (multip
 
 Here's an example of an insufficiently scoped task: "Make the upload work." This example provides no actionable guidance about what "work" means or what components are involved.
 
-Here'e and example of an overly prescriptive task: "On line 47 of DocumentsController.cs, add a method named UploadDocument with parameters (IFormFile file, string userId) and implement it using exactly these steps..." This task description removes developer agency and doesn't account for evolving code structure.
+Here's an example of an overly prescriptive task: "On line 47 of DocumentsController.cs, add a method named UploadDocument with parameters (IFormFile file, string userId) and implement it using exactly these steps..." This task description removes developer agency and doesn't account for evolving code structure.
 
 ### Task dependencies and sequencing
 
@@ -211,9 +212,9 @@ This command instructs the AI to focus on tasks T001 through T027, generating co
 
 ### Provide assistance during implementation
 
-The AI might require assistance or permission to proceed with certain tasks. For example, if a task requires building or running the app, the AI may prompt for confirmation before proceeding.
+The AI might require assistance or permission to proceed with certain tasks. For example, if a task requires building or running the app, the AI might prompt for confirmation before proceeding.
 
-In addition, the AI might discover a bug when testing the implementation of a task. Provide detailed information to help diagnose the issue.  You can also provide additional context or clarifications if the AI encounters ambiguities.
+In addition, the AI might discover a bug when testing the implementation of a task. Provide detailed information to help diagnose the issue. You can also provide extra context or clarifications if the AI encounters ambiguities.
 
 When prompted for assistance in the Chat view, a quick response helps to keep implementation moving smoothly.