---
feature_id:           # e.g., Feature-001
feature_file:         # relative path to Feature .md
plan_by:              # SE name
plan_date:
artifact-status: draft   # draft | approved — approval state of this generated file (gate reads this)
sad_impact: false     # true if Feature changes/extends SAD
adr_needed: false     # true if Feature needs new ADR
split_mode: single    # single | stack-split | sub-feature-split
---
# Feature-{NNN}-Technical: {Title}

> Technical plan for `{feature_file}`. Generated by `/tas-plan`.
> Source of truth for SE during `/tas-dev`.
> **Coding agent reads (the build spine):** Context Refs · Modules · DO NOT CHANGE · UI Binding · the per-stack sections (Logic Flow / File Changes / API Spec / ERD Delta / Unit Test Cases / Tasks). The **SAD Impact Matrix** and **Architecture Decisions** are plan-time governance (filled by `/tas-plan`, read by gates) — not build instructions.

---

## Context Refs
> Pre-resolved pointers to the ONLY upstream sections relevant to this Feature.
> `/tas-plan` fills this so `/tas-dev` and reviewers never re-read full PRD/SAD/Design-Spec.
> Format: `{doc} > {exact heading path}` — read by grepping the heading, not the whole file.
> Omit a row if that doc is not relevant. Keep tight — list only sections that actually inform this Feature.

| Doc | Section (heading path) | Why relevant |
|-----|------------------------|--------------|
| PRD | {e.g. Functional Requirements > Checkout flow} | {AC source / business rule} |
| SAD | {e.g. C2 Containers > Payment Service} | {container/component touched} |
| UI/UX Design | {e.g. Screen Inventory > SCR-004 Checkout; Screen Content Map > SCR-004} | {screens this Feature renders — omit if no UI} |
| Design-Spec | {e.g. Design Tokens > btn-primary; Components > input} | {UI tokens/components to enforce — omit if no UI} |
| ADR | {e.g. ADR-007 Payment provider} | {constraint to honor} |

## Modules
> The SAD design items this Feature realizes — the **claim** that feeds coverage. `/tas-plan` fills these from the SAD; the master-plan break gate + done-time `/tas-status` assert every SAD design item (component / entity / contract / NFR / security control) is claimed by some Feature, so nothing designed is missed.

- **Builds:** {component IDs this Feature constructs — e.g. MOD-01.C1 CheckoutPage, MOD-01.C2 OrderApiClient} *(or "None — extends existing")*
- **Connects:** {component / MOD-IDs / containers it calls + protocol — e.g. MOD-02 Order (REST)}
- **Entities (owns / uses):** {E-NNN this Feature creates the schema for = **owns** (drives entity coverage — one owner per entity); E-NNN it only reads/writes = **uses** — e.g. owns: E-003 Order; uses: E-001 Customer. A pre-existing/`baseline` entity (brownfield) is always **uses** — its owner is the baseline, not this Feature} *(or "None")*
- **Contracts (produces):** {IC-NN this Feature builds the **producer** for — drives IC coverage; contracts it merely consumes belong in DO NOT CHANGE, not here — e.g. IC-01} *(or "None")*
- **NFRs:** {NFR-NNN this Feature enforces as a constraint — e.g. NFR-001 (checkout P95 ≤ 2s)} *(or "None")*
- **Security:** {SEC-NN controls this Feature implements — e.g. SEC-01 (JWT on protected routes)} *(or "None")*

## DO NOT CHANGE
> Stable contracts this Feature **consumes** — copied verbatim from SAD §9.2 Integration Contract Registry. The coding agent MUST NOT alter these signatures; changing one requires a new ADR + `/tas-sad`, never an edit here. (Contracts this Feature *produces* live under `## Modules > Contracts (produces)`, not here.)

