Updated unit content formatting based on Preview URLs

Author: ChrisHowd

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-greenfield-intro/2-what-spec-driven-development.yml

@@ -1,9 +1,9 @@
 ### YamlMime:ModuleUnit
 uid: learn.wwl.spec-driven-development-github-spec-kit-greenfield-intro.what-spec-driven-development
-title: "Understand spec-driven development"
+title: "What is spec-driven development?"
 metadata:
-  title: "Understand Spec-Driven Development"
-  description: "Understand spec-driven development."
+  title: "What is Spec-Driven Development?"
+  description: "What is spec-driven development?"
   ms.date: 01/26/2026
   author: chrishowd
   ms.author: cahowd

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-greenfield-intro/includes/2-what-spec-driven-development.md

@@ -32,11 +32,11 @@ Essentially, *the spec becomes the code's single source of truth*. In SDD, the s
 
 Three trends make SDD not just possible but necessary:
 
-**AI capabilities have crossed a critical threshold**. Natural language specifications can now reliably generate working code. This achievement isn't about replacing developers - it's about amplifying their effectiveness by automating the mechanical translation from specification to implementation. It can amplify exploration and creativity, support "start-over" easily, and support addition, subtraction, and critical thinking.
+- **AI capabilities have crossed a critical threshold**. Natural language specifications can now reliably generate working code. This achievement isn't about replacing developers - it's about amplifying their effectiveness by automating the mechanical translation from specification to implementation. It can amplify exploration and creativity, support "start-over" easily, and support addition, subtraction, and critical thinking.
 
-**Software complexity continues to grow exponentially**. Modern systems integrate dozens of services, frameworks, and dependencies. Keeping all these pieces aligned with original intent through manual processes becomes increasingly difficult. SDD provides systematic alignment through specification-driven generation.
+- **Software complexity continues to grow exponentially**. Modern systems integrate dozens of services, frameworks, and dependencies. Keeping all these pieces aligned with original intent through manual processes becomes increasingly difficult. SDD provides systematic alignment through specification-driven generation.
 
-**The pace of change accelerates**. Requirements shift far more rapidly today than ever before. Pivoting is no longer exceptional - it's expected. Modern product development demands rapid iteration based on user feedback, market conditions, and competitive pressures.
+- **The pace of change accelerates**. Requirements shift far more rapidly today than ever before. Pivoting is no longer exceptional - it's expected. Modern product development demands rapid iteration based on user feedback, market conditions, and competitive pressures.
 
 Traditional development treats requirement changes as disruptions. Each pivot requires manually propagating changes through documentation, design, and code. The result is either slow, careful updates that limit velocity, or fast, reckless changes that accumulate technical debt.
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-greenfield-intro/includes/3-examine-spec-driven-development-principles-processes.md

@@ -1,6 +1,6 @@
 The spec-driven development (SDD) methodology provides a phased approach to software development that emphasizes clarity, structure, and adaptability. By breaking down the development process into four distinct phases—Specify, Plan, Tasks, and Implement—SDD ensures that each step is well-defined and builds upon the previous one. This structured workflow not only enhances communication among stakeholders but also allows for continuous refinement and adaptation of the software being developed.
 
-## SDD workflow overview
+## Workflow phases in spec-driven development
 
 The SDD workflow transforms an idea into working code through four distinct phases. Each phase builds on the previous one, creating a clear progression from vision to execution. Think of it as a structured progression where each step has a clear output that feeds into the next.
 
@@ -31,7 +31,7 @@ A key aspect of SDD is that each phase has a validation step before moving forwa
 
 This structured progression is what gives SDD its reliability.
 
-## Living artifacts
+## Specifications as living artifacts
 
 Unlike static requirements documents that are created once and gradually become outdated, SDD outputs are **living artifacts** that can evolve. The spec might get updated as you learn new information, and then you'd adjust the plan and tasks accordingly.
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-greenfield-intro/includes/4-compare-spec-driven-development-other-methodologies.md

