# Issue-To-Test Policy

## Purpose

This document tells agents and maintainers what to do after fixing an issue so
the repository accumulates durable regression protection instead of relying only
on memory.

This is a separate workflow from bug fixing itself.

Bug fixing answers:

- what is broken?
- how do we repair it?

Regression follow-up answers:

- how do we make sure future work does not break this again?

## Mandatory Classification After High-Risk Fixes

After a high-risk issue is fixed, the author must classify the repair against
the regression tiers in `docs/test-infra/regression-strategy.md`.

Minimum questions:

1. Should this repair add or update a fast API regression?
2. Should this repair add or update a UI/runtime regression?
3. Does this repair reveal a scenario that should exist, even if not implemented now?
4. If no regression asset is added immediately, where is the debt recorded?

## What Counts As High-Risk

Treat the following issue classes as high-risk by default:

- user-visible business behavior fixes
- metadata-driven rendering or describe-driven behavior fixes
- permissions, auth, scope, or security fixes
- setup/bootstrap/control-plane fixes
- flow / validation / formula / approval fixes
- cross-object workflow fixes
- data loss, wrong default, wrong auto-population, wrong status, wrong linkage

## Default Outcomes

### Outcome A: Add fast API coverage now

Use when:

- the repaired invariant is narrow
- it can be proven with API calls and readback
- it belongs naturally in CI

Typical artifact:

- a new or updated file under `tests/e2e-api/cases/**`

### Outcome B: Add UI/runtime coverage now

Use when:

- the repaired behavior is browser-visible
- persistence/readback in the UI is the real acceptance criterion
- metadata-driven rendering is part of the fix

Typical artifact:

- Playwright coverage
- documented runtime inspection flow
- scenario extension when it is a multi-step journey

### Outcome C: Record debt in the backlog

Use when:

- the right regression asset is clear
- but the current PR or issue scope should not implement it yet

Required action:

- add or update the appropriate item in:
  - `docs/test-infra/api-regression-backlog-2026-04-23.md`, or
  - `docs/test-infra/ui-regression-backlog-2026-04-23.md`

The backlog entry should name:

- the protected behavior
- the risk
- the preferred regression tier
- any known issue or source reference

## Pull Request Expectations

When a PR fixes a high-risk issue, it should explicitly state one of:

- regression asset added
- existing regression asset updated
- regression backlog item added
- explicit exemption with reason

Silence is not a valid default for high-risk fixes.

## Reviewer Expectations

Reviewers should ask for regression follow-up when:

- the fix changes observable business behavior
- the fix modifies a known fragile area
- the fix addresses a bug that has already reoccurred once
- the fix repairs a cross-object or setup-sensitive path

## Relationship To Existing E2E Case Policy

This policy does not replace `.agent/skills/e2e-test-policy/SKILL.md`.

Instead:

- the E2E case policy governs mandatory fast API cases for qualifying CRUD changes
- this document governs the broader regression follow-up discipline for all
  high-risk fixes, including UI/runtime and scenario backlog work