| IC-ID | Contract (endpoint / event) | Owner (producer MOD) | Why locked for this Feature |
|-------|-----------------------------|----------------------|-----------------------------|
| IC-01 | POST /v1/payments | MOD-03 Payment | consumed here; signature frozen — other Features depend on it |

## Context Diagram
> All containers involved across all stacks. Who calls what, which DBs/external systems are touched.

:::mermaid
flowchart LR
  user[User / Caller]
  web[Web App]
  service[API Service]
  integration[Integration Adapter]
  db[({DB})]
  ext[{External API / Queue}]

  user --> web
  web --> service
  service --> integration
  integration --> ext
  service --> db
:::

- **Stacks involved:** {list only stacks active in this feature — omit others}
- **Callers / Actors:** {users, internal services, schedulers}
- **Databases:** {names + tables touched}
- **External systems:** {third-party APIs, queues, message brokers}

## Data Flow
> End-to-end data journey across all stacks.

:::mermaid
graph LR
  input["{Input: {source}}"]
  validate["{Validate}"]
  transform["{Transform}"]
  persist["{Persist}"]

  input --> validate
  validate --> transform
  transform --> persist
:::

| Step | Stack | Field(s) | Transformation | Destination |
|------|-------|----------|----------------|-------------|
| {step} | {stack} | {fields} | {mapping, validation} | {DB column / response / event} |

## API Spec
> Contracts between stacks (REST, event, queue). Only if feature exposes new/changed interfaces.

| Endpoint / Event | Stack | Method | Request | Response | Status |
|-----------------|-------|--------|---------|----------|--------|
| {path/topic} | {service/web} | {GET/POST/EVENT} | {schema} | {schema} | {codes} |

**Error Codes:**
- {code}: {description}

## ERD Delta
> The schema delta this Feature applies to SAD §8 Data Architecture — reference entities by their `E-NNN` codes. Cover the entities this Feature **owns** (see `## Modules > Entities (owns)`); the canonical model stays in SAD §8. Schema-level only (tables/columns/indexes) — no per-row logic.