@@ -17,7 +17,9 @@ The following table summarizes key differences between SDD and other common meth
 
 Waterfall methodology emphasizes comprehensive upfront planning with requirements, design, implementation, testing, and deployment flowing sequentially. A requirements specification is written once at the beginning and often becomes stale as development progresses over months or years.
 
-**Key differences:**
+### Key differences between SDD and Waterfall
+
+There are several important distinctions between Waterfall and SDD:
 
 - **Specification lifecycle:** In Waterfall, the requirements document is a phase artifact that's created and then left behind. In SDD, the spec is continuously used and updated; it directly generates implementations rather than being just a phase document.
 
@@ -31,7 +33,9 @@ Waterfall methodology emphasizes comprehensive upfront planning with requirement
 
 Agile methodologies value "working software over comprehensive documentation," which might seem at odds with SDD's specification focus. However, the two approaches share more  than you might expect.
 
-**Key differences:**
+### Key differences between SDD and Agile/Scrum
+
+There are key distinctions between Agile/Scrum and SDD:
 
 - **Documentation philosophy:** Agile often minimizes documentation in favor of direct communication and working code. SDD doesn't mean writing a massive spec and never changing it - rather, any given increment (even within a sprint) starts with a clear spec and plan that can evolve.
 
@@ -45,43 +49,53 @@ Agile methodologies value "working software over comprehensive documentation," w
 
 TDD drives development by writing tests first. You begin by creating a failing test. Then you write code to pass the test. Finally, you refactor the code as needed. This red-green-refactor cycle guides design at the unit level.
 
-**Key differences:**
+### Key differences between SDD and TDD
+
+There are several important distinctions between TDD and SDD:
 
 - **Level of abstraction:** TDD operates at a low level (unit tests), whereas SDD works at a higher requirements level. TDD tests individual functions; SDD specifications describe complete features.
 
 - **Primary driver:** In TDD, tests drive the design. In SDD, the specification drives design and code. Both use "something before code" to guide development, but that something differs in scope.
 
 - **Role of acceptance criteria:** In SDD, the spec itself plays a role similar to a "super-test" by defining acceptance criteria for all functionality. Tasks in SDD function like guides for the AI - each task is small and verifiable, almost like an acceptance test the AI aims to satisfy.
 
-**Where they align:** Both methodologies encourage thinking about outcomes before writing implementation code. Both produce artifacts that can be verified.
+### Where SDD and TDD align
+
+Both methodologies encourage thinking about outcomes before writing implementation code. Both produce artifacts that can be verified.
 
-**How they complement:** TDD and SDD aren't mutually exclusive. You can use SDD to produce a clear direction and still use TDD within implementation for code quality. SDD can even generate test specifications as part of the tasks phase, which developers then implement using TDD practices.
+### How SDD and TDD complement each other
+
+TDD and SDD aren't mutually exclusive. You can use SDD to produce a clear direction and still use TDD within implementation for code quality. SDD can even generate test specifications as part of the tasks phase, which developers then implement using TDD practices.
 
 ## SDD vs. Behavior-Driven Development (BDD)
 
 BDD focuses on user behavior using Given-When-Then scenarios to drive development. These scenarios become automated tests that developers satisfy with code.
 
-**Key differences:**
+### Key differences between SDD and BDD
 
 - **Execution model:** BDD results in automated tests that developers then write code to satisfy. SDD's spec and plan result in tasks and code generated with AI assistance.
 
 - **Artifact focus:** BDD produces executable behavioral scenarios. SDD produces specifications that drive AI-generated implementations.
 
-**Where they align:** Both put requirements first and focus on the "what and why" before implementation. Both emphasize understanding user needs before coding.
+### Where SDD and BDD align
+
+Both put requirements first and focus on the "what and why" before implementation. Both emphasize understanding user needs before coding.
+
+### How SDD and BDD complement each other
 
