Clarify code review vs QA testing workflow and improve review-state ergonomics

[Aditya-Chowdhry]

Summary

While using Relay to manage a multi-card QA pass, the workflow exposed confusion between the review and testing stages. The tool worked well as an audit trail, but the semantics around code review, QA review, testing, and final approval were ambiguous enough that it was easy to say a card was approved when it had only been approved to enter testing.

Observed confusion

Current flow looked like:

in_progress -> review -> testing -> done

In practice:

• review was used as a QA/Product review gate for implementation quality.
• Moving from review to testing required a --human-summary, which implies review is not final QA/testing approval.
• Notes saying approved in review were ambiguous: approved for testing, not approved as final product acceptance.
• Cards in testing still needed a separate tester/UAT signoff, but the previous review notes already sounded final.

This creates a real risk that teams treat testing as done or skip the separate QA/testing stage.

Suggested workflow model

Rename or clarify the states so the gates are explicit:

in_progress -> code_review -> qa_testing -> done

Suggested semantics:

• code_review: engineering/code correctness gate.

  • Checks implementation, tests, migrations, builds, regressions.
  • Note language: Code review approved or Code review changes requested.
  • Move target: qa_testing.

• qa_testing: product/integration behavior gate.

  • Validates user scenarios from the card/design doc end to end.
  • Note language: QA testing approved or QA testing failed.
  • Move target: done or back to in_progress.

• done: only after QA testing passes.

If renaming states is too disruptive, Relay could keep the existing state names but enforce stage-specific note templates and UI/CLI copy:

• review = code review
• testing = QA/UAT testing

CLI / workflow improvements

1. Require or strongly encourage stage-prefixed notes:

   • ## Code review - approved
   • ## QA testing - approved
   • Avoid generic approved notes without a stage.

2. Show transition requirements before a move command fails.

   • Example: moving to testing requires --human-summary; show that in relay move --help and/or dry-run output.

3. Add first-class summary fields instead of overloading notes:

   • code_review_summary
   • qa_test_summary
   • validation_evidence

4. Improve PR/head metadata reliability before a card can enter review.

   • Several cards had stale commit hashes or blank PR URLs.
   • Consider requiring prUrl and current head SHA before review, or warning loudly when they are stale.

5. Add a native watch/filter mode for review operations:

relay watch --status review --project "Routines Backend P2"

Manual polling with relay card list --status review --json | jq ... worked, but this should be a first-class workflow.

6. Add a compact list output for polling/review dashboards:

relay card list --status review --fields id,title,projectName,featureName,assignedAgent,commitSha,prUrl,updatedAt

Why this matters

For a multi-card feature, the distinction between code review approval and QA testing approval matters. Relay already has the lifecycle states to support this, but the current names and note language make it easy to blur the gates. Tightening the semantics would make the board safer for final acceptance workflows.

[Aditya-Chowdhry]

Maintainer triage after reviewing this workflow feedback.

Decision:

• The feedback is valid: review vs testing can be misunderstood when notes say "approved" without naming the gate.
• I am not renaming persisted statuses to code_review / qa_testing right now. That would force migration and compatibility churn for a semantic/copy problem.
• The product decision is to keep internal statuses stable and make the semantics explicit: review = code review, testing = QA/UAT. A card is not accepted as done until it passes testing and admin marks it done.

Accepted and fixed in 0b68f1f / v0.1.2:

• README now defines review as code review and testing as QA/UAT.
• CLI help now says reviewer is code-review only and tester is QA/UAT only.

Already partly addressed:

• human_review_summary is now required when moving into review or testing, which reduces the risk of vague "approved" handoffs.

Deferred:

• relay card transitions <id> / dry-run transition discovery is valid CLI ergonomics work and should be a separate issue.
• First-class code_review_summary / qa_test_summary layers may be useful later, but for now human_review_summary, implementation_notes, and validation_evidence cover the handoff surfaces without adding more layer types.
• Requiring fresh prUrl / head SHA before review is valid but should be separate because it needs a clear stale-SHA policy.

Validation: npm test passes, 35/35.