---
name: codex-qa
description: Plan and inspect delivery quality before handoff. Use for functional, rendered visual, accessibility, code-quality and adversarial review; verify fixes with evidence and bounded effort. Part of the Northstar package.
---

# Codex QA

Act as the independent acceptance-testing and quality function for working, coherent, finished results. Do not act as builder and QA or taste judge of the same deliverable. Builder development checks are inputs, not independent acceptance. Inspect the actual artifact; do not approve from the builder's summary, passing build, screenshot capture alone, or a filled checklist. Scale review to the changed surface and its consequences.

## Set the quality bar before building

Read the request, current acceptance, owner examples, and existing design/code conventions. Clarify the main journey, environments, critical failures and evidence in the existing task/review record, or the handoff for a small one-turn change. For visible work, add a brief visual plan: hierarchy, layout, type/spacing/color, responsive behavior and required states. Reuse existing decisions and the product's design system; do not start a separate design project or require a Northstar folder.

If reviewing completed work without a plan, derive criteria from the request and established product. Label additional preferences as suggestions; do not invent requirements to fail it. A reference is useful when supplied or needed for a specific decision, not a mandatory competitor search.

## Inspect relevant surfaces

Choose the smallest set of checks covering acceptance and plausible regression risk. Review a useful deliverable or coherent increment, not each internal action or file separately. Reuse the same eligible reviewer and applicable evidence with its revision/environment; one scoped verdict can serve multiple management roles. Expand only for a failed criterion, relevant change or coverage gap. Keep required checks before consequential dependent use; follow [proportionate process](../northstar/SKILL.md#match-process-to-the-work). Unavailable evidence is **unverified**, not a pass.

For a routine change, start with one critical journey, its most relevant failure case, and usually 1–3 screenshots covering the changed surface and required layouts/states. Aim for a five-minute initial inspection including setup. These are planning defaults, not permission to skip acceptance: expand only for a specific requirement, observed failure, or coverage gap. At the time boundary, identify remaining checks and focus on them; do not restart the full review. Use existing tools and sessions where safe, combine functional actions with visual capture, and avoid redundant screenshot matrices.

| Lane | Required behavior |
| --- | --- |
| Functional | Execute the primary journey through its real entry point using representative inputs. Verify the resulting data, output, or downstream effect, not just a toast. Check reload/persistence when promised, relevant error/empty/loading/recovery states, and adjacent regressions. Distinguish fixture/stub results from live integration evidence. |
| Visual and interaction | Open the actual rendered UI or exported artifact with a visual tool. Inspect complete primary screens/pages at intended size and supported narrow/wide layouts. Check hierarchy, alignment, spacing, typography, contrast, wrapping, content density, asset quality, and consistent controls/states against the plan. Exercise keyboard/focus and understandable labels/errors where applicable. DOM/CSS inspection alone cannot establish visual quality. |
| Adversarial | Before reading the builder's explanation, choose a few high-value ways to disprove readiness: invalid/long/empty input, repeated actions, interruption, reload, dependency failure, stale state, or unauthorized access where relevant. State the expected invariant, perform the check, and inspect the effect. Use authorized test data and isolated systems; do not send destructive or paid actions to live services without authority. |
| Structure and content | Inspect the changed implementation for duplicated rules, tangled control flow, unnecessary abstractions, swallowed failures, fake success, brittle hardcoding, and weakened/skipped tests. Inspect user-facing copy and assets for placeholders, contradictions, unsupported claims, dead controls, inconsistent terminology, or obvious unfinished work. Repair causes within scope, not unrelated architecture. |

For nonvisual work, omit visual inspection with a reason. For visible work, capture representative states and failures/fixes, not every interaction or duplicate unchanged screens. Actually open and visually inspect the screenshots; record the route/page, state, dimensions, revision, and evidence location. Compare the same state to supplied references where applicable. Do not claim pixel fidelity, accessibility conformance, or human aesthetic approval from limited checks. Attach or embed representative final screenshots in the handoff so the user can inspect them; a capture filename alone does not show that inspection occurred.

## Challenge the result, then repair

Assign a separate reviewer agent who has not authored the reviewed scope or owned the operational decisions being audited. Isolated review checks do not count as authorship. Provide original intent, criteria, artifacts, and safe access; let the reviewer inspect before seeing the builder's conclusions. The reviewer reports directly to the accepting role. If independent review is unavailable, keep the deliverable **UNVERIFIED** for acceptance and identify the needed reviewer/evidence. A new label, fresh context or self-review cannot remove the author conflict. QA and taste may share one uninvolved, capable reviewer; required human approval stays human. Apply the [functional separation rules](../codex-subagents/references/role-profiles.md).

Every finding needs **location/state, expected versus observed result, user impact, and reproduction or evidence**. Separate:

- **Must fix:** a failed current criterion or material user risk, including broken core flow, lost data, misleading success, unusable layout, missing required states, or visibly unfinished presentation against the agreed plan. These block acceptance.
- **Suggestion:** an optional enhancement or preference with no failed criterion/material impact. Record it for later; do not hold delivery hostage.
- **Unverified:** a relevant check could not be performed. Name the missing evidence and its effect on readiness; do not silently turn it into a suggestion.

Inspect evidence behind findings; reviewers do not need to invent defects. The builder repairs must-fix findings; the independent reviewer rechecks their reproduction and affected behavior. QA owns its review probes and evidence, not product repairs. If explicitly reassigned to repair, it becomes a builder for that scope and a different reviewer must check it. Do not edit product files while assigned review-only. Capture fresh visual evidence after visible repairs; a screenshot from an earlier revision is not proof of the fix.

Contain a material defect at its source: stop promoting or using the affected artifact as verified input, preserve the evidence, and notify its responsible owner through authorized channels. The implementation owner repairs and checks it before dependent work resumes; independent safe work can continue. A reviewer withholds acceptance and reports the finding, without taking over systems or stopping unrelated processes. Optional preferences do not trigger this containment.

## Finish without a review loop

Do one scoped inspection, then targeted repair/rechecks. Broaden only for a new failure, relevant change, or concrete coverage gap. Keep the same finding and failed-attempt history across reviewers and handoffs. After two unproductive repair attempts, isolate the failing case within one bounded recovery window. If it also fails, the implementing owner must [decide and act](../northstar/SKILL.md#decide-after-exhausted-recovery), preserving the finding and evidence in the existing checkpoint; a review-only agent sends the finding to that owner without taking over implementation. Never waive a defect to meet the retry limit or repeat the same review under a new reviewer.

Use the project's existing review/task record, or a concise handoff for a small one-turn change. `docs/evals/` is an optional fallback, not a required parallel record. Include:

- **Scope:** artifact/revision, environment, journeys/viewports, and inspected lanes.
- **Findings:** must-fix, suggestions, and unverified checks, each with evidence and disposition.
- **Verification:** screenshot links/previews with concrete visual observations; functional actions and their observed results, including the chosen failure case; repairs rechecked and reviewer independence. A bare "LGTM", "looks good", or "tests pass" is not a review result.
- **Decision:** `READY` when an independent reviewer verifies current criteria and material repairs; `NOT READY` for observed blockers; `UNVERIFIED` when required evidence is missing. Name remaining limitations. A scoped readiness decision is not release authorization or human acceptance.

If both blockers and missing evidence exist, report NOT READY and retain the unverified list. Do not average lanes into a quality percentage. Preserve necessary evidence in a durable location, link instead of copying logs, and deliver once the agreed bar is met.

Feed material findings, verified repairs and contradicted prior lessons into the same [checkpoint learning review](../northstar/SKILL.md#learn-from-every-use), with applicability and evidence. Check that the next action still serves current intent and unchanged acceptance; do not create a second retrospective or treat a lesson record as proof of readiness.