# Story {{epic_num}}.{{story_num}}: {{story_title}}

**Status:** ready-for-dev
**Epic:** {{epic_num}}
**Priority:** {{priority}}
**Estimated Effort:** {{effort}}

---

## Story

As a **{{role}}**,
I want to **{{action}}**,
So that **{{benefit}}**.

---

## Business Context

### Why This Matters

{{business_value}}

### Production Reality

{{scale_requirements}}
{{compliance_requirements}}
{{urgency}}

---

## Acceptance Criteria

{{acceptance_criteria}}

---

## Tasks / Subtasks

{{tasks_subtasks}}

---

## Dev Notes

### Gap Analysis: Current State vs Requirements

**✅ IMPLEMENTED (Verified by Codebase Scan):**

{{implemented_components}}

**❌ MISSING (Required for AC Completion):**

{{missing_components}}

**⚠️ PARTIAL (Needs Enhancement):**

{{partial_components}}

### Architecture Compliance

{{architecture_patterns}}

### Library/Framework Requirements

**Current Dependencies:**
```json
{{current_dependencies}}
```

**Required Additions:**
```json
{{required_dependencies}}
```

### File Structure Requirements

**Completed Files:**
```
{{existing_files}}
```

**Required New Files:**
```
{{required_files}}
```

### Testing Requirements

**Current Test Coverage:** {{test_count}} tests passing

**Required Additional Tests:**
{{required_tests}}

**Target:** {{coverage_target}}

### Dev Agent Guardrails

{{guardrails}}

### Previous Story Intelligence

{{previous_story_learnings}}

### Project Structure Notes

{{structure_alignment}}

### References

{{references}}

---

## Definition of Done

### Code Quality (BLOCKING)
- [ ] Type check passes: `pnpm type-check` (zero errors)
- [ ] Zero `any` types in new code
- [ ] Lint passes: `pnpm lint` (zero errors in new code)
- [ ] Build succeeds: `pnpm build`

### Testing (BLOCKING)
- [ ] Unit tests: {{coverage_target}} coverage
- [ ] Integration tests: Key workflows validated
- [ ] All tests pass: New + existing (zero regressions)

### Security (BLOCKING)
- [ ] Dependency scan: `pnpm audit` (zero high/critical)
- [ ] No hardcoded secrets
- [ ] Input validation on all endpoints
- [ ] Auth checks on protected endpoints
- [ ] Audit logging on mutations

### Architecture Compliance (BLOCKING)
- [ ] Multi-tenant isolation: dealerId in all queries
- [ ] Cache namespacing: Cache keys include siteId
- [ ] Performance: External APIs cached, no N+1 queries
- [ ] Error handling: No silent failures
- [ ] Follows patterns from playbooks

### Deployment Validation (BLOCKING)
- [ ] Service starts: `pnpm dev` runs successfully
- [ ] Health check: `/health` returns 200
- [ ] Smoke test: Primary functionality verified

### Documentation (BLOCKING)
- [ ] API docs: Swagger decorators on endpoints
- [ ] Inline comments: Complex logic explained
- [ ] Story file: Dev Agent Record complete

---

## Dev Agent Record

### Agent Model Used

(To be filled by dev agent)

### Implementation Summary

(To be filled by dev agent)

### File List

(To be filled by dev agent)

### Test Results

(To be filled by dev agent)

### Completion Notes

(To be filled by dev agent)

---

**Generated by:** /create-story-with-gap-analysis
**Date:** {{date}}
