---
# Story Template Metadata
template_version: "3.1"
last_updated: "2026-04-22"
format_version: "3.1"
template_updated: 2026-04-22
---

<!-- SECTION_MANIFEST
last_verified: "2026-04-22"
sections:
  - name: "Description"
    header_level: 2
    line_range: {start: 385, end: 393}
    status: "Required"
  - name: "Provenance"
    header_level: 2
    line_range: {start: 394, end: 441}
    status: "Required"
    validation:
      min_origin_count: 2
      required_origin_trace: "brainstorm OR epic"
      enforcement: "conditional_halt"
      skip_when: "no_epic_association"
  - name: "Acceptance Criteria"
    header_level: 2
    line_range: {start: 442, end: 562}
    status: "Required"
  - name: "Technical Specification"
    header_level: 2
    line_range: {start: 563, end: 725}
    status: "Required"
  - name: "Implementation Guide"
    header_level: 2
    line_range: {start: 726, end: 789}
    status: "Conditional"
  - name: "Technical Limitations"
    header_level: 2
    line_range: {start: 790, end: 818}
    status: "Required"
  - name: "Non-Functional Requirements (NFRs)"
    header_level: 2
    line_range: {start: 819, end: 923}
    status: "Required"
  - name: "Dependencies"
    header_level: 2
    line_range: {start: 924, end: 967}
    status: "Required"
  - name: "Test Strategy"
    header_level: 2
    line_range: {start: 968, end: 1004}
    status: "Required"
  - name: "Acceptance Criteria Verification Checklist"
    header_level: 2
    line_range: {start: 1005, end: 1047}
    status: "Required"
  - name: "Edge Cases"
    header_level: 2
    status: "Required"
  - name: "Definition of Done"
    header_level: 2
    line_range: {start: 1048, end: 1088}
    status: "Required"
  - name: "Change Log"
    header_level: 2
    line_range: {start: 1089, end: 1096}
    status: "Required"
  - name: "Notes"
    header_level: 2
    line_range: {start: 1097, end: 1125}
    status: "Required"
  - name: "XML Acceptance Criteria Format"
    header_level: 3
    line_range: {start: 448, end: 467}
    status: "Required"
  - name: "Source Files Guidance"
    header_level: 3
    line_range: {start: 537, end: 562}
    status: "Required"
  - name: "Architecture Decisions"
    header_level: 3
    line_range: {start: 733, end: 740}
    status: "Conditional"
  - name: "Cross-Cutting Concerns"
    header_level: 3
    line_range: {start: 741, end: 750}
    status: "Conditional"
  - name: "Implementation Sequence"
    header_level: 3
    line_range: {start: 751, end: 758}
    status: "Conditional"
  - name: "Task Prompt Templates"
    header_level: 3
    line_range: {start: 759, end: 772}
    status: "Conditional"
  - name: "Anti-Patterns"
    header_level: 3
    line_range: {start: 773, end: 779}
    status: "Conditional"
  - name: "Patterns and References"
    header_level: 3
    line_range: {start: 780, end: 789}
    status: "Conditional"
  - name: "Performance"
    header_level: 3
    line_range: {start: 821, end: 837}
    status: "Required"
  - name: "Security"
    header_level: 3
    line_range: {start: 838, end: 866}
    status: "Required"
  - name: "Scalability"
    header_level: 3
    line_range: {start: 867, end: 884}
    status: "Required"
  - name: "Reliability"
    header_level: 3
    line_range: {start: 885, end: 902}
    status: "Required"
  - name: "Observability"
    header_level: 3
    line_range: {start: 903, end: 923}
    status: "Required"
  - name: "Prerequisite Stories"
    header_level: 3
    line_range: {start: 926, end: 937}
    status: "Required"
  - name: "External Dependencies"
    header_level: 3
    line_range: {start: 938, end: 952}
    status: "Required"
  - name: "Technology Dependencies"
    header_level: 3
    line_range: {start: 953, end: 967}
    status: "Required"
  - name: "Unit Tests"
    header_level: 3
    line_range: {start: 970, end: 988}
    status: "Required"
  - name: "Integration Tests"
    header_level: 3
    line_range: {start: 989, end: 998}
    status: "Required"
  - name: "E2E Tests"
    header_level: 3
    line_range: {start: 999, end: 1004}
    status: "Optional"
  - name: "Implementation"
    header_level: 3
    line_range: {start: 1050, end: 1055}
    status: "Required"
  - name: "Quality"
    header_level: 3
    line_range: {start: 1056, end: 1062}
    status: "Required"
  - name: "Testing"
    header_level: 3
    line_range: {start: 1063, end: 1069}
    status: "Required"
  - name: "Documentation"
    header_level: 3
    line_range: {start: 1070, end: 1075}
    status: "Required"
  - name: "TDD Workflow Summary"
    header_level: 3
    line_range: {start: 1077, end: 1081}
    status: "Required"
  - name: "Files Created/Modified"
    header_level: 3
    line_range: {start: 1082, end: 1086}
    status: "Required"
END_SECTION_MANIFEST -->

