RafaelFerSilva/refinement-agent-skills

QA Plan

Derive the baseline test plan for a User Story through socratic examination: test conditions with declared design techniques, expected results asserted only when specifications support them, and questions directed to whoever can resolve the rest. You do not ask "is this story well-written?", that is /refine-story. You answer: what can break, how do I prove it works, and what must exist for me to execute that proof.

A mid-level QA engineer should be able to implement tests directly from this artifact; a senior QA engineer should agree with its prioritization.

US: $ARGUMENTS

Three-layer boundary

Deriving unwritten conditions is the essence of QA, provided it follows established methods. Therefore, the boundary here operates across three layers; the foundation remains requirements-rigor. Every condition in the plan belongs to exactly one layer:

• [SPECIFIED: excerpt] (pt-BR: [ESPECIFICADO: trecho]): condition and expected result originate directly from text. Cite the source.
• [DERIVED: technique] (pt-BR: [DERIVADO: técnica]): the condition follows from a test design technique applied to what was specified. Always name the technique; a condition without a declared technique is a guess and must not enter. Expected results may only be asserted if they follow logically from the specification.
• [UNDEFINED -> Question n] (pt-BR: [INDEFINIDO → Pergunta n]): a legitimate condition whose expected result the specification does not define. The condition enters the matrix; the result becomes a numbered question.

Quick test: "which technique generated this condition, and from which excerpt does it stem?" If either cannot be answered, exclude it from the plan.

Before starting

Read docs/agents/refinement.md in the workspace: it defines the operating mode (with or without code), language (en-US or pt-BR, default en-US), and publishing paths. The mode dictates who answers architectural questions: with code, you resolve them by inspecting the codebase; without code, the engineering team resolves them via questionnaires. Socratic examination and the QA plan are authored in the configured language. If the file is missing, request /configure-refinement and stop.

Steps

1. Load. Read the US, CONTEXT.md, domain ADRs, TEST-DESIGN.md, and invoke the Skill tool for requirements-rigor. If .scratch/<slug>/spec.md exists from /refine-story, start from it: decisions from that session already answer many questions. Without this file, treat the US as unrefined, even if Status: says READY. Completed when: testability triage is stated in a single line: TESTABLE (every expected outcome has an observation point and no dependencies are pending confirmation), TESTABLE WITH RESERVATIONS (conditions can be derived, but at least one outcome lacks an observation point or depends on unconfirmed dependencies), or NOT TESTABLE.

2. Triage. NOT TESTABLE (criteria fail to describe observable behavior: exclusively tasks, or subjective terms without metrics across all criteria): explain what is missing, list 3 to 5 minimal questions, and recommend /refine-story. Stop here; analyzing untestable material produces facade plans. If the US has not undergone refinement, state this and proceed, noting that many questions would be resolved by /refine-story. Completed when: triage is declared.

3. Derive conditions. For each criterion, apply applicable techniques from TEST-DESIGN.md, avoiding forcing inapplicable techniques, and review silent angles, reporting only applicable ones. Build the matrix: condition, origin, expected result or [UNDEFINED -> Question n], priority, layer. Undefined conditions remain in the matrix: visible future coverage is far better than hidden gaps. Number questions in a single sequence across PO and DEV combined, so [UNDEFINED -> Question n] resolves unambiguously. Priority rationales (half-line per condition) go in a list within the risk analysis section, not inside the table. Completed when: every condition has a declared origin and every [UNDEFINED] has an assigned question number.

4. Search for facts before asking. Separate questions by recipient. PO: undefined business behavior. DEV: architecture, observability, testing layer, isolation of external dependencies, time control, test data provisioning, API error response, persistence after failure, technical idempotency. In code mode, dispatch a subagent to answer DEV questions by reading code: is notification synchronous or asynchronous? is there a lock on approval? does a mock exist for the external system? A found fact becomes an expected result or defined layer, with source citation. In no-code mode, search is restricted to workspace files without subagents; if nothing is found, state this in a single line at the top of round 1. Completed when: each question is marked as answered by a source or open, with assigned recipient.

5. Examine PO. Invoke the Skill tool for socratic-examination. The question round accompanies the current matrix, as questions reference specific conditions. The frontier consists of PO questions, blocking items first (those that unblock P1 conditions), each with a recommended answer when specifications provide grounding; when absent, provide "no recommendation" (or "sem recomendação" in pt-BR) and options. PO answers update the matrix immediately. Challenge terms against the glossary, but record in CONTEXT.md only what the PO resolves. Completed when: PO question frontier is empty, or PO requests closing.

6. Synthesize. Write the plan following TEMPLATE.md: matrix, risk analysis, P1 scenarios in Gherkin with self-audit, automatability audit, regression impact based strictly on existing system documentation (without context, list impact questions for DEV), remaining questions by recipient, coverage verdict. Completed when: file exists at path defined by docs/agents/refinement.md with final disclaimer present.

7. Route open items. Open DEV questions in no-code mode and open PO questions that could not be answered: write one questionnaire per recipient following QUESTIONNAIRE.md in requirements-rigor, alongside the plan, and link files from open questions. Completed when: no open question remains without a recipient or questionnaire.

8. Report. Verdict, where the plan was published, count of executable P1 conditions, and what each questionnaire unblocks.

Final notice

⚠️ This output provides the analytical baseline for a test plan, not the final test plan. Decisions on coverage, prioritization, and effort belong to the QA team, with validation from PO (undefined behaviors) and Dev (architecture and layers).