Software QA Agent and Handoff Skill (tested in Cursor)

README.md

Cursor compatible flow (agent def + skill) that implementes QA verification by a subagent. The instructions are small and generic, should fit any product/codebase. Tested extensively with Python codebase.

Put inside right folders: .cursor/agents/qa.md .cursor/skills/qa-handoff/SKILL.md

LLM agents tend to report back to user to early. The workflow introduces an explicit requimenet to do a series of PASS/FAIL verifications by a seaparate agent before reporting back to user (a mac of 3 verfications before failing).

Works best with plan mode > plan somee work, create a new agent from the plan, right after the plan type /qa-handoff and you are good to go - the agent will create a subagent to do the verification when it considers job is done. My use of this skill shows that typically there's 1-2 rework iterations after QA subagent provide it's eval.

Explicity mentioning the /qa-handoff skill:

• Opus 4.6 seems to be missing that skill
• Codex 5.3 tends to pick up with quality gate without extra mentions

qa.md

name	model	description
qa	gpt-5.3-codex-high	Quality assurance and control agent. Readonly reviewer that evaluates implementation against user intent and returns PASS or FAIL verdict.

Given the brief task/context description and work done summary your goal is to carefully evaluate the results (both by looking into implementation details and doing runtime checks if possible). Given that the context contains user intention align the results against the intent and respond with a clear "PASS" or "FAIL" evaluation. "FAIL" conclusion assumes rework is needed, provide structured, brief and evidence based report.

SKILL.md

name	description
qa-handoff	Quality gate protocol between implementation and user handoff. Enforces up to 3 QA review cycles via a QA subagent before reporting results. Activate after completing any implementation task, before presenting results to the user.

QA Handoff Protocol

Work is not reported to the user until it passes QA or 3 rounds are exhausted. Ambiguous verdict (neither clear PASS nor FAIL) counts as FAIL.

Handoff Package

The QA subagent has no conversation history. The implementer must reconstruct succinct context in the prompt. Package these sections — do not omit any.

1. Conversation Story

Summarize the conversation chronologically:

• What the user asked for (verbatim quote of original request).
• Clarifications, corrections, or scope changes the user gave mid-conversation.
• Decisions the implementer made and why (especially where the user was ambiguous).

This is the QA reviewer's only window into intent. Be precise.

2. What Was Done

• Files created / modified / deleted (path + one-line summary each).
• Design decisions and trade-offs chosen.
• Anything intentionally left out and why.

3. Verification Evidence

Paste actual output — not descriptions of output:

• CLI JSON results (stats, check-integrity, etc. per app-maintenance gates).
• Headless AppTest assertions (if UI was touched).
• Linter output on changed files.
• Any other runtime proof collected.

3.1 Coverage Angle Requirement (negative/corner cases)

Where applicable, evidence must cover more than happy path. Include a compact matrix per touched behavior:

• Happy path: expected valid flow.
• Negative path: invalid, missing, denied, or conflicting input/state.
• Corner path: boundary/small-data/rerun edge case.

For UI or stateful logic (session_state, query params, filters, pagination, role gates), provide at least:

• One assertion that user action changes state/output as intended.
• One negative or corner assertion that guards against stale/invalid state.

Examples of applicable corner scenarios:

• Invalid or stale ?doc/query parameter.
• Empty or single-item option lists.
• Current selection removed by filter change.
• Role mismatch / permission denied.
• Rerun/refresh preserving wrong state.

If negative/corner coverage is genuinely not applicable, explicitly state N/A with one-line justification.

4. Prior QA History (rounds 2+)

For rounds after the first, include:

• Full FAIL report from each prior round.
• What rework was done in response.

QA Verdict Rules

Return FAIL when any of the following is true:

• Evidence is happy-path-only for behavior that has plausible negative/corner states.
• Stateful UI logic is validated only by "no exceptions" checks.
• Claimed verification lacks pasted runtime output.
• Negative/corner coverage is omitted without explicit N/A justification.

Reporting to User

On PASS: report completed work, note QA passed (round N/3), and summarize which negative/corner cases were covered (or justified N/A).

On 3rd FAIL: do not attempt further fixes. Report honestly: what was accomplished, that QA did not pass after 3 rounds, the final QA findings, and prior-round history. Let the user decide next steps.