# =============================================================================
# STORY TEMPLATE CHANGELOG
# =============================================================================
#
# Version: 3.0
# Last Updated: 2026-03-23
# Maintained by: spec-driven-stories skill
#
# Version History:
#
# v3.0 (2026-03-23) - Implementation Guide Enhancement, SECTION_MANIFEST Update (STORY-578, EPIC-089, ADR-047)
#   Changes:
#     - Added <implementation> optional XML element to AC schema in coding-standards.md
#     - Added ## Implementation Guide conditional section (between Technical Specification and Technical Limitations)
#     - Added 6 subsections: Architecture Decisions, Cross-Cutting Concerns, Implementation Sequence, Task Prompt Templates, Anti-Patterns, Patterns and References
#     - Updated SECTION_MANIFEST with Implementation Guide entry (status: Conditional) and 6 subsection entries
#     - Bumped template_version and format_version from 2.9 to 3.0
#   Rationale:
#     - Close the WHAT-WHERE-HOW gap: stories now carry HOW guidance alongside WHAT (AC) and WHERE (Tech Spec)
#     - Enable fresh Claude sessions to implement stories without manual supplemental context
#     - Per-AC implementation element for targeted implementation hints
#     - Story-level Implementation Guide for cross-cutting implementation concerns
#   References:
#     - STORY-578: Template v3.0 Schema and Implementation Guide Section
#     - EPIC-089: Story Template v3.0 Implementation Guide Enhancement
#     - ADR-047: Story Template v3.0 Implementation Guide Enhancement Decision Record
#
# v2.9 (2026-02-09) - Implementation Notes Format Guidance (STORY-403, EPIC-063)
#   Changes:
#     - Added HTML comment block in Definition of Done section area
#     - Comment explains flat structure requirement for DoD items
#     - Comment references extract_section() validator behavior
#     - Comment includes full path to dod-update-workflow.md reference
#     - Bumped template_version and format_version to 2.9
#   Rationale:
#     - Developers don't see critical format requirements at point-of-use
#     - Pre-commit validation fails when DoD items placed under ### subsections
#     - Point-of-use guidance prevents format errors before they occur
#   References:
#     - STORY-403: Document Implementation Notes Format in Story Template
#     - EPIC-063: Phase 09 Framework-Analyst Recommendation Pipeline
#     - dod-update-workflow.md: DoD Update Workflow specification
#
# v2.8 (2026-02-04) - Advisory Story Support (STORY-348, EPIC-054)
#   Changes:
#     - Added advisory field to YAML frontmatter (boolean, optional, default: false)
#     - Added source_gap field for traceability to original gap (pattern: GAP-NNN)
#     - Added source_story field for traceability to story where gap detected (pattern: STORY-NNN)
#     - Advisory field positioned after priority field
#     - Source fields required when advisory: true, omitted for standard stories
#     - Bumped template_version and format_version to 2.8
#   Rationale:
#     - Enable clear identification of advisory (non-blocking) stories
#     - Full traceability from story back to original QA finding
#     - Visual distinction with [ADVISORY] prefix in title
#   References:
#     - STORY-348: Create Advisory Stories with ADVISORY Prefix and Frontmatter
#     - EPIC-054: QA Warning Follow-up System
#
# v2.7 (2026-01-21) - Provenance XML Section (STORY-291, EPIC-049)
#   Changes:
#     - Added provenance XML section after Description for context traceability
#     - Added <origin> element with document, section attributes and quote, line_reference, quantified_impact children
#     - Added <decision> element with rationale attribute and selected, rejected, trade_off children
#     - Added <stakeholder> element with role, goal attributes and quote, source children
#     - Added <hypothesis> element with id, validation, success_criteria attributes
#     - Bumped template_version and format_version to 2.7
#   Rationale:
#     - BMAD "Artifacts Travel With Work" pattern (RESEARCH-003)
#     - Preserves brainstorm context in downstream documents
#     - Enables traceability from story to original business rationale
#   References:
#     - STORY-291: Add Provenance XML Section to Story Template v2.7
#     - EPIC-049: Context Preservation and Provenance Tracking
#     - RESEARCH-003: BMAD-METHOD
#
# v2.6 (2026-01-19) - XML Acceptance Criteria Format (STORY-280, EPIC-046)
#   Changes:
#     - Added XML acceptance criteria format with <acceptance_criteria> blocks
#     - Added complete example with all optional elements (verification, source_files)
#     - Added source_files guidance section for verification hints
#     - Added backward compatibility note: legacy markdown AC NOT supported by verification
#     - Bumped template_version and format_version to 2.6
#   Rationale:
#     - Machine-parseable AC enables automated compliance verification
#     - ac-compliance-verifier subagent requires XML format
#     - Standardized schema per coding-standards.md (lines 362-460)
#   References:
#     - STORY-280: Story Template Update for XML AC Format
#     - EPIC-046: AC Compliance Verification System
#     - coding-standards.md: XML Acceptance Criteria Schema
#
# v2.5 (2025-12-29) - Unified Change Log Section (STORY-152)
#   Changes:
#     - Replaced ## Workflow Status with unified ## Change Log section
#     - Added **Current Status:** field for tracking story state
#     - Added 5-column table: Date | Author | Phase/Action | Change | Files Affected
#     - Initial entry with author `.claude/story-requirements-analyst`
#     - Shared reference guide at .claude/references/changelog-update-guide.md
#   Rationale:
#     - Unified tracking of workflow state AND file modifications
#     - Subagent attribution for audit trail
#     - Single source of truth for story history
#   References:
#     - STORY-152: Unified Story Change Log Tracking
#     - .claude/references/changelog-update-guide.md
#
# v2.4 (2025-12-23) - Story Type Classification (STORY-126)
#   Changes:
#     - Added type field to YAML frontmatter for TDD phase skipping
#     - Valid types: feature (default), documentation, bugfix, refactor
#     - Positioned after title field, before epic field
#     - Default value: feature (full TDD workflow)
#   Phase Skip Matrix:
#     - feature: No phases skipped (full TDD)
#     - documentation: Skip Phase 05 Integration (no runtime code)
#     - bugfix: Skip Phase 04 Refactor (minimal changes)
#     - refactor: Skip Phase 02 Red (tests exist)
#   Backward Compatibility:
#     - Stories without type field default to "feature"
#     - No migration required for existing stories
#   References:
#     - STORY-126: Story Type Detection & Phase Skipping
#     - coding-standards.md: Story Type Classification section
#
# v2.3 (2025-12-21) - Technical Limitations Section
#   Changes:
#     - Added Technical Limitations section after Technical Specification
#     - YAML format with id, component, limitation, decision, discovered_phase, impact
#     - Decision options: pending, defer:STORY-XXX, descope:ADR-XXX, workaround:description
#     - Discovered phase options: Architecture, Development, QA
#   Rationale:
#     - Prevents late-stage discovery of tool/technology blockers
#     - Enables explicit decision-making for capability gaps
#     - Provides audit trail for limitation handling
#   References:
#     - Architectural review of /qa STORY-118 execution
#
# v2.2 (2025-12-14) - STORY-090 Parallel Development Support
#   Changes:
#     - Added depends_on field to YAML frontmatter for dependency declaration
#     - Format: Array of STORY-NNN IDs (e.g., ["STORY-044", "STORY-045"])
#     - Positioned after points field, before status field
#     - Default value: empty array [] for stories with no dependencies
#     - Enables Feature 3 (Dependency Graph Enforcement) for parallel development workflows
#   Backward Compatibility:
#     - Compatible with v2.1 stories (depends_on field optional for existing stories)
#     - Stories without depends_on field treated as having no dependencies (empty array)
#   Rationale:
#     - Prerequisite for EPIC-010 (Parallel Story Development)
#     - Standardized array format enables automated dependency validation
#   References:
#     - STORY-090: Update Story Template to v2.2 with depends_on Field
#     - EPIC-010: Parallel Story Development with CI/CD Integration
#
# v2.1 (2025-01-21) - RCA-012 Remediation
#   Changes:
#     - Removed checkbox syntax from AC headers
#     - Format change: '### 1. [ ] Title' → '### AC#1: Title'
#     - Rationale: AC headers are definitions, not completion trackers
#     - Three-layer tracking system clarified in CLAUDE.md:
#       * TodoWrite (AI phase-level monitoring)
#       * AC Verification Checklist (granular sub-item tracking)
#       * Definition of Done (official completion record)
#   Impact:
#     - Eliminates user confusion about unchecked AC headers
#     - Clarifies AC headers are static definitions
#     - All future stories (58+) benefit from clear format
#   References:
#     - RCA-012: devforgeai/RCA/RCA-012/
#     - Root cause: Vestigial checkboxes from pre-RCA-011 design
#
# v2.0 (2025-10-30) - Structured Tech Spec (RCA-006 Phase 2)
#   Changes:
#     - Added technical_specification YAML code block
#     - Machine-readable component definitions (Service, Worker, API, etc.)
#     - Test requirements embedded in each component
#     - Improved deterministic parsing for test generation
#   Impact:
#     - Test generation accuracy improved (85% → 95%+)
#     - Validation automation enabled
#   References:
#     - devforgeai/specs/STRUCTURED-FORMAT-SPECIFICATION.md
#
# v1.0 (Initial) - Original Template
#   Features:
#     - User story format (As a... I want... So that...)
#     - AC headers with checkbox syntax (vestigial as of v2.1)
#     - Freeform technical specification
#     - Definition of Done section
#
# Migration Paths:
#   v1.0 → v2.0: Gradual (on story update)
#   v2.0 → v2.1: Optional script available
#     Location: .claude/skills/spec-driven-stories/scripts/migrate-ac-headers.sh
#     Documentation: devforgeai/RCA/RCA-012/MIGRATION-SCRIPT.md
#
# Backward Compatibility:
#   All versions (v1.0, v2.0, v2.1) supported by framework
#   Old stories continue to work without migration
#   Migration is optional (for visual consistency only)
#
# =============================================================================