:::mermaid
erDiagram
  ORDER ||--o{ ORDER_ITEM : "1..N"
  ORDER {
    uuid id PK
    string status
  }
  ORDER_ITEM {
    uuid id PK
    uuid order_id FK
    int qty
  }
:::

- **New tables (E-NNN):** {e.g. E-003 Order → `orders` — or "None"}
- **New columns:** {E-NNN.{column} — or "None"}
- **New indexes:** {table(column) — or "None"}
- **Migration script:** {path — or "None"}

## UI Binding
> *(write `N/A` if backend-only or the project has no UI/UX Design stage)* How the coding agent renders this Feature's screens. This section carries the **selection only** — which screen, reuse mode, and which component/token/breakpoint **IDs** apply. It does NOT restate token/component definitions: those live once in `docs/design-spec.md` (SSoT) and are implemented once into the codebase design system by `/tas-dev`; code references them by ID.
> Derived from `Feature Spec.Design Reference` + `UI/UX Design.Generated Screens`.

| SCR-ID | Reuse | Source (if pixel-perfect) | Components / tokens / breakpoint (by ID) |
|--------|-------|---------------------------|------------------------------------------|
| SCR-004 Checkout | pixel-perfect | `docs/ui/checkout.html` → copy, wire data/state only, do NOT redraw | only for parts added beyond the prototype |
| SCR-00N {name} | build | — | `{component.input}`, `{component.button-primary}`, `{colors.error}`, breakpoint `mobile-single-column` |

- **Reuse rule:** `pixel-perfect` applies only when the Generated Screen is code (Claude Design HTML) and Design Reference marks it reuse — copy the file, wire data/state/behaviour, never redraw. Otherwise `build` from the Design Spec components/tokens.

## SAD Impact Matrix
> Fill per `.tas/rules/common/sad-impact.md`. Set frontmatter `sad_impact: true` if any row `Detected: Yes`. ADR Candidate marks decisions human will review for `/tas-adr`.

| # | Category | Detected | SAD Section | Change Summary | ADR Candidate |
|---|----------|----------|-------------|----------------|---------------|
| 1 | Tech Stack | No | — | — | No |
| 2 | System Boundary | No | — | — | No |
| 3 | Container / Topology | No | — | — | No |
| 4 | Data Architecture | No | — | — | No |
| 5 | API Contract | No | — | — | No |
| 6 | Security | No | — | — | No |
| 7 | NFR / Ops | No | — | — | No |
| 8 | Deployment | No | — | — | No |

## Architecture Decisions
> Significant design choices. Document decision + rationale. Flag candidates for ADR review (human decides).

| Decision | Rationale | ADR Candidate |
|----------|-----------|---------------|
| {what} | {why — trade-offs, constraints} | {Yes / No} |

## Execution Plan
> `tas-dev` reads this to orchestrate agents. `split_mode: single` → all stacks in this file. `stack-split` / `sub-feature-split` → each row is a child file.
> `Parallel Safe: Yes` = no dependency on other rows; can run as concurrent agent.

| # | Part / Stack | File | Depends On | Parallel Safe | Est. Time |
|---|---|---|---|---|---|
| 1 | {stack or part-title} | {`this file` or relative child path} | — | Yes / No | {e.g. 2h} |

---

## Stack: Web
> *(omit this section entirely if Web stack not involved)*

### Logic Flow
1. {entry point — component/page/route}
2. {validation / UI state}
3. {API call / user interaction}
4. {response handling / state update}

### File Changes

#### Modify
| File | Change | Reason |
|------|--------|--------|
| {path} | {what} | {why} |

#### Create
| File | Purpose |
|------|---------|
| {path} | {what it does} |

#### Delete
| File | Reason |
|------|--------|
| {path} | {why removed} |

### Config
| Item | Type | Value / Source | Environment |
|------|------|----------------|-------------|
| {VAR_NAME} | env var | {description} | dev / staging / prod |

### Locator Map
> `data-testid` per `.tas/rules/common/locator-naming.md`. SSoT for `/tas-dev` (inject into source) + `/tas-functest*` (consume).
> Best-effort at plan time — `/tas-dev` back-fills any element missing here. Origin: `plan` = seeded by `/tas-plan` | `dev` = back-filled by `/tas-dev`.

| Element (business) | testid | Component / File | Actions | AC Ref | Origin |
|---|---|---|---|---|---|
| {Email field} | ipt_auth_email | {LoginForm.tsx} | type | AC-1 | plan |
| {Submit button} | btn_auth_submit | {LoginForm.tsx} | click | AC-1 | plan |

### Unit Test Cases
> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
> Unit tests do NOT use locators — query by role/label/text (Testing Library). Locator Map is for functional/E2E only.

| ID | AC Ref | Type | Description | Input | Expected Output |
|----|--------|------|-------------|-------|-----------------|
| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |

### Tasks
> Each task names the AC(s) it serves, so every AC traces to ≥1 task (no AC left unbuilt).
- [ ] W1: {file + change} — AC-1
- [ ] W2: {file + change} — AC-2
- [ ] W3: Unit tests for AC-1, AC-2

---

## Stack: Service
> *(omit this section entirely if Service stack not involved)*

### Logic Flow
1. {entry point — controller/handler}
2. {validation / authn-authz}
3. {business logic — service/use-case}
4. {persistence / external call}
5. {response / event emit}

Optional sequence diagram:
:::mermaid
sequenceDiagram
  Caller->>Controller: request
  Controller->>Service: invoke
  Service->>Repository: read/write
  Repository->>DB: query
  DB-->>Service: rows
  Service-->>Controller: result
  Controller-->>Caller: response
:::

### File Changes

#### Modify
| File | Change | Reason |
|------|--------|--------|
| {path} | {what} | {why} |

#### Create
| File | Purpose |
|------|---------|
| {path} | {what it does} |

#### Delete
| File | Reason |
|------|--------|
| {path} | {why removed} |

### Config
| Item | Type | Value / Source | Environment |
|------|------|----------------|-------------|
| {VAR_NAME} | env var | {description} | dev / staging / prod |

### Unit Test Cases
> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`

| ID | AC Ref | Type | Description | Input | Expected Output |
|----|--------|------|-------------|-------|-----------------|
| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |

### Tasks
> Each task names the AC(s) it serves, so every AC traces to ≥1 task (no AC left unbuilt).
- [ ] S1: {file + change} — AC-1
- [ ] S2: {file + change} — AC-2
- [ ] S3: Unit tests for AC-1, AC-2

---

## Stack: Integration
> *(omit this section entirely if Integration stack not involved)*

### Logic Flow
1. {entry point — adapter/client}
2. {authentication with external system}
3. {request transform + call}
4. {response transform + error handling}
5. {retry / circuit breaker logic}

### File Changes

#### Modify
| File | Change | Reason |
|------|--------|--------|
| {path} | {what} | {why} |

#### Create
| File | Purpose |
|------|---------|
| {path} | {what it does} |

#### Delete
| File | Reason |
|------|--------|
| {path} | {why removed} |

### Config
| Item | Type | Value / Source | Environment |
|------|------|----------------|-------------|
| {VAR_NAME} | env var | {description} | dev / staging / prod |
| {API_KEY} | secret | {external service name} | all |

### Unit Test Cases
> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`

| ID | AC Ref | Type | Description | Input | Expected Output |
|----|--------|------|-------------|-------|-----------------|
| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |

### Tasks
> Each task names the AC(s) it serves, so every AC traces to ≥1 task (no AC left unbuilt).
- [ ] I1: {file + change} — AC-1
- [ ] I2: {file + change} — AC-2
- [ ] I3: Unit tests for AC-1, AC-2

---

## Stack: App
> *(omit this section entirely if App/mobile stack not involved)*

### Logic Flow
1. {entry point — screen/view}
2. {state management / local validation}
3. {API call / deep link}
4. {response handling / navigation}

### File Changes

#### Modify
| File | Change | Reason |
|------|--------|--------|
| {path} | {what} | {why} |

#### Create
| File | Purpose |
|------|---------|
| {path} | {what it does} |

#### Delete
| File | Reason |
|------|--------|
| {path} | {why removed} |

### Config
| Item | Type | Value / Source | Environment |
|------|------|----------------|-------------|
| {VAR_NAME} | env var | {description} | dev / staging / prod |

### Locator Map
> `testID` (React Native) per `.tas/rules/common/locator-naming.md`. SSoT for `/tas-dev` (inject into source) + `/tas-functest-mobile` (consume).
> Best-effort at plan time — `/tas-dev` back-fills any element missing here. Origin: `plan` = seeded by `/tas-plan` | `dev` = back-filled by `/tas-dev`.

| Element (business) | testid | Component / File | Actions | AC Ref | Origin |
|---|---|---|---|---|---|
| {Email field} | ipt_auth_email | {LoginScreen.tsx} | type | AC-1 | plan |
| {Submit button} | btn_auth_submit | {LoginScreen.tsx} | click | AC-1 | plan |

### Unit Test Cases
> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
> Unit tests do NOT use locators — query by role/label/text (Testing Library). Locator Map is for functional/E2E only.

| ID | AC Ref | Type | Description | Input | Expected Output |
|----|--------|------|-------------|-------|-----------------|
| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |

### Tasks
> Each task names the AC(s) it serves, so every AC traces to ≥1 task (no AC left unbuilt).
- [ ] A1: {file + change} — AC-1
- [ ] A2: {file + change} — AC-2
- [ ] A3: Unit tests for AC-1, AC-2

---

## Changelog
| Date | Changes | Author |
|------|---------|--------|