Skip to content

ADR-0014: Introduce Ready for UAT for UI/UX Impacting Linear Issues

  • Status: Accepted
  • Date: 2026-05-11
  • Owners: @team/test, @team/uat
  • Related: ADR-0001

Context

Some Linear issues require explicit validation by UAT stakeholders before they can safely proceed toward production. This is especially important for issues that affect the user interface, user experience, customer-facing behavior, or visible content such as titles and descriptions.

The existing flow from Ready to Test (Prep) to production readiness does not always make this UAT dependency explicit. As a result, issues that require stakeholder validation may progress without a clear handoff point, or may remain blocked without sufficient visibility for release coordination.

This decision defines when the Ready for UAT state must be used and clarifies the responsibilities of the Test Team and UAT stakeholders during that stage.

Decision

Linear issues with UI/UX impact must be moved to Ready for UAT after Ready to Test (Prep) when they require UAT-side validation. This applies to feature work, improvements, title or description changes, and similar customer-visible changes or enhancements.

After UAT validation:

  • If the issue is approved by UAT, it will be moved to Ready for Production.
  • If UAT identifies a blocking problem, it will be moved to Testing Failed.

The Test Team may update the issue state after receiving UAT approval or rejection. This state transition is not mandatory for every issue. The Test Team is responsible for determining which issues require the Ready for UAT step based on the nature and impact of the change.

Because issues remaining in Ready for UAT, Ready for Production, or Testing Failed may affect release readiness, the Test Team is responsible for coordinating with UAT stakeholders and ensuring that issue status remains current.

Options Considered

Option A - Continue without a dedicated UAT state

  • Pros: No workflow change is required; fewer status transitions for simple issues.
  • Cons: UAT validation remains implicit, making release impact and ownership harder to track.
  • Decision: Rejected because UI/UX-impacting work needs a visible and auditable UAT handoff.

Option B - Require UAT for every issue

  • Pros: Creates a uniform workflow for all issues.
  • Cons: Adds unnecessary process overhead for issues that do not require stakeholder validation.
  • Decision: Rejected because the additional step is only valuable for specific issue types.

Option C - Use Ready for UAT selectively for UI/UX-impacting issues

  • Pros: Makes UAT dependency explicit where needed while avoiding unnecessary workflow overhead for unrelated issues.
  • Cons: Requires the Test Team to actively classify which issues need UAT validation.
  • Decision: Accepted.

Consequences

Positive

  • UAT validation becomes visible in Linear for customer-facing changes.
  • Release coordination improves because issues requiring UAT are easier to identify and follow up.
  • The Test Team has clear ownership of deciding when the UAT state is required.
  • Approved UAT outcomes can be reflected directly in the issue state.

Negative / Tradeoffs

  • The Test Team must consistently identify issues that require UAT validation.
  • Issues may remain in UAT-related states and affect release readiness if stakeholder feedback is delayed.
  • Additional coordination is required between the Test Team and UAT stakeholders.

Follow-ups

  1. Communicate the new state usage rule to the Test Team and UAT stakeholders.
  2. Update Linear workflow documentation and any release tracking views if needed.
  3. Review active UI/UX-impacting issues and move them to Ready for UAT where appropriate.
  • Supersedes / Superseded by: None