---
id: STORY-XXX
title: [Story Title - What is being built]
type: feature
# Story type controls TDD phase skipping. Options: feature (default), documentation, bugfix, refactor
epic: EPIC-XXX
sprint: Backlog
# Sprint field default: "Backlog" for new stories. Only set to a Sprint-NN when /create-sprint assigns the story to a sprint. NEVER reverse-engineer from sibling stories.
status: Backlog
points: [Story points: 1, 2, 3, 5, 8, 13]
depends_on: []
# Array of STORY-NNN IDs this story depends on. Examples: [], ["STORY-044"], ["STORY-044", "STORY-045"]
priority: [High / Medium / Low]
# Advisory story fields (optional - populated by /review-qa-reports for non-blocking gaps)
advisory: false
# Set to true for advisory (non-blocking) stories created from gaps.json with blocking: false
# Advisory stories have [ADVISORY] prefix in title and filename includes 'advisory' slug
source_gap: null
# Gap ID that created this story (e.g., GAP-001). Required when advisory: true. Pattern: GAP-\d{3}
source_story: null
# Story where gap was originally detected (e.g., STORY-123). Required when advisory: true. Pattern: STORY-\d+
# QA-recommendations story fields (optional - populated by /create-story --from-recommendations; template v3.1)
from_recommendations: false
# Set to true when this story was generated from a *-qa-recommendations.md file via /create-story --from-recommendations.
source_recommendations: null
# List of REC-IDs matching REC-STORY-\d+-[CHML]-\d{3}. Required when from_recommendations: true.
cycle_recorded: null
# QA cycle (integer) that surfaced these recs, from qa-recommendations-status.current_cycle. Required when from_recommendations: true.
# DEVARCH pipeline story fields (optional - populated when /create-story ingests a development-architecture story seed; Phase 01 Sub-step 1.2.0)
feature_ref: ""
# F-NN — the feature this story implements, from the Development Architecture Document. Empty for legacy/non-pipeline stories.
source_devarch: ""
# Relative path to the Development Architecture Document (DEVARCH) this story was seeded from. Empty for legacy/non-pipeline stories.
assigned_to: [Developer Name]
created: YYYY-MM-DD
format_version: "3.1"
---