-**How they complement:** You can integrate BDD-style scenarios into the SDD spec - for example, listing Gherkin scenarios as part of requirements. The AI could use those scenarios to validate the implementation if tests are generated as part of the tasks. This combination gives you the best of both worlds: precise behavioral specifications and AI-accelerated implementation.
+You can integrate BDD-style scenarios into the SDD spec - for example, listing Gherkin scenarios as part of requirements. The AI could use those scenarios to validate the implementation if tests are generated as part of the tasks. This combination gives you the best of both worlds: precise behavioral specifications and AI-accelerated implementation.
 
 ## Where SDD shines
 
 SDD is particularly powerful in specific scenarios:
 
-**Complex projects with clear goals:** When investing time to specify yields significant returns - enterprise systems, mission-critical applications, or projects with regulatory requirements. The upfront investment in specification pays dividends throughout development and maintenance.
+- **Complex projects with clear goals:** When investing time to specify yields significant returns - enterprise systems, mission-critical applications, or projects with regulatory requirements. The upfront investment in specification pays dividends throughout development and maintenance.
 
-**AI-accelerated development:** Teams using AI tools benefit most by structuring their input to the AI. A well-crafted specification gives AI assistants the context they need to generate accurate, useful implementations rather than code that needs extensive correction.
+- **AI-accelerated development:** Teams using AI tools benefit most by structuring their input to the AI. A well-crafted specification gives AI assistants the context they need to generate accurate, useful implementations rather than code that needs extensive correction.
 
-**Cross-team communication:** The spec and plan artifacts serve as clear communication mediums between product managers, developers, and AI agents. Everyone works from the same source of truth, reducing misalignment and rework.
+- **Cross-team communication:** The spec and plan artifacts serve as clear communication mediums between product managers, developers, and AI agents. Everyone works from the same source of truth, reducing misalignment and rework.
 
-**Projects with multiple implementation approaches:** SDD's separation of specification from implementation means you can generate multiple approaches from the same spec - exploring different optimization targets for performance, maintainability, or cost.
+- **Projects with multiple implementation approaches:** SDD's separation of specification from implementation means you can generate multiple approaches from the same spec - exploring different optimization targets for performance, maintainability, or cost.
 
 ## When to use lighter approaches
 

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-greenfield-intro/includes/5-examine-spec-driven-development-workflow-phases.md

@@ -22,6 +22,7 @@ A well-structured specification includes several key sections:
 - **User stories:** Brief narrative descriptions of how users interact with the feature. User stories capture intent and value rather than technical implementation.
 
     For example:
+
     - As a user, I want to add RSS feeds by URL so that I can follow my favorite websites.
     - As a user, I want to see unread articles sorted newest-first so that I can catch up on recent content.
 
@@ -96,11 +97,11 @@ This task is specific about what to build, what it accepts, what validations to
 
 Complex features benefit from organizing tasks into phases:
 
-- **Phase 1 – Foundation:** Set up project structure, create database schema, and add required packages.
-- **Phase 2 – Core functionality:** Implement feed parsing, add URL validation, and implement article storage.
-- **Phase 3 – User interface:** Create feed list view, add article display, and implement read/unread tracking.
-- **Phase 4 – Security:** Add HTML sanitization, implement HTTPS-only feed fetching, and add error handling.
-- **Phase 5 – Testing:** Write unit tests, create integration tests, and document the application.
+1. **Phase 1 – Foundation:** Set up project structure, create database schema, and add required packages.
+1. **Phase 2 – Core functionality:** Implement feed parsing, add URL validation, and implement article storage.
+1. **Phase 3 – User interface:** Create feed list view, add article display, and implement read/unread tracking.
+1. **Phase 4 – Security:** Add HTML sanitization, implement HTTPS-only feed fetching, and add error handling.
+1. **Phase 5 – Testing:** Write unit tests, create integration tests, and document the application.
 
 ### Task dependencies
 
@@ -119,6 +120,8 @@ If phases 1-3 are done well, implementation should be straightforward. You can e
 
 ### The implementation process
 
+Implementation follows a simple loop:
+
 1. Select the next task from the tasks list.
 1. Write code to implement the task (manually or using AI assistance).
 1. Test that the task meets spec and plan expectations.

learn-pr/wwl-azure/spec-driven-development-github-spec-kit-greenfield-intro/includes/6-introduction-github-spec-kit.md

