bbl-senior-backend

Use this skill when THB-BBL backend behavior, schema, contracts, or persistence semantics may change.

When to use

1. Route, payload, auth, schema, migration, or backend business-rule changes in src/app/api/**/route.ts, src/server/services/**, prisma/schema.prisma, or backend/**.
2. Compatibility risk for downstream consumers inside this app (UI screens, exports, and reporting routes).
3. Backend performance, data integrity, privacy, or security-sensitive behavior changes.

When not to use

1. UI-only changes in src/app/** or src/components/** with no backend contract impact.
2. Typo-only edits with no runtime effect.
3. Process-only requests without backend behavior changes.

Preflight

1. Read touched repo guidance (agents.md and relevant docs).
2. Identify affected endpoints, service modules, schema objects, and any mirrored logic in backend/**.
3. Enumerate downstream consumers in this repo that rely on changed payloads/semantics.

Stop condition: if compatibility impact cannot be determined, stop before implementation.

Execution checklist

1. Identify affected API surfaces (src/app/api/**/route.ts) and service/data layers (src/server/services/**, prisma/schema.prisma, backend/**).
2. Classify compatibility as backward-compatible or breaking.
3. Confirm migration approach before schema changes.
4. Add/update route-level tests where present (route.test.ts) and service tests.
5. Run Prisma migration impact analysis when schema changes.
6. Run parity checks when behavior exists in both TypeScript and Python paths.
7. Validate with npm run lint, npm run typecheck, npm run test, and python3 -m pytest backend/tests when Python backend changes.
8. Document rollout and rollback strategy.

Fallbacks

1. If scope becomes cross-layer coordination-heavy, route primary coordination to bbl-senior-fullstack.
2. If scope becomes UI-primary, route to bbl-senior-frontend and keep backend as secondary.
3. If downstream updates are deferred, record explicit compatibility risk and follow-up dependency.

Completion contract

Return:

1. scope_statement
2. affected_endpoints
3. affected_services
4. affected_schema_objects
5. compatibility_status
6. parity_impact (TS vs Python where applicable)
7. files_changed
8. validations_run
9. blocked_checks
10. residual_risks
11. rollback_notes