# Story: [Title]

## Description

**As a** [user role/persona],
**I want** [capability/feature],
**so that** [business value/benefit].

**Example:**
As a returning customer, I want to use my saved payment method during checkout, so that I can complete purchases faster without re-entering card details.

## Provenance

> **Optional Section:** Include when story originates from a brainstorm document or has traceable business rationale. Omit for stories created without brainstorm reference.

Document the origin, decisions, stakeholders, and hypotheses that led to this story. Uses XML format for Claude's fine-tuned XML attention.

```xml
<provenance>
  <!-- Origin: Link to source brainstorm document with quoted evidence -->
  <origin document="BRAINSTORM-NNN" section="problem-statement">
    <quote>"Exact quote from brainstorm document"</quote>
    <line_reference>lines XX-YY</line_reference>
    <quantified_impact>Measurable impact statement</quantified_impact>
  </origin>

  <!-- Decision: Document the approach selected and alternatives rejected -->
  <decision rationale="selected-over-alternatives">
    <selected>Chosen approach description</selected>
    <rejected alternative="alternative-name">
      Why this alternative was not chosen
    </rejected>
    <trade_off>Trade-off accepted with this decision</trade_off>
  </decision>

  <!-- Stakeholder: Link to specific stakeholder goals from brainstorm -->
  <stakeholder role="Role Title" goal="stakeholder-goal-id">
    <quote>"Stakeholder quote from brainstorm"</quote>
    <source>BRAINSTORM-NNN, section name</source>
  </stakeholder>

  <!-- Hypothesis: Link to testable hypotheses from brainstorm -->
  <hypothesis id="H1" validation="validation-method" success_criteria="measurable criteria">
    Hypothesis statement to be validated
  </hypothesis>
</provenance>
```

### Provenance Elements Reference

| Element | Required | Attributes | Children | Purpose |
|---------|----------|------------|----------|---------|
| `<origin>` | Yes (if provenance present) | `document`, `section` | `<quote>`, `<line_reference>`, `<quantified_impact>` | Link to source document |
| `<decision>` | Optional | `rationale` | `<selected>`, `<rejected>`, `<trade_off>` | Document approach selection |
| `<stakeholder>` | Optional (repeatable) | `role`, `goal` | `<quote>`, `<source>` | Link to stakeholder goals |
| `<hypothesis>` | Optional (repeatable) | `id`, `validation`, `success_criteria` | Text content | Link to testable hypotheses |

---

## Acceptance Criteria

Define testable, specific conditions that must be met for story completion. Use XML format with `<acceptance_criteria>` blocks for machine-parseable verification.

> **IMPORTANT:** XML acceptance criteria format is REQUIRED for automated verification by the ac-compliance-verifier subagent. Legacy markdown format (Given/When/Then bullets) is NOT supported by verification tools.

### XML Acceptance Criteria Format

Use the following XML schema for each acceptance criterion:

