api-aqa-flow-test-correction

<api_aqa_flow_test_correction>

<description_and_purpose> Fix identified API test failures based on the Phase 6 execution report. Prepares proposed changes, requires explicit user approval before applying, then applies them incrementally with lint checks and hands re-testing back to the user. </description_and_purpose>

<workflow_context>

• Phase 7 of 8 in api-aqa-flow
• Input: execution report from Phase 6 (plans/api-aqa-{IDENTIFIER}/execution-report.md; resolve {IDENTIFIER} from agents/TEMP/<FEATURE>/api-aqa-state.md)
• Output: corrected test code, ready for re-testing
• Prerequisite: Phase 6 complete
• HITL: explicit user approval required before applying any change (a domain-specific specialization of hitl)
• In-scope file set (single SSoT): test files + shared test-utility files only. Writes outside this set are refused and escalated.
• Required skills: qa-knowledge (correction mode — proposed-change block + approval gate + correction discipline), qa-structure (run paths + api-aqa-state.md)
• Recommended skills: coding (authors the proposed/applied edits), debugging (root-cause alignment), hitl (explicit approval) </workflow_context>

<correction_contract> The phase OWNS the iteration cap and the escalation contract. The proposed-change approval block is qa-knowledge's shared proposed-change template (the skill loads its own asset at step 7.1) — present one block per change BEFORE any write. Flow parameters for the template: change-type enum = assertion-fix | auth-fix | data-setup | request-shape | wait-strategy | other; root-cause reference = execution-report entry id (e.g. ERR-3); state file = agents/TEMP/<FEATURE>/api-aqa-state.md; on retry-cap, loop back to Phase 6. Verified by <validation_checklist> independent of skill internals. </correction_contract>

<phase_steps>

1. Prepare proposed corrections (step 7.1 — preparation-only)
2. Present changes for approval (step 7.2)
3. Apply approved changes (step 7.3)
4. Update state (step 7.4) </phase_steps>

<execute_corrections step="7.1" subagent="engineer" role="Test correction engineer"> Preparation-only: nothing in this block modifies workspace files until step 7.3 after explicit approval in 7.2. "Preparation-only" means proposed edits paired with before/after evidence — no writes to test or product source files.

1. USE SKILL qa-structure to resolve run paths/api-aqa-state.md. USE SKILL debugging to align each proposed edit with a confirmed Phase 6 root cause (no symptom-only fixes).
2. USE SKILL qa-knowledge (correction mode) and USE SKILL coding to author each proposed edit (preparation-only — before/after evidence, no writes). The present → approve → apply discipline is owned by this phase: <present_for_approval> (7.2) + <apply_changes> (7.3). Bindings grouped by owner: proposed-change source = plans/api-aqa-{IDENTIFIER}/execution-report.md; proposed-change template + state file + iteration cap + loop target = <correction_contract>; in-scope file set = <workflow_context>; approval-token set = step 7.2.
3. Produce one Proposed Change record per fix per the <correction_contract> template, citing the matching execution-report entry id (e.g. ERR-3). Do NOT apply anything yet. </execute_corrections>

<present_for_approval step="7.2">

1. Present all proposed changes with before/after code per the template.
2. Approval gate: USE SKILL qa-knowledge to run its shared approval gate; USE SKILL hitl. Approval = an exact token from the closed list approved / approve / yes (case-insensitive), scoped to the named changes — no "or equivalent" / "or similar" phrasing extends it. Comments, questions, suggestions, edits, and partial review are REVIEW, not approval. Partial approval applies only to named changes/hunks; re-present changed proposals (re-present step = 7.2); full rejection returns to Phase 6. </present_for_approval>

<apply_changes step="7.3">

1. Apply approved changes one at a time (or in named approved batches).
2. Validate linting/format after each change. On lint failure: revert that change (never leave the file broken), re-prepare a corrected version, and re-present that single change via <present_for_approval>.
3. Verify each applied change addresses its root cause by cross-referencing it to the matching entry in plans/api-aqa-{IDENTIFIER}/execution-report.md (cite the entry id, e.g. ERR-3). On root-cause mismatch: return to step 7.1 with a note in agents/TEMP/<FEATURE>/api-aqa-state.md; do not leave unmapped changes applied.
4. Max retries: apply the <correction_contract> iteration cap — on the 3rd failed cycle for the same change, stop, record Phase 7 blocked: in-phase apply retry cap reached in api-aqa-state.md, escalate to the user. </apply_changes>