backend-implement

Implement the approved backend scope so it satisfies the contract exactly. The backend owns the contract — implement it as published; never silently change it.

When to use / not use

• Use after the contract is approved (and ideally /backend-tasks has produced a plan).
• Don't start if the contract is unstable, or expand scope beyond what was approved.

Before editing

1. Read CLAUDE.md, AGENTS.md, the backend LLD (docs/technical/<slug>/lld/backend.md),

and the contract (contracts/<slug>/openapi.yaml).

1. Read the /backend-tasks plan if present; otherwise derive the same ordered slices.
2. List the files you intend to change.
3. Stop and ask a human before DB migrations, auth/permission, payment logic, prod

config, or dependency upgrades.

Steps (per task, test-first)

1. Write the failing test first from the contract/acceptance criteria (RED).
2. Implement the minimum to pass it (GREEN), in dependency order: types/schema →

domain/service → persistence → API/controller.

1. Refactor with tests green; remove duplication.
2. Add cross-cutting concerns for the slice: validation, error mapping, logging/metrics.
3. Run the targeted check, then move to the next task. On failure, invoke /fix.
4. After all tasks, run full /verify and address the standards checklist.

Standards every backend change must satisfy

• Security — authorize every operation (never trust the client); validate & bound all

input; parameterize queries (no injection); encode output; secrets never in code/logs; minimize/protect PII; safe deserialization; no SSRF from user-supplied URLs.

• Backward compatibility — additive by default; don't remove/rename/retype fields or

tighten validation without a version + migration; defaults for new fields; old clients keep working.

• Rate limiting & abuse — limits/quotas on new endpoints; cap page size & payload size;

sane timeouts; guard expensive operations; return 429 + retry-after when exceeded.

• Idempotency & retries — mutating/retryable operations honor an idempotency key or are

naturally idempotent; no duplicate side effects on retry.

• Data & migrations — expand → migrate → contract; reversible; index new query paths;

no online long locks / full-table rewrites; backfill existing rows safely.

• Concurrency — transactions where needed; prevent lost updates (optimistic version/ETag);

choose correct isolation; handle races.

• Observability — structured logs (no secrets/PII), metrics on new paths, tracing spans,

and an error taxonomy mapped to the contract's error shape.

• Performance — no N+1 or unbounded queries; bound query cost; cache/pool where the LLD says.
• Error contract — return the contract's error envelope and correct status codes; never

leak internals in messages.

Edge cases to implement and test (not just the happy path)

• Inputs: null / missing / empty / whitespace / max-length / oversized / negative / zero /

boundary numbers / invalid enum / malformed / duplicate / unicode / injection payloads.

• Auth: unauthenticated, expired token, insufficient scope, cross-tenant access attempt.
• Concurrency: two writers on the same entity; retry after timeout; idempotency-key reuse.
• Failure: downstream dependency down/slow; DB error; partial write; timeout → correct fallback.
• Pagination: first/last/empty page, invalid cursor, unstable ordering.
• Rate limit reached; large result sets; time zones / DST / numeric precision & rounding.

External skill (provision — the TDD engine)

Read skills.config.yaml → backend.external.tdd (default test-driven-development, from the Superpowers pack, or none). If set, use it to drive RED → GREEN → REFACTOR. Whatever the engine, ensure the tests it produces cover the edge cases above and the contract's negative paths — not happy-path only. If none, implement then add unit + integration tests to the same bar.

Safety

Never run destructive commands (rm -rf, force-push, DROP/TRUNCATE TABLE) or write prod config/secrets (.env, keys) — those are human pre-steps. Nothing auto-blocks this; you are the backstop.

Verification

Invoke /verify (lint, typecheck, unit + integration, migration check, provider-side contract validation). On failure invoke /fix (bounded to 3; delegates to shared.external.debug).

Definition of done (stop condition)

Tests ran and pass; every standards item addressed or explicitly noted; edge-case tests exist; changed files summarized; remaining risks listed; contract honored exactly. Passing checks are the proof — not a message that says "done". Outputs: branch, summary, tests_passed.