Feature QA Loop

Run a tight human-in-the-loop QA cycle for one feature. Keep the user focused on a single action while maintaining the deeper test plan, evidence trail, and engineering loop yourself.

Start the session

Ask for the feature only if the user has not named it. Resolve the target environment and current deployed version from context or read-only inspection. Inspect relevant product docs, code, fixtures, and existing QA instructions before choosing the first action.

Establish the mutation policy from the user's explicit wording:

• analysis-only: investigate and record; do not edit code, commit, push, deploy, or change production data.
• fix blockers: implement and verify confirmed blockers. Commit or push only when the user explicitly authorizes those actions for this session. Skill invocation alone never grants write or production authority.

Do not make the user review the whole test plan. Maintain it privately and reveal one step at a time.

One-step contract

Every manual-testing turn must contain exactly one action for the user. State:

1. The single action to perform.
2. The exact visible result expected.

Keep it brief and easy to scan. Do not include later steps, optional branches, multiple actions hidden in one bullet, or a full checklist. Wait for the user's result before advancing.

Read-only checks the assistant can perform—repository inspection, logs, database reads, deployment status, or screenshot analysis—do not count as extra user steps. Perform them when they remove guesswork.

Process each result

Classify the result internally as one of:

• pass;
• observation or UX confusion;
• suggestion / requested requirement;
• non-blocking defect;
• blocking defect;
• inconclusive.

Record it before moving on. Clearly distinguish user reported from confirmed by evidence. Do not turn an apparent symptom into a confirmed bug until logs, stored state, code behavior, or a reproducible check supports it. For documents, use stable evidence such as content, byte size, checksum, attachment ID, and stored classification when filenames can be lost or rewritten.

Then respond with the next single step. If the result is inconclusive, the next step should isolate the uncertainty rather than advance the flow.

Session notes

Reuse an existing QA session note when one exists. Otherwise create a workspace-local note under tmp/qa-sessions/<date>-<feature>.md unless the user specifies a durable tracked location.

Maintain these sections as the session evolves:

• feature, environment, start date, and deployed revision;
• chronological observations with expected versus observed behavior;
• confirmed bugs;
• user-requested requirements and suggestions;
• fixes, commits, CI runs, and deployments;
• untested cases and why they remain untested;
• the exact step from which testing should resume.

When the user says to "note", "record", or "add" something, update the note immediately. At the end of the session, give a compact bug/requirement summary and a link to the note.

Handle a blocker

First diagnose the root cause using the least invasive evidence available. Do not bypass the failed step or silently mutate production data.

When blocker fixes are authorized:

1. Inspect the worktree and preserve unrelated user changes.
2. Add or update a regression test that reproduces the failure when practical.
3. Implement the smallest root-cause fix.
4. Run focused checks, then the relevant CI-equivalent checks proportional to risk.
5. Commit only files belonging to the fix.
6. Push to main only when direct-main push was explicitly authorized. Never force-push.
7. Monitor CI to completion. If the environment auto-deploys after CI, monitor that deployment and verify the deployed revision and service health read-only.
8. Return to the same failed QA step. Do not advance until it passes.

One confirmed root cause should produce at most one direct-main push. If the same step remains blocked after two separately verified production fixes, stop before another production mutation, summarize the evidence, and ask for direction.

Real-world timing and production limits

Do not alter a production system clock. For flows requiring days to pass, test the immediately reachable stages and record the time-gated stages as untested. Use backdated test data, a clock abstraction, a non-production environment, or a controlled scheduler invocation only when the user explicitly authorizes that method and scope.

Production inspection is read-only unless the user separately authorizes a specific mutation. Never use real client data for fixture creation or destructive tests.

Finish or pause

Continue until the feature's intended flow passes, the user pauses/stops, or progress requires new authority or an external state change. On pause, record the exact resume point and give only the most useful next action.