Skip to main content

QA and Review Loop

Source: .agents/references/implementation/qa-and-review-loop.md

Content​

QA and Review Loop

Use this after a worker reports DONE or DONE_WITH_CONCERNS.

Per-Task Loop​

  1. Worker implements the task and reports completion.
  2. For a page task, the worker adds or updates the owned Playwright spec and runs the recorded page-level command.
  3. Master agent marks task implementation-done only when required page coverage exists and passes.
  4. QA agent reruns the recorded page-level Playwright command and verifies it against requirements and acceptance criteria.
  5. Code review agent reviews with .agents/skills/code-review/SKILL.md.
  6. If both pass, mark task passed.
  7. If QA fails, mark qa-failed, record feedback, increment retry count, and return the task to the same worker or a replacement worker with exact QA feedback.
  8. If code review fails, mark review-failed, record feedback, increment retry count, and return the task to the same worker or a replacement worker with exact review feedback.
  9. Repeat until both QA and code review pass or the task is blocked.

Pass Criteria​

QA passes only when:

  • Acceptance criteria are satisfied.
  • Required user flows work.
  • Edge cases are handled or explicitly out of scope.
  • Design/Figma requirements match when applicable.
  • Claimed tests/checks are credible for the task.
  • Every affected page has its owned Playwright spec, the exact page-level command passes, and the cases cover the main flow plus relevant acceptance-criteria states rather than only page loading.
  • Any blocked or excluded Playwright flow records the exact missing prerequisite. not-applicable is accepted only when the feature has no user-facing page impact.

Code review passes only when:

  • .agents/rules/*.mdc are followed.
  • Relevant feature and coding-standard references were considered.
  • Changed code is scoped to the task.
  • Type safety, service error handling, localization, security, and styling rules are respected.
  • Tests are adequate for risk and blast radius.
  • Page-by-page Playwright coverage, cases, ownership, and execution evidence are complete.
  • Any conflict resolution is scoped correctly and does not revert unrelated work, dependency-task behavior, or existing approved behavior.

Retry Handling​

  • Keep retry count per task.
  • Preserve failed feedback in the checklist.
  • Do not retry with identical instructions after a blocker; add context, narrow scope, or escalate.
  • If a task fails repeatedly because scope is too large, split it and update the checklist/worktree assignments.
  • If QA or review fails because of incorrect conflict resolution, return the task to the conflict owner with the exact files, expected preserved behavior, and dependency task(s) involved.

Integration Gate​

The master agent may coordinate integration of a task only after:

  • Status is passed.
  • Worker changed-file report is reviewed.
  • QA result is PASS.
  • Code review result is PASS.
  • No unresolved dependency is blocking the task.
  • Any task-scoped conflicts are resolved by that task owner and reviewed.

Final Feature Verification​

After all tasks pass and are integrated:

  • Run every page-level Playwright command recorded in the page test inventory.
  • Run bun run playwright:test as the final integrated browser suite gate.
  • Return feature-related Playwright failures to the responsible page owner or a dedicated integration worker; do not waive or silently skip them.
  • Run final relevant checks/tests.
  • Run or delegate final code review for the integrated diff.
  • Assign any repo-editing final integration fixes to a dedicated non-master integration worker.
  • Confirm no unrelated files changed.
  • Confirm conflict resolutions preserve all passed task behavior.
  • Confirm feature references were updated if durable domain behavior changed.
  • Prepare final summary and suggested PR description.