```xml
<acceptance_criteria id="AC1" implements="COMP-XXX,COMP-YYY">
  <given>Initial context or precondition</given>
  <when>Action or event being tested</when>
  <then>Expected outcome or result</then>
  <verification>
    <source_files>
      <file hint="Main implementation">path/to/source.py</file>
      <file hint="Helper module">path/to/helper.py</file>
    </source_files>
    <test_file>path/to/test.py</test_file>
    <coverage_threshold>95</coverage_threshold>
  </verification>
</acceptance_criteria>
```

### AC#1: [Criterion 1 Title]

```xml
<acceptance_criteria id="AC1">
  <given>[Initial context/state]</given>
  <when>[Action/event occurs]</when>
  <then>[Expected outcome]</then>
</acceptance_criteria>
```

---

### AC#2: [Criterion 2 Title]

```xml
<acceptance_criteria id="AC2" implements="COMP-001">
  <given>[Initial context/state]</given>
  <when>[Action/event occurs]</when>
  <then>[Expected outcome]</then>
  <verification>
    <source_files>
      <file>[path/to/source.ext]</file>
    </source_files>
    <test_file>[path/to/test.ext]</test_file>
  </verification>
</acceptance_criteria>
```

---

### AC#3: [Criterion 3 Title] - Complete Example

This example shows ALL optional elements for comprehensive verification:

```xml
<acceptance_criteria id="AC3" implements="COMP-002,COMP-003">
  <given>Shopping cart has items and user is authenticated</given>
  <when>User clicks checkout button</when>
  <then>Order is created with correct total and confirmation displayed</then>
  <verification>
    <source_files>
      <file hint="Checkout service">src/cart/checkout.py</file>
      <file hint="Order creation">src/orders/service.py</file>
      <file hint="Total calculation">src/cart/calculator.py</file>
    </source_files>
    <test_file>tests/STORY-XXX/test_ac3_checkout.py</test_file>
    <coverage_threshold>95</coverage_threshold>
  </verification>
</acceptance_criteria>
```

---

### AC#4: [Criterion 4 Title]

```xml
<acceptance_criteria id="AC4">
  <given>[Initial context/state]</given>
  <when>[Action/event occurs]</when>
  <then>[Expected outcome]</then>
</acceptance_criteria>
```

---

*Add more criteria as needed (typically 3-7 per story)*

---

### Source Files Guidance

The `<source_files>` element provides hints to the ac-compliance-verifier about where implementation code is located.

**When to Include Source Files:**
- For ACs that modify or create specific files
- When implementation spans multiple files
- When verification needs to locate test coverage targets

**How to Use Hints:**
- `hint` attribute describes what the file contains
- Use relative paths from project root
- List ALL files that implement the AC

**Example Hints:**
- `hint="Main service implementation"` - Primary business logic
- `hint="Repository layer"` - Data access code
- `hint="API controller"` - Endpoint handling
- `hint="Configuration"` - Settings/config changes

**How Verification Uses Source Files:**
1. ac-compliance-verifier reads `<source_files>` from AC
2. Locates corresponding test file from `<test_file>`
3. Validates tests exist for each source file
4. Checks coverage threshold is met for listed files

## Technical Specification

