---
name: backend-change-planning
description: Use when backend work requires contract-first thinking, schema changes, permission checks, side-effect analysis, or test planning.
---

# Backend Change Planning

Use this skill before implementing non-trivial backend changes.

## Check in this order

1. **Contract changes** — are request/response shapes, status codes, or error formats changing? List every endpoint affected. If the API is public or consumed by other teams, flag it as a breaking change risk.
2. **Schema and migration changes** — are tables, columns, indexes, or constraints being added, modified, or removed? Migrations must be:
   - Reversible (or explicitly flagged as one-way)
   - Safe under concurrent traffic (no locking whole tables in production)
   - Applied before code that depends on them
3. **Query and repository impact** — are queries changing? Check for N+1 patterns, missing indexes on new filter columns, and unbounded result sets.
4. **Validation and error flow** — is input validation complete at the boundary? Are error types and messages consistent with the existing codebase?
5. **Permission and ownership checks** — does the change enforce proper authorization? Can a user access or modify resources they don't own?
6. **Audit and other side effects** — does the change need to emit events, logs, notifications, or update caches? Are these handled transactionally or eventually?
7. **Tests** — for each item above, define the tests that verify correctness:
   - Contract tests (request/response shape validation)
   - Migration tests (up and down)
   - Permission boundary tests (authorized vs. unauthorized)
   - Error path tests (invalid input, dependency failure)

## Expected output

Produce a structured checklist with findings for each item:

1. contract impact — [endpoints affected, breaking changes]
2. schema and migration impact — [tables, columns, reversibility]
3. query impact — [new queries, indexes needed, performance notes]
4. validation and error handling — [boundary checks, error types]
5. permission and ownership impact — [auth rules, resource scoping]
6. audit and side effects — [events, notifications, cache invalidation]
7. required tests — [specific scenarios with expected outcomes]

Write "N/A — [reason]" for items that do not apply.

## Implementation order for backend changes

1. Migrations first — run and verify before deploying code that uses new schema
2. Shared types and interfaces second — DTOs, error types, shared validators
3. Repository/data layer third — new queries, updated repository methods
4. Service/business logic fourth — core behavior
5. Handlers/controllers fifth — wiring to HTTP or event triggers
6. Tests alongside each step — do not batch all tests to the end

## Common backend mistakes to verify against

- Missing database index on a new WHERE clause or JOIN column
- Nullable column added without handling NULL in existing queries
- Migration that locks a large table under traffic
- Error response format inconsistent with existing API conventions
- Transaction boundary too wide (holding locks longer than necessary) or too narrow (partial updates on failure)
- Missing rate limiting or pagination on new list endpoints

Maintain this checklist consistently with the repository guidance in `docs/agent-playbook.md`, and update any related agent/template docs together when intentional workflow changes are made.

## Conformance self-check

Before marking backend planning as complete, verify:

- [ ] All 7 checklist items are addressed (N/A with reason if not applicable)
- [ ] `DECISIONS.md` was read and no contradictions exist
- [ ] Implementation order follows: migrations → shared types → repository → service → handlers → tests
- [ ] Common backend mistakes were checked against
- [ ] For high-risk changes: plan was presented to user for approval before implementing

## Use this skill when

- Implementing non-trivial backend changes (schema, API contract, permissions, side effects)
- Backend work involves database migrations or query changes
- Planning changes that affect multiple service layers or external integrations