# Skills & Roles (backend)

Backend-scoped copy of the root `SKILLS.md` — same five roles, applied to
`backend/` surfaces (Next.js API gateway, OCR pipeline, Postgres, Docker/deploy)
during `n`/`next` execution (see `AGENTS.md` Part B, this dir). One agent can play
all of them in sequence; a multi-agent harness may spawn each as a separate
subagent for a fresh-context pass. Order matters: Architect → Backend/Frontend →
QA → Hardware/Compatibility.

## 1. Software Architect

**Responsibilities**
- Decide where new backend code lives; keep module boundaries clean (API routes vs.
  `utils/` business logic vs. `db/` layer vs. the Python pipeline in `config/`).
- Prefer deep modules (few, well-bounded files with simple interfaces) over shallow
  ones — this is what keeps the codebase navigable for an agent.
- Own the 256-LOC split rule (`AGENTS.md` Part B §B3): when a file crosses the
  threshold, decide the split boundary before anyone patches around it.
- Keep `plans/next-enhancements.md` (this dir) structured by real backend module
  boundaries, not arbitrary groupings.
- Owns the existing-project audit (`AGENTS.md` Part B §B0) for backend specifically.

**When invoked**: start of every `e`/`enhance` run; start of every `n`/`next` task,
before implementation begins.

**Handoff**: hands the Backend/Frontend roles a target file layout and interface
contract, not just a task description.

## 2. Backend Engineer

**Responsibilities**
- Implement Next.js API route logic, DB access (`src/db/`), and the Python OCR
  pipeline (`config/classify_ocr_server.py`, pipeline API) as the task requires.
- Wire the mock-vs-live routing required by the Demo/Live switch (`AGENTS.md` Part B
  §B5) and the Cloud/Local endpoint switch (§B6) if/when built — both must resolve
  through the same contract so swapping either setting never changes calling code.
- Keep business logic out of route handlers (`src/app/api/**/route.ts`); route
  handlers stay thin, matching the existing `utils/parser.ts`-style separation.
- Use `withTransaction` (`src/db/index.ts`) for any multi-statement write that must
  be atomic — see task 7.1 in the pre-kit history for why this matters here.

**When invoked**: any task touching API routes, the DB layer, or the OCR pipeline.

**Handoff**: gives Frontend a stable contract (types/response shape) to build
against; gives QA the list of new/changed endpoints and their expected error modes.

## 3. Frontend Engineer

**Responsibilities**
- Implement UI for the task inside `pfm-web-app/src/app/`, including Demo/Live and
  Cloud/Local switcher controls where relevant.
- Follow this repo's existing page pattern: consolidated single-page flows (root
  `page.tsx`) vs. standalone-purpose route folders (`manual-label/page.tsx`,
  `scan-pfm/page.tsx`) — see backend `CLAUDE.md` for which pattern a given feature
  should follow.
- Consume the Backend Engineer's contract rather than reaching around it.
- Keep components small and composable, respecting the 256-LOC rule.

**When invoked**: any task with a user-facing surface inside `pfm-web-app/`.

**Handoff**: gives QA the golden-path user flow and the edge cases it's aware of.

## 4. QA / Test Engineer

**Responsibilities**
- During clarification (`AGENTS.md` Part B §B2a), turn resolved answers into
  concrete acceptance criteria — what "done" verifiably means.
- Write/extend automated tests (`parser.test.ts` pattern) for the change.
- For anything touching `parser.ts` or the OCR pipeline, run the accuracy
  regression harness (`node pfm-web-app/scripts/accuracy-check.mts` or `accuracy-check-scan.mts`) and check for
  regressions against the current baseline (see `sources/accuracy_history.jsonl` and `sources/product_accuracy_history.jsonl` for latest metrics), not just "it compiles."
- Run the **verify build integrity** pass: golden path + edge cases + regression
  check on adjacent features.
- Reject work back to the relevant role if acceptance criteria aren't met — don't
  patch around a failing check.

**When invoked**: acceptance-criteria drafting during §B2a; final verification pass
before a task is marked `[DONE]`.

**Handoff**: reports pass/fail with specifics (what broke, under what input) back to
whichever role owns that surface.

## 5. Hardware & Performance Compatibility Reviewer

**Responsibilities**
- Check the change against this stack's real constraints: single vs. dual-GPU dev
  mode (`docker-compose.yml` runs `npm run dev`, a known throughput ceiling), VRAM
  budget for vLLM (`gpu-memory-utilization` in `config/vllm_config.yaml`), and
  behavior under the Local/on-prem deployment mode from `AGENTS.md` Part B §B6.
- Flag newly introduced heavy Python/Node dependencies, GPU-specific assumptions, or
  anything that would break the isolated vLLM-server-only environment (no
  `paddlepaddle-gpu` in this venv — see `AGENTS.md` Part A / `docs/vllm-service.md`).
- Flag anything that would degrade badly on lower-spec hardware or slower networks
  (e.g. the mobile app's 2s polling loop against a slow backend response), and
  suggest a lighter-weight alternative when one exists.

**When invoked**: final verification pass, alongside QA, before a task is marked
`[DONE]`; also whenever a task adds a new dependency or changes the deployment/
runtime surface.

**Handoff**: blocks `[DONE]` status until concerns are resolved or explicitly
accepted as a documented trade-off in `docs/feature-list.md` (this dir).