```yaml
technical_specification:
  format_version: "2.0"

  components:
    # Service Component Example
    - type: "Service"
      name: "[ServiceName]"
      file_path: "src/[path]/[ServiceName].cs"
      interface: "[IServiceInterface]"
      lifecycle: "Singleton|Scoped|Transient"
      dependencies:
        - "[IDependency1]"
        - "[IDependency2]"
      requirements:
        - id: "SVC-001"
          description: "[What this service must do]"
          testable: true
          test_requirement: "Test: [Specific test for this requirement]"
          priority: "Critical|High|Medium|Low"

    # Worker Component Example
    - type: "Worker"
      name: "[WorkerName]"
      file_path: "src/[path]/[WorkerName].cs"
      interface: "BackgroundService|IHostedService"
      polling_interval_ms: 30000
      dependencies:
        - "[IDependency]"
      requirements:
        - id: "WKR-001"
          description: "[What this worker must do]"
          testable: true
          test_requirement: "Test: [Specific test for this requirement]"
          priority: "Critical|High|Medium|Low"

    # Configuration Component Example
    - type: "Configuration"
      name: "appsettings.json"
      file_path: "src/[path]/appsettings.json"
      required_keys:
        - key: "[ConfigSection.KeyName]"
          type: "string|int|bool|array|object"
          example: "[Example value]"
          required: true|false
          default: "[Default value if any]"
          validation: "[Validation rules]"
          test_requirement: "Test: [How to verify this config loads]"

    # Logging Component Example
    - type: "Logging"
      name: "Serilog|NLog|log4net"
      file_path: "src/[path]/Program.cs"
      sinks:
        - name: "File|EventLog|Database|Console"
          path: "[Log file path]"
          test_requirement: "Test: [How to verify this sink works]"

    # Repository Component Example
    - type: "Repository"
      name: "[RepositoryName]"
      file_path: "src/Infrastructure/Repositories/[RepositoryName].cs"
      interface: "[IRepositoryInterface]"
      data_access: "Dapper|EF Core|Prisma|Raw SQL"
      entity: "[EntityName]"
      table: "[dbo].[TableName]"
      requirements:
        - id: "REPO-001"
          description: "[What this repository must do]"
          testable: true
          test_requirement: "Test: [Specific test for this requirement]"
          priority: "Critical|High|Medium|Low"

    # API Endpoint Component Example
    - type: "API"
      name: "[EndpointName]"
      endpoint: "/api/[resource]/[action]"
      method: "GET|POST|PUT|PATCH|DELETE"
      authentication:
        required: true|false
        method: "Bearer Token|API Key|OAuth2"
        scopes: ["scope1", "scope2"]
      request:
        content_type: "application/json"
        schema:
          field1:
            type: "string|number|boolean|object|array"
            required: true|false
            validation: "[Validation rules]"
      response:
        success:
          status_code: 200|201|204
          schema:
            id: "UUID"
            field: "string"
        errors:
          - status_code: 400|401|403|404|422|500
            condition: "[When this error occurs]"
            schema:
              error: "string"
              message: "string"
      requirements:
        - id: "API-001"
          description: "[What this API must do]"
          testable: true
          test_requirement: "Test: [Specific test for this requirement]"
          priority: "Critical|High|Medium|Low"

    # DataModel Component Example
    - type: "DataModel"
      name: "[EntityName]"
      table: "[dbo].[TableName]"
      purpose: "[What this model represents]"
      fields:
        - name: "[FieldName]"
          type: "UUID|String|Int|DateTime|Enum|etc"
          constraints: "Primary Key|Required|Unique|etc"
          description: "[Purpose of this field]"
          test_requirement: "Test: [How to validate this field]"
      indexes:
        - name: "IX_[Table]_[Field]"
          fields: ["[Field1]", "[Field2]"]
          unique: true|false
          purpose: "[Why this index exists]"
      relationships:
        - type: "One-to-Many|Many-to-One|Many-to-Many"
          related_entity: "[RelatedEntity]"
          foreign_key: "[FK_Field]"
          cascade: "Cascade|Restrict|SetNull"
          description: "[Relationship purpose]"

  business_rules:
    - id: "BR-001"
      rule: "[Business rule description]"
      trigger: "[When this rule is evaluated]"
      validation: "[How to validate compliance]"
      error_handling: "[What happens if violated]"
      test_requirement: "Test: [How to test this rule]"
      priority: "Critical|High|Medium|Low"

  non_functional_requirements:
    - id: "NFR-001"
      category: "Performance|Security|Scalability|Reliability"
      requirement: "[NFR description]"
      metric: "[Measurable target with numbers]"
      test_requirement: "Test: [How to verify this NFR]"
      priority: "Critical|High|Medium|Low"
```

**Instructions for AI Story Creation:**
1. Use appropriate component types based on what's being built
2. Every requirement/key/sink/field should have a `test_requirement`
3. IDs should be unique and follow pattern: SVC-001, WKR-001, API-001, etc.
4. Priorities: Critical (must have), High (should have), Medium (nice to have), Low (optional)
5. All test requirements start with "Test: " prefix
6. Metrics must be measurable (include numbers, thresholds, or ranges)

**See `devforgeai/specs/STRUCTURED-FORMAT-SPECIFICATION.md` for complete schema reference and examples.**

---

## Implementation Guide

<!-- CONDITIONAL SECTION: Required for feature stories >= 5 points. Optional for all others.
     When not applicable, this entire section is omitted by Phase 05 assembly. Do NOT manually add this section for non-qualifying stories.
     This section bridges WHAT (Acceptance Criteria) and WHERE (Technical Specification) with HOW (implementation approach).
     Added in template v3.0 per ADR-047 and EPIC-089. -->

### Architecture Decisions

<!-- Document key technical decisions that span multiple ACs. Format as table. -->

| Decision | Chosen Approach | Alternatives Considered | Rationale |
|----------|----------------|------------------------|-----------|
| [Decision 1] | [Approach] | [Alt 1, Alt 2] | [Why this approach] |

### Cross-Cutting Concerns

<!-- Document implementation concerns that span multiple ACs but don't belong to any single one. -->

**Error Handling Strategy:**
[Describe error handling approach spanning multiple ACs — e.g., Result pattern, exception hierarchy, retry policies]

**Data Flow:**
[Describe end-to-end data flow across components — e.g., "Request enters via API → validated → processed by service → persisted → event published"]

### Implementation Sequence

<!-- Recommended order of AC implementation based on dependencies between ACs. -->

1. **AC#N** (description) — Foundation; other ACs depend on this
2. **AC#M** (description) — Depends on AC#N
3. **AC#P** (description) — Depends on AC#M

### Task Prompt Templates

<!-- Suggested prompt fragments for subagent invocations. Story author can shape how agents behave. -->

**For test-automator (Phase 02 Red):**
```
[Suggested prompt fragment for test generation — e.g., "Focus on boundary conditions for the validation logic"]
```

**For backend-architect (Phase 03 Green):**
```
[Suggested prompt fragment for implementation — e.g., "Use repository pattern per coding-standards.md, error handling via Result type"]
```

### Anti-Patterns

<!-- What NOT to do, with rationale from planning/exploration. Prevents repeating discovered mistakes. -->

