Awesome_IA_Rules / core

---
description: "4-Phase Spec-Driven Development (SDD) workflow for backend, BFF, and frontend features"
globs:
alwaysApply: false
---

# Spec-Driven Development (SDD) Workflow

> **Mandate**: Specification precedes implementation. Never write production code—whether backend services, BFF endpoints, or frontend features—before establishing an explicit, verifiable specification of behavior, contracts, architecture boundaries, and failure modes.

---

## 1. The 4-Phase SDD Lifecycle

Every non-trivial feature, API change, UI flow, or refactoring must progress through four explicit gates:

```mermaid
flowchart LR
    P1["1. Specify<br/>(Requirements & Contracts)"] --> P2["2. Plan<br/>(Architecture & Slices)"]
    P2 --> P3["3. Execute<br/>(Test-First Implementation)"]
    P3 --> P4["4. Verify<br/>(Audit against Spec)"]
```

### Phase 1: Specify (What & Why)
Before designing or coding, inspect the existing codebase and define:
1. **Problem & Goal**: Concise statement of the business capability and operational/UX constraints (latency, throughput, consistency, idempotency, accessibility, SSR/CSR hydration).
2. **Domain Invariants & State Transitions**:
   - *Backend*: Preconditions, postconditions, entity state machine transitions, and business rules.
   - *Frontend*: UI state matrix (`loading` / skeleton, `success`, `empty`, `error` with retry, optimistic updates) and user interaction flows.
3. **Interface Contracts (Contract-First)**:
   - *Backend / BFF*: Inbound/Outbound schemas (OpenAPI 3.1, AsyncAPI, gRPC Protobuf, Zod schemas, or typed DTOs), field-level validation rules, and complete error matrix (`400`, `401`, `403`, `404`, `409`, `422`, `424`/`502`, `500`).
   - *Frontend*: Component Props interfaces, custom Hook input/output contracts, server-to-client hydration props, and analytics/accessibility requirements (WCAG 2.1 AA, ARIA roles, keyboard navigation).
4. **Acceptance Criteria (Given / When / Then)**: Deterministic scenarios covering happy paths, boundary conditions, authorization checks, and failure modes.

> **Ambiguity Gate**: If requirements, edge cases, or breaking-change impacts are ambiguous, **stop and ask targeted clarifying questions** with concrete options and trade-offs before writing code.

---

### Phase 2: Plan (How & Where)
Translate the specification into an architectural execution plan:
1. **Layer & Boundary Mapping**: Identify exact files to create or modify across layers, respecting existing repository scaffolding:
   - *Backend (Go / Java)*: `Domain → Application → Infrastructure (Repository / Adapter / Entrypoint)`.
   - *Backend / BFF (Node.js)*: `Routes → Controllers (Zod Schemas) → Applications (AppDto) → Gateways (GwDto)`.
   - *Frontend (React / Next.js / SSR)*: `Pages/Routes → Feature View → Custom Hooks (Data/Logic) → Sub-Components`.
2. **Data, State & Migration Strategy**: Define persistence model changes, backward-compatible DB migrations, cache invalidation / query keys, and idempotency strategies.
3. **Vertical Task Breakdown**: Decompose work into small, independently testable steps ordered from the core out:
   - `Step 1`: Core Domain / Schemas / Types + Test Data Builders.
   - `Step 2`: Application Use Cases / Custom Hooks + Unit Tests.
   - `Step 3`: Infrastructure Gateways / Repositories / UI Sub-Components + Unit/Integration Tests.
   - `Step 4`: Entrypoints (REST Controllers / Feature Views / Pages) + Contract/Component Tests & Docs.

---

### Phase 3: Execute (Test-First Implementation)
Implement each vertical slice with strict discipline:
1. **Red → Green → Refactor**: Write unit/component tests (using AAA + Builder pattern) derived directly from the `Given/When/Then` criteria before or alongside the implementation.
2. **Zero Scope Creep**: Implement **only** what is specified in the approved plan. Do not introduce unrequested features, speculative abstractions, or unrelated stylistic refactors.
3. **Self-Contained Steps**: Keep each slice compilable, lint-clean, and passing all tests before advancing to the next slice.

---

### Phase 4: Verify (Spec Compliance Audit)
Before declaring a task complete, verify every item against the specification:
- [ ] **Contract Parity**: Does the implementation match the OpenAPI/Zod/TypeScript contract and error status matrix 1:1?
- [ ] **Scenario Coverage**: Is every `Given/When/Then` acceptance criterion and UI state (`loading`, `empty`, `error`, `success`) covered by an automated, deterministic test?
- [ ] **Architecture Alignment**: Do all dependencies point inward with zero leakage of persistence/transport models into Domain or UI layers?
- [ ] **Security & Accessibility**: Are inputs validated, authz derived from verified context, PII excluded from logs/URLs, timeouts configured, and WCAG 2.1 AA semantics met (for UI)?
- [ ] **Documentation Sync**: Are API specs, `README.md`, and `CHANGELOG.md` updated?

---

## 2. Lightweight Spec Template

When asked to specify or plan a feature, use this compact structure:

```markdown
# Spec: [Feature / Endpoint / Component Name]

## 1. Context & Objective
- **Goal**: [1-2 sentences on what changes and why]
- **Non-Goals**: [Explicitly out of scope]

## 2. Contracts & State Matrix
- **API / Route / Component**: `POST /api/v1/resources` or `<FeatureView />`
- **Input Contract (Request Schema / Props)**: [Fields, types, validation constraints]
- **Output Contract (Response Schema / UI States)**: [Success payload + Loading/Empty/Error states]
- **Error Matrix**:
  | Scenario | Semantic Code | HTTP / UI Behavior |
  | :--- | :--- | :--- |
  | Invalid input | `VALIDATION_ERROR` | `400` / Field error alert |
  | Business conflict | `RESOURCE_CONFLICT` | `409` / Conflict banner |
  | Upstream outage | `DEPENDENCY_FAILURE` | `424` or `502` / Retryable error state |

## 3. Domain Rules & Acceptance Criteria
- **AC1 (Happy Path)**: Given [precondition], When [action], Then [expected outcome].
- **AC2 (Validation / Invariant)**: Given [invalid input/state], When [action], Then reject with `[Semantic Code]`.
- **AC3 (Resilience / Edge Case)**: Given [upstream failure or duplicate request], When [action], Then [safe fallback / idempotent behavior].

## 4. Implementation Plan (Files & Layers)
1. `domain / schemas / types`: [Files to create/modify]
2. `application / hooks`: [Files to create/modify]
3. `infrastructure / gateways / components`: [Files to create/modify]
4. `entrypoints / views / tests`: [Unit, integration, and component test cases]
```