Governing Quality Waivers

Governing Quality Waivers

Use this skill when something in the quality system is being switched off - or when you need to find out how much already has been.

Every repo accumulates skips. A test.skip from a sprint that ended, an eslint-disable-next-line nobody can explain, a continue-on-error: true added during an incident, a coverage threshold lowered to match reality. None were wrong at the time. All of them are now invisible, unowned, and permanent.

A waiver makes the same decision visible: same skip, but with a reason, an owner, and a date. That is the entire mechanism, and it is the difference between a considered trade-off and rot.

When to Use

• someone wants to bypass a quality gate for this change or this release
• a check is failing and the pragmatic answer is "not now"
• a repo has skip lists, disabled rules, or quarantined tests with no owners
• an audit, a handover, or a new lead asks what this project actually enforces
• a quality contract has SHOULD practices that will not be done this quarter
• a continue-on-error or a lowered threshold turns up in a diff

Operating Principles

• Skipping is allowed. Silent skipping is not. The goal is not zero waivers; it is zero unowned waivers.
• A waiver has four fields, always. What, why, who, until when. Missing any one makes it a skip wearing a nicer name.
• MUST is not waivable. A mandatory practice that cannot be met means the practice is wrong, the profile is wrong, or the work is not done. Those are three real answers; "waived" is not a fourth.
• Expiry is not optional and "never" is not a date. An unbounded waiver is a permanent lowering of the bar, and it should be recorded as a contract change instead.
• The owner is a person or a named team. "The team" owns nothing.
• The reason names the blocker, not the feeling. "Flaky" is not a reason. "Fails when the CI runner's clock skews past the token TTL; needs a fake clock, tracked in QA-431" is.
• An expired waiver is a finding. Not a warning, not a nag - a finding that appears every run until it is renewed with a fresh justification or removed.
• Renewal requires a new justification. Rubber-stamping the old reason is how a 90-day waiver becomes a three-year one.

Workflow

Phase 1: Classify the request

Before writing anything, establish what kind of skip this is:

Getting this classification right prevents the register from filling up with rows that were never waivers, which is what makes people stop reading it.

Phase 2: Write the entry

Use ./resources/waiver-register-template.md. Store the register where the contract lives - .qa/waivers.md, or the waivers: block of .qa/quality-contract.yaml.

- id: W-004
  scope: coverage-rigor
  paths: ['src/generated/**']
  reason: >-
    Generated OpenAPI clients. Tests would assert the generator's output, not our
    behaviour. Regenerated on every schema change; the schema itself is contract-tested.
  owner: '@maria'
  created: 2026-08-21
  expiry: 2026-12-01
  review_trigger: 'if we hand-edit anything under src/generated/'
  ticket: null

review_trigger is the field that earns its keep: an expiry catches time passing, a trigger catches the assumption breaking. A waiver justified by "this code is generated" should expire the moment someone edits it by hand.

Phase 3: Set the expiry honestly

The last row matters. A structural exception dressed as a waiver expires, gets renewed unread, and pollutes the register. If the bar has genuinely moved, move the contract and say so out loud.

Phase 4: Inventory the silent skips

The high-value pass, especially on an inherited repo. Work through ./resources/silent-skip-inventory.md: skipped and quarantined tests, .only leaks, disabled lint rules, @ts-expect-error and any escapes, continue-on-error and || true in CI, coverage ignores and excludes, lowered thresholds, raised retries, --no-verify habits, allowlisted secret-scan and audit findings.

For each finding, one of three outcomes - and no fourth:

1. Fix it - usually cheaper than the discussion about it
2. Waive it - with the four fields
3. Delete it - the skip protects code nobody needs

Report the count. "31 silent skips, 4 with any explanation" is the sentence that gets a team to act.