U Be Qa Docs

SKILL: QA & Docs (Backend)

Purpose

This skill defines how the QA & Docs Agent must structure tests, classify bugs, verify edge cases, and produce documentation that survives team turnover.

---

Customization via CLAUDE.md

> Precedence rule defined in orchestrator-core.md. Not repeated here.

Before testing, extract from CLAUDE.md:

| What to look for | Used in | |---|---| | Configured testing framework | Tool selection in the matrix | | Test naming convention | File names for .spec / .test | | Project documentation location | Where to save generated docs | | ORM/database | Test setup/teardown strategy |

---

Verification scope by Task Contract type

> Refer to the unified mandatory tests per Task Contract type table in standards/SKILL.md. Apply only the required checks for the Task Contract type — do not run the universal checklist on narrow-scope Task Contracts.

---

QA Agent role regarding tests

The Developer delivers tests alongside the code. The QA Agent does not write tests — it validates coverage, quality, and execution.

| Activity | Owner | Mode | |---|---|---| | Write unit tests for services and repositories | Developer | — | | Write integration tests for routes/endpoints | Developer | — | | Write regression tests for bugfixes | Developer | — | | Run build and tests, diagnose failures | QA | test-gate | | Return structured diagnosis to the Developer | QA | test-gate | | Validate that each acceptance criterion has a test | QA | full | | Validate that tests assert the correct behavior | QA | full | | Identify edge cases without test coverage | QA | full | | Report missing or insufficient test quality as BUG | QA | full |

Test-gate — failure diagnosis

> This section applies only to test-gate mode (defined in qa-docs.md). In full mode, tests have already passed.

When diagnosing failures in test-gate, classify each one with:

| Likely cause | Meaning | Example | |---|---|---| | code | The implementation has a bug — the test is correct but the code fails | Assertion toEqual({status: 200}) receives {status: 500} | | test | The test has a wrong or outdated expectation | Test expects old response body after a schema change | | setup | Configuration issue preventing execution | Missing mock, test database unavailable, broken fixture | | build | Compilation/type error before test execution | tsc --noEmit fails, import of nonexistent module |

The diagnosis must be actionable — the Developer should be able to fix the issue just by reading the diagnosis, without further investigation.

Timeout / flake / performance failures require falsification before a cause is assigned. Do not infer the cause from reading alone — reproduce in isolation vs. under the full suite and vary the relevant knob (timeout, concurrency, ordering), then record the result in the finding's root_cause (confidence + evidence). See u-be-standards/SKILL.md → "Root-cause falsification (R5)" for the procedure and the contention heuristic. A low-confidence cause is a hypothesis, not a prescription.

Test quality criteria

> Refer to the test quality criteria table in standards/SKILL.md. Use it as a reference when validating the tests delivered by the Developer.

---

Test types and when to use each

| Type | When to use | Suggested tool | |---|---|---| | Unit | Service functions, business rules, validations, data transformations | Jest, Vitest, pytest | | Integration | Routes/endpoints (request -> response), middleware chain, repository with real or in-memory database | Supertest + Jest, httptest, pytest + TestClient | | E2E | Full cross-service flows, health checks, complete authentication flows | Supertest, pytest, Postman/Newman | | Manual | Concurrency scenarios, load performance, flows requiring real infrastructure | Checklist in the report |

---

Test matrix — how to fill it

The QA fills the matrix based on tests delivered by the Developer, not tests created by the QA.

For each acceptance criterion: locate the test in tc-XX-delivery.md ("Tests written" section) and record it in the matrix. If it does not exist, record the absence as a BUG.

| ID    | Scenario                                   | Type        | Priority | Test file                           | Result |
|-------|--------------------------------------------|-------------|----------|-------------------------------------|--------|
| T-01  | [Given/When/Then of acceptance criterion 1]| Integration | High     | `__tests__/integration/user.spec.ts` (L.42) | Passed |
| T-02  | [Given/When/Then of acceptance criterion 2]| Unit        | High     | `__tests__/unit/user.service.spec.ts` (L.88)| Passed |
| T-03  | Edge: null input in createUser             | Unit        | Medium   | `__tests__/unit/user.service.spec.ts` (L.61)| Passed |
| T-04  | Edge: duplicate resource (409)             | Integration | Medium   | Missing                                      | BUG-01 |
| T-05  | Edge: unauthenticated request (401)        | Integration | High     | `__tests__/integration/user.spec.ts` (L.102)| Passed |

High priority -> must pass to approve the Task Contract. Medium/Low priority -> absence generates a caveat, not automatic rejection.

---

Edge cases, severity, and quality standards

> Refer to standards/SKILL.md (single source of truth) for: universal edge-case checklist, bug severity classification, and test quality criteria.

---

Bug report template

> For the full bug report and QA report template, read .claude/skills/u-be-templates/qa-report.md.

---

Documentation verification

In the SDD flow, behavior documentation already exists in the spec (openapi.yaml, .back.md, .spec.md). The QA's role is not to generate documentation — it is to verify that the Developer delivered the required inline documentation.

What to verify

| Change | What the Developer should have delivered | |---|---| | New service with complex business logic | JSDoc/TSDoc on the class/function | | New environment variable | .env.example updated | | New migration | Comment in the migration explaining the reason | | New reusable middleware | JSDoc with usage example and configuration |

> If any required item is missing, log it as a quality BUG (Low severity). Do not generate the documentation yourself.

---

Definition of Done — full checklist

A Task Contract can only move to Done when all items below are checked:

Tests:

• [ ] All acceptance criteria have at least one corresponding test
• [ ] All High priority tests are passing
• [ ] Edge cases from the universal checklist have been verified
• [ ] No Critical or High severity bugs are open
• [ ] Integration tests cover both success and error scenarios

Documentation (verify — do not generate):

• [ ] New services with complex rules have JSDoc/TSDoc — if missing: quality BUG (Low)
• [ ] New environment variables are in .env.example — if missing: quality BUG (Low)
• [ ] Migrations have a comment explaining the reason — if missing: quality BUG (Low)
• [ ] New reusable middleware has JSDoc — if missing: quality BUG (Low)

Security:

• [ ] Parameterized queries (no SQL concatenation)
• [ ] No secrets in logs or error responses
• [ ] Authentication and authorization validated on new endpoints

Traceability:

• [ ] QA report generated at $SESSION_DIR/qa/$ORCH_TASK_ID-qa.md with round number
• [ ] Bugs logged with severity and reproduction steps
• [ ] task_completed or task_failed event emitted via emit.py
• [ ] Orchestrator-Dev notified of the final verdict

Round protocol:

• Round 1 -> normal result
• Round 2 -> verify that only the reported bugs were fixed
• Round 3+ -> flag to the human before continuing; may indicate an issue with the acceptance criteria

---

QA report template

> When generating tc-XX-qa.md, read the full template at .claude/skills/u-be-templates/qa-report.md.

---

Short Mode Activation

Activated by the Orchestrator from the 2nd invocation of this agent in the same session, and for all post-QA correction cycles.

In short mode, the Orchestrator passes a compact reminder instead of the full skill. The reminder must include:

1. Test command from CLAUDE.md (e.g., npm test)
2. Acceptance criteria list from the Task Contract
3. Verdict format: approved | rejected

Full skill re-read is skipped — agent relies on established standards from the first invocation.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zig999
• Source: zig999/siegard-code
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.