---
roadcrew_template_name: "spec.template.md"
roadcrew_template_type: "template"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-01-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "Apache-2.0"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "Apache-2.0"
type: spec
feature: {{FEATURE_NAME}}
feature_id: {{FEATURE_ID}}
status: {{STATUS}}              # Draft | Review | Approved | Implemented
version: {{VERSION}}
related_prd: ../prds/{{FEATURE_ID}}-prd.md
epic: {{EPIC_LINK}}
created: {{CREATED_DATE}}
updated: {{UPDATED_DATE}}
---
# ⚙️ {{FEATURE_NAME}} – Technical Specification {#spec-{{FEATURE_ID}}}

> This document defines **how** to implement the feature. All "what/why" lives in PRD.

## 1. Mapping: PRD → Spec

| PRD Requirement  | Satisfied In Spec Section |
| ---------------- | ------------------------ |
| R1: {{PRD_REQ_1}}| See: 2.1.1               |
| R2: {{PRD_REQ_2}}| See: 3.2                 |
| ...              | ...                      |

## 2. Technical Requirements

### 2.1 Functional Requirements (max 6 bullets—must map PRD 1:1)
- {{REQUIREMENT_1}}
- {{REQUIREMENT_2}}
- ...

### 2.2 Non-Functional Requirements (≤20 words each)
- **Performance:** {{PERFORMANCE_NFR}}
- **Security:** {{SECURITY_NFR}}
- **Reliability:** {{RELIABILITY_NFR}}
- **Scalability:** {{SCALABILITY_NFR}}

### 2.3 Out of Scope (3 bullets max, ≤12 words each)
- {{OUT_OF_SCOPE_1}}
- {{OUT_OF_SCOPE_2}}

## 3. Design Overview (≤100 words)
> Concise paragraph describing the core technical solution and major system changes—no rationale.

{{DESIGN_OVERVIEW}}

## 4. Architecture & Implementation

### 4.1 New/Modified Services (bullets, each ≤20 words)
- **Service:** {{SERVICE_NAME}} – {{SUMMARY_OF_CHANGE}}

### 4.2 Data Model Changes (table: field, type, description, notes; optional YAML block if schema)
| Field | Type | Description | Notes |
|-------|------|-------------|-------|
|       |      |             |       |

### 4.3 API Changes (table: method, endpoint, purpose, affected systems)
| Method | Endpoint | Purpose | Notes          |
|--------|----------|---------|----------------|

### 4.4 Env/Config (table: var, default, description, required)
| Variable        | Default | Description           | Required |
| --------------- | ------- | --------------------- | -------- |

## 5. Execution Plan & Issues

### 5.1 Implementation Plan (≤60 words each phase)
- **Step 1:** {{DESC}}
- **Step 2:** {{DESC}}

### 5.2 Issues (reference anchors)
- [Issue {{EPIC}}.1](#issue-{{EPIC}}-1): {{SUMMARY}}  
- ...

### 5.3 Risks & Mitigations (simple table)
| Risk           | Mitigation         |
|----------------|-------------------|
| Example Risk   | Example Solution   |

## 6. Testing & Validation

### 6.1 Acceptance Criteria (1 line per acceptance, pass/fail)
- {{ACCEPTANCE_CRITERION_1}}
- {{ACCEPTANCE_CRITERION_2}}

### 6.2 Test Plan (≤100 words OR checklist bullets)
- [ ] {{TEST_STEP}}
- [ ] {{TEST_STEP}}

## 7. Dependencies & Links

- **Depends On:** {{DEPENDENCIES}}
- **Blocks:** {{BLOCKS}}
- **Related:** {{RELATED_LINKS}}

## 8. Issue Breakdown

### Epic 1: {{EPIC_1_TITLE}}

{{EPIC_1_DESCRIPTION}} (≤100 words)

**Goals:**
- {{GOAL_1}}
- {{GOAL_2}}
- {{GOAL_3}}

**Success Criteria:**
- [ ] {{SUCCESS_CRITERION_1}}
- [ ] {{SUCCESS_CRITERION_2}}

#### Issue 1.1: {{ISSUE_1_1_TITLE}} {#issue-1-1}

- **Overview:** {{OVERVIEW}} (≤50 words, AI-parseable for enhancement.template.md)
- **Accepts:** [≤5 bullets, pass/fail, ≤12 words each]
- **Tech Approach:** [≤6 bullets, maps to enhancement.template.md]
- **Files/Components:** {{FILES}}
- **Dependencies:** {{DEPENDENCIES}} or "None"
- **Classification:** {{CLASSIFICATION}} (1-10 scale for TOC routing)
- **Size/Complexity:** {{SIZE}}/{{COMPLEXITY}} (S/M/L)

---

#### Issue 1.2: {{ISSUE_1_2_TITLE}} {#issue-1-2}

- **Overview:** {{OVERVIEW}} (≤50 words)
- **Accepts:** [≤5 bullets]
- **Tech Approach:** [≤6 bullets]
- **Files/Components:** {{FILES}}
- **Dependencies:** {{DEPENDENCIES}} or "None"
- **Classification:** {{CLASSIFICATION}} (1-10)
- **Size/Complexity:** {{SIZE}}/{{COMPLEXITY}}

---

#### Issue 1.3: {{ISSUE_1_3_TITLE}} {#issue-1-3}

[Same structure as above]

---

### Epic 2: {{EPIC_2_TITLE}}

{{EPIC_2_DESCRIPTION}} (≤100 words, if multiple epics needed)

**Goals:**
- {{GOAL_1}}

**Success Criteria:**
- [ ] {{SUCCESS_CRITERION_1}}

#### Issue 2.1: {{ISSUE_2_1_TITLE}} {#issue-2-1}

[Same structure as Epic 1 issues]

---

#### Issue 2.2: {{ISSUE_2_2_TITLE}} {#issue-2-2}

[Same structure as Epic 1 issues]

---

## Editor Instructions:
- Write as atomic, non-narrative items wherever possible.
- Never exceed field length limits.
- All mapping tables must match PRD keys exactly.
- Issue breakdowns must map 1:1 to enhancement.template.md structure.
- Anchors enable deep linking: `#issue-{{EPIC}}-{{N}}`
- Classification (1-10) drives assignment in scope-release.
- Any deviation, ambiguity, or overrun invalidates this doc for automation.

<!--
DOWNSTREAM TEMPLATE MAPPING:

templates/enhancement.template.md requirements:
- Overview: ≤50 words → Issue "Overview" field
- Acceptance Criteria: ≤5 bullets → Issue "Accepts" field
- Technical Implementation: ≤6 bullets → Issue "Tech Approach" field
- Classification: 1-10 scale → Issue "Classification" field
- Size/Complexity: S/M/L → Issue "Size/Complexity" field

templates/epic.template.md requirements:
- Overview: ≤30 words → Epic-level summary (derive from all issues)
- Key Goals: ≤5 bullets → Epic-level objectives

templates/release.template.md requirements:
- Target State: ≤30 words → Release-level summary (derive from all epics)

.cursor/commands/implement-epic.md requirements:
- Dependencies: Explicit issue dependencies for ordering
- Test Plan: Validation steps for each issue
- Metrics: Duration, tokens, files modified
-->