@@ -20,11 +20,11 @@ Key point: GitHub Spec Kit isn't an AI model itself - it's a framework and CLI t
 
 GitHub Spec Kit's design directly implements SDD principles:
 
-**Executable specifications:** GitHub Spec Kit makes the spec "executable" by using it to drive code generation through commands. Your specification isn't just documentation - it's the input that produces implementation.
+- **Executable specifications:** GitHub Spec Kit makes the spec "executable" by using it to drive code generation through commands. Your specification isn't just documentation - it's the input that produces implementation.
 
-**Structured workflow enforcement:** GitHub Spec Kit guides you through phases in order. You can't effectively implement without first having a spec and plan, because the tool's workflow is designed to build each phase on the previous one.
+- **Structured workflow enforcement:** GitHub Spec Kit guides you through phases in order. You can't effectively implement without first having a spec and plan, because the tool's workflow is designed to build each phase on the previous one.
 
-**Intent-first approach:** You always start by explicitly stating intent (in the spec) in the tool's flow. The creators' goal was to let developers focus on product requirements and outcomes, while the AI handles the boilerplate code.
+- **Intent-first approach:** You always start by explicitly stating intent (in the spec) in the tool's flow. The creators' goal was to let developers focus on product requirements and outcomes, while the AI handles the boilerplate code.
 
 ## Supported project types
 
@@ -69,10 +69,10 @@ When you set up GitHub Spec Kit, you get several integrated components:
 The `specify` command-line tool initializes and manages spec-driven projects. When you run `specify init` in your project directory, it:
 
 1. Prompts you to select your AI coding assistant
-2. Creates a `.github/prompts/` directory with workflow templates
-3. Generates a project structure with folders for specifications
-4. Creates template files: constitution.md, spec.md, plan.md, tasks.md
-5. Configures integration with your chosen AI assistant
+1. Creates a `.github/prompts/` directory with workflow templates
+1. Generates a project structure with folders for specifications
+1. Creates template files: constitution.md, spec.md, plan.md, tasks.md
+1. Configures integration with your chosen AI assistant
 
 ### Markdown artifact files
 
@@ -106,15 +106,17 @@ The underlying specification artifacts (spec.md, plan.md, tasks.md) remain ident
 
 ## Why use GitHub Spec Kit?
 
-**Efficiency:** It drafts specs and plans quickly with AI. What might take hours to write from scratch, GitHub Spec Kit can generate in minutes (though you refine it).
+GitHub Spec Kit offers several advantages for developers adopting spec-driven development with AI assistance:
 
-**Consistency:** It enforces a consistent format via templates and a consistent approach every time - valuable for teamwork and repeatable processes.
+- **Efficiency:** It drafts specs and plans quickly with AI. What might take hours to write from scratch, GitHub Spec Kit can generate in minutes (though you refine it).
 
-**Multi-agent flexibility:** Use the AI environment you prefer (Visual Studio Code with GitHub Copilot, Claude, or others) without changing your workflow.
+- **Consistency:** It enforces a consistent format via templates and a consistent approach every time - valuable for teamwork and repeatable processes.
 
-**Enterprise ready:** The constitution concept means GitHub Spec Kit is ready to encode company-wide best practices and ensure AI follows them in every plan.
+- **Multi-agent flexibility:** Use the AI environment you prefer (Visual Studio Code with GitHub Copilot, Claude, or others) without changing your workflow.
 
-**Open source and extensible:** Organizations can customize templates, contribute improvements, or integrate GitHub Spec Kit with their systems.
+- **Enterprise ready:** The constitution concept means GitHub Spec Kit is ready to encode company-wide best practices and ensure AI follows them in every plan.
+
+- **Open source and extensible:** Organizations can customize templates, contribute improvements, or integrate GitHub Spec Kit with their systems.
 
 GitHub Spec Kit empowers you to accomplish in minutes what might otherwise take days - it's like having an AI project manager guiding your code generation while you focus on what matters: the product requirements and outcomes.