- Do NOT [specific thing] because [reason discovered during planning]
- Do NOT [another thing] because [rationale]

### Patterns and References

<!-- Point to existing code, design patterns, or similar stories as reference. -->

- **Design Pattern:** [Pattern name from coding-standards.md, with section reference]
- **Similar Implementation:** [STORY-NNN that implements a similar feature — use as reference]
- **External Reference:** [Documentation link, if applicable]

---

## Technical Limitations

Document known tool or technology limitations discovered during architecture, development, or QA phases. This prevents late-stage discovery of blockers and enables explicit decision-making.

```yaml
technical_limitations:
  # Example entries - remove or replace with actual limitations
  - id: TL-001
    component: "[Component or tool name]"
    limitation: "[Description of what cannot be done]"
    decision: "pending"  # Options: pending | defer:STORY-XXX | descope:ADR-XXX | workaround:description
    discovered_phase: "Architecture"  # Options: Architecture | Development | QA
    impact: "[How this affects the story]"
```

**Decision Options:**
- `pending` - Not yet decided, requires user input
- `defer:STORY-XXX` - Deferred to follow-up story for resolution
- `descope:ADR-XXX` - Removed from scope via Architecture Decision Record
- `workaround:description` - Alternative approach implemented

**When to Add Entries:**
- Tool cannot perform required analysis
- Framework limitation prevents full implementation
- External dependency has capability gaps
- Performance constraints prevent ideal solution

---

## Non-Functional Requirements (NFRs)

### Performance

**Response Time:**
- **API Endpoint 1:** < [X]ms (p95), < [X]ms (p99)
- **API Endpoint 2:** < [X]ms (p95), < [X]ms (p99)

**Throughput:**
- Support [X] requests per second
- Support [X] concurrent users

**Performance Test:**
- Load test with [X] concurrent users
- Verify response time under load
- Verify no memory leaks over [X] hour run

---

### Security

**Authentication:**
- [Required / Optional / None]
- [Auth method: OAuth 2.0, JWT, API Key, etc.]

**Authorization:**
- [Role-based / Permission-based / None]
- Required roles: [Roles that can access this feature]

**Data Protection:**
- Sensitive fields: [List fields requiring encryption/masking]
- Encryption: [At rest / In transit / Both]
- PII handling: [GDPR/CCPA compliance requirements]

**Security Testing:**
- [ ] No SQL injection vulnerabilities
- [ ] No XSS vulnerabilities
- [ ] No hardcoded secrets
- [ ] Proper input validation
- [ ] Proper output encoding
- [ ] Authentication enforced
- [ ] Authorization enforced

**Rate Limiting:**
- [X] requests per [time period] per [IP / user / API key]

---

### Scalability

**Horizontal Scaling:**
- Stateless design: [Yes / No]
- Load balancing: [Required / Not Required]

**Database:**
- Expected data volume: [X] records per [time period]
- Growth rate: [X]% per [time period]
- Indexing strategy: [Described above in Data Models]

**Caching:**
- Cache strategy: [None / Redis / In-Memory]
- Cache TTL: [X] seconds/minutes
- Cache invalidation: [Strategy]

---

### Reliability

**Error Handling:**
- Follow Result Pattern (per coding-standards.md)
- Log all errors with context
- Return user-friendly error messages (no stack traces)

**Retry Logic:**
- Retry transient failures: [Yes / No]
- Max retries: [X]
- Backoff strategy: [Exponential / Linear / Fixed]

**Monitoring:**
- Metrics to track: [List key metrics]
- Alerts: [When to alert, who receives alerts]

---

### Observability

**Logging:**
- Log level: [INFO / DEBUG / WARN / ERROR]
- Log structured data (JSON format)
- Include correlation ID for request tracing
- Do NOT log sensitive data (passwords, tokens, PII)

**Metrics:**
- Request count
- Response time (p50, p95, p99)
- Error rate
- [Custom metric 1]
- [Custom metric 2]

**Tracing:**
- Distributed tracing: [Yes / No]
- Trace all external calls

---

## Dependencies

### Prerequisite Stories

Stories that must complete BEFORE this story can start:

- [ ] **STORY-XXX:** [Story title]
  - **Why:** [Explanation of dependency]
  - **Status:** [Not Started / In Progress / Complete]

- [ ] **STORY-YYY:** [Story title]
  - **Why:** [Explanation of dependency]
  - **Status:** [Not Started / In Progress / Complete]

### External Dependencies

Dependencies outside the team's control:

- [ ] **External Dependency 1:** [Description]
  - **Owner:** [Team/Vendor]
  - **ETA:** [Date]
  - **Status:** [On Track / At Risk / Blocked]
  - **Impact if delayed:** [Description]

- [ ] **External Dependency 2:** [Description]
  - **Owner:** [Team/Vendor]
  - **ETA:** [Date]
  - **Status:** [On Track / At Risk / Blocked]

### Technology Dependencies

New packages or versions required:

- [ ] **Package 1:** [Name] v[Version]
  - **Purpose:** [Why needed]
  - **Approved:** [Yes / Pending]
  - **Added to dependencies.md:** [Yes / No]

