vertical-slices

# Vertical Slices Build features as independent slices that own contract, business rules, persistence logic, and tests. Prefer feature-first folders and thin entrypoints. Keep business behavior inside the slice, not in transport or framework code. Always follow stricter repository rules when present (for example `AGENTS.md`). ## Outcomes A slice is complete only when all are true: - One clear capability is owned by one slice. - Behavior is implemented in the slice, not in handlers/controllers/routes. - Persistence logic is co-located and transaction-safe. - Tests cover behavior, boundaries, and failure paths with regression depth. - Cross-slice coupling is explicit, minimal, and one-way. If these are not met, do not call the slice done. ## Execution Workflow (Required) ### 1) Define the slice boundary before coding - Name exactly one capability in business language. - Define one owner module (for example `billing`, `session`, `question`). - State what is intentionally out of scope for this slice. - Limit dependencies to shared infrastructure and explicit contracts. ### 2) Write a compact Slice Design Spec before implementation Create a short design note in your working context with: - Capability statement: one sentence with actor + action + outcome. - Invariants: 3-7 rules that must remain true. - Boundary contracts: input, output, error model, idempotency behavior. - Data ownership: tables/entities read and written by the slice. - Dependency map: entrypoint -> slice -> infrastructure only. - Cross-slice touchpoints: event names or explicit interfaces only. - Failure model: validation, conflict, upstream, and persistence failures. If this spec is missing, pause and define it first. ### 3) Define contracts before behavior - Create input/output schemas at the boundary (HTTP, queue, CLI, RPC). - Use the same contract definitions in adapters and tests. - Keep contract definitions in the slice area, not spread across global folders. - Map internal errors to boundary errors in one place. ### 4) Implement business behavior in the slice - Keep handlers/routes thin: validate -> invoke slice -> map result/error. - Keep orchestration and rules in slice functions. - Avoid leaking framework request/response objects into business logic. - Prefer explicit return types at public slice boundaries. ### 5) Co-locate persistence and side effects - Keep slice-specific reads/writes near slice behavior. - Use explicit transaction boundaries for multi-write flows. - Emit side effects only after successful commit. - Make idempotency explicit when retries can happen. ### 6) Enforce low coupling - Use event publication for asynchronous cross-slice reactions. - Use explicit interfaces only when immediate response is required. - Do not deep-import another slice internals. - Keep dependency direction one-way: entrypoint -> slice -> infrastructure. ### 7) Apply test maturity gates (required) Do not stop at export/smoke tests. Build behavior-focused suites: - Unit-level slice tests: - happy path with realistic data - validation failures - domain invariant failures - edge cases for optional/empty/limit inputs - Boundary integration tests when behavior crosses boundaries: - transport + contract validation + error mapping - persistence side effects and rollback behavior - idempotency and duplicate request handling when relevant - Regression tests: - every bug fix must add at least one failing-then-passing test - test must assert behavior outcome, not implementation details ### 8) Run final quality gate before completion - Execute `references/checklist.md` fully. - Discover verification commands from the host repository before running tests: - inspect package/workspace scripts for unit/integration/e2e commands - inspect CI workflows to identify required checks for affected paths - do not assume script names; infer by behavior - Run concrete verification commands for the touched slice paths: - smallest relevant unit command(s) - integration command(s) when boundaries/persistence changed - e2e command(s) when user-visible workflows changed - Prefer package/service-local commands first. Do not use repository root tests when the repo uses a root test guard. - Keep verification aligned with required CI checks for the affected area. - Record exact commands executed, pass/fail outcome, and intentional skips with residual risk. - Record residual risks and follow-ups. - Call out compatibility or migration impact. ## Choose a Blueprint Read `references/blueprints.md` to pick folder templates for backend-only and fullstack repositories. ## Apply Naming Conventions Read `references/naming.md` and pick canonical package and slice names before creating folders and contracts. ## Validate Slice Quality Read `references/checklist.md` and execute the checks before finalizing changes. Do not mark complete if any required check fails. ## Build Mature Test Suites Read `references/testing-maturity.md` when designing tests. Use it to choose test depth, avoid shallow suites, and ensure regressions are captured. ## Refactor Toward Slices If starting from layered architecture, read `references/adoption-playbook.md` and migrate one feature at a time.