- [ ] **Package 2:** [Name] v[Version]
  - **Purpose:** [Why needed]
  - **Approved:** [Yes / Pending]

---

## Test Strategy

### Unit Tests

**Coverage Target:** 95%+ for business logic

**Test Scenarios:**
1. **Happy Path:** [Description of normal flow]
2. **Edge Cases:**
   - [Edge case 1]
   - [Edge case 2]
   - [Edge case 3]
3. **Error Cases:**
   - [Error case 1: null input]
   - [Error case 2: invalid input]
   - [Error case 3: business rule violation]

*Test examples use AAA pattern (Arrange-Act-Assert). Follow language-specific conventions.*

---

### Integration Tests

**Coverage Target:** 85%+ for application layer

**Test Scenarios:**
1. **End-to-End API Flow:** [Description]
2. **Database Integration:** [Description]

---

### E2E Tests (If Applicable)

**Coverage Target:** 10% of total tests (critical paths only)

---

## Acceptance Criteria Verification Checklist

**Purpose:** Real-time progress tracking during TDD implementation. Check off items as each sub-task completes.

**Usage:** The spec-driven-dev skill updates this checklist at the end of each TDD phase (Phases 1-5), providing granular visibility into AC completion progress.

**Tracking Mechanisms:**
- **TodoWrite:** Phase-level tracking (AI monitors workflow position)
- **AC Checklist:** AC sub-item tracking (user sees granular progress) ← YOU ARE HERE
- **Definition of Done:** Official completion record (quality gate validation)

### AC#1: [First Acceptance Criterion Title]

- [ ] [Sub-item 1] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]
- [ ] [Sub-item 2] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]
- [ ] [Sub-item 3] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]

### AC#2: [Second Acceptance Criterion Title]

- [ ] [Sub-item 1] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]
- [ ] [Sub-item 2] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]

### AC#3: [Third Acceptance Criterion Title]

- [ ] [Sub-item 1] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]
- [ ] [Sub-item 2] - **Phase:** [1-5] - **Evidence:** [test file or implementation location]

---

**Checklist Progress:** {checked}/{total} items complete ({percentage}%)

---

<!-- IMPLEMENTATION NOTES FORMAT REQUIREMENT (Critical for pre-commit validation):
When filling in the Implementation Notes section during /dev workflow:
1. DoD items MUST be placed DIRECTLY under "## Implementation Notes" header
2. NO ### subsection headers (like "### Definition of Done Status") before DoD items
3. The extract_section() validator stops at the first ### header it encounters
4. If DoD items are under a ### subsection, the validator cannot find them → commit blocked
5. The ### Additional Notes subsection is OK because it comes AFTER DoD items
See: .claude/skills/spec-driven-dev/references/dod-update-workflow.md for complete details
-->

## Definition of Done

### Implementation
- [ ] [Implementation checklist item 1]
- [ ] [Implementation checklist item 2]
- [ ] [Implementation checklist item 3]
- [ ] [Implementation checklist item 4]

### Quality
- [ ] All [X] acceptance criteria have passing tests
- [ ] Edge cases covered ([list specific edge cases])
- [ ] Data validation enforced ([specify validation rules])
- [ ] NFRs met ([specify which NFRs])
- [ ] Code coverage >[X]% for [module/component]

### Testing
- [ ] Unit tests for [module 1]
- [ ] Unit tests for [module 2]
- [ ] Integration tests for [feature 1]
- [ ] Integration tests for [feature 2]
- [ ] E2E test: [critical user journey]

### Documentation
- [ ] [Document type 1]: [What is documented]
- [ ] [Document type 2]: [What is documented]
- [ ] [Document type 3]: [What is documented]

---

### TDD Workflow Summary

| Phase | Status | Details |
|-------|--------|---------|

### Files Created/Modified

| File | Action | Lines |
|------|--------|-------|

---

## Change Log

**Current Status:** Backlog

| Date | Author | Phase/Action | Change | Files Affected |
|------|--------|--------------|--------|----------------|
| YYYY-MM-DD HH:MM | .claude/story-requirements-analyst | Created | Story created | STORY-XXX.story.md |

## Notes

[Additional context, design decisions, clarifications, or open questions]

**Backward Compatibility - Acceptance Criteria Format:**
> **Legacy markdown AC format (Given/When/Then bullets) is NOT supported by automated verification.**
> The ac-compliance-verifier subagent requires XML `<acceptance_criteria>` blocks to parse and verify ACs.
> Stories created before v2.6 may have markdown AC format - these will need manual verification or migration to XML format.

**Design Decisions:**
- [Decision 1 and rationale]
- [Decision 2 and rationale]

**Open Questions:**
- [ ] [Question 1] - **Owner:** [Name] - **Due:** [Date]
- [ ] [Question 2] - **Owner:** [Name] - **Due:** [Date]

**Related ADRs:**
- [ADR-XXX: [Title]](../ADRs/ADR-XXX.md)

**References:**
- [External documentation link]
- [Design mockup link]
- [Related ticket/issue]

---

Story Template Version: 3.0
Last Updated: 2026-03-23
