Ask for and approve a waiver
This guide shows you how to ask for a waiver, how to approve or reject one, and what to do when a waiver ends.
A waiver is an approved exception for one check in one section, with a reason. An approved waiver stops the finding from counting in the verdict. Speccy writes it to the sidecar of the doc, and the doc text does not change.
In the app, the control for a waiver is Ship it open. Use it when the gap is real, and the doc ships with it. When the finding does not apply to this doc, answer Not needed on the questions screen instead. Not needed closes at once and needs no approval.
Before you start
Section titled “Before you start”- The finding is a MUST or a SHOULD. An INFO finding never changes the verdict, so it takes no waiver.
- The finding is not “The reviewer gave no answer for this check”. Run the review again for that finding.
- The finding is not a coverage gap. A
trace.coveragefinding takes an answer instead. Close a coverage gap shows the three answers. - In hosted mode, you are a member of the workspace. A person in reviewer mode sees no findings and asks for no waiver.
Ask for a waiver
Section titled “Ask for a waiver”-
Open the spec doc, and open the Findings tab of the rail.
-
Under the finding, click Ship it open. The dialog Ship it open names the check and the section.
-
Write the reason: why the doc can ship with this gap. The reason needs at least 20 characters, so an approver can judge it.
-
In hosted mode, click Ask for approval. In local mode, click Ship it open.
In hosted mode, the request waits for approval under the profile’s waiver policy. In local mode, the waiver closes at once, because you are the approver. Speccy writes it to the sidecar.
The questions screen offers the same request. It lists each open MUST finding that blocks Build Ready and needs a person. On a finding item, click Ship it open, and fill in the same dialog. A material gap offers Ship it open as a choice next to its options, Other and Not needed. Pick it, and write the reason.
A waiver is for one check in one section. A failed rubric check can give several findings, one for each shortfall, and one waiver covers all of them there. What the waiver binds to depends on the check:
- A rubric check that names a section in the profile: that section with its subsections.
- A lint rule, or a check with
scope: section: the section of the finding. - A whole-doc check, which is a rubric check with no section: the check itself. The card reads “whole doc”.
- A check of another stage that reads the whole doc, such as
links.has-upstream: the whole doc text. The card reads “whole doc”. coherence.contradiction: the section of the finding and the one conflict it names. A new conflict in the same section needs its own waiver. A later review that finds the same conflict keeps its quotes, so the waiver still covers it.
Ask from the terminal
Section titled “Ask from the terminal”speccy waive asks for a waiver without the app. It uses the state of the folder, as the app does. When the app runs, the command sends its calls to the app.
-
Review the doc, and find the
idof the finding in the JSON output:Terminal window speccy review docs/sdd-payments.md --format jsonEach bundle in the output also has its
doc_idand itsbundle_id. -
Ask for the waiver, with the reason:
Terminal window speccy waive docs/sdd-payments.md 01a110a2-3aeb-719a-b706-5d03631f85a4 --reason "The card network sets this limit, and we cannot change it." -
Read the result. In local mode, you are the approver, so Speccy approves the waiver at once. An upstream request or a send-back still waits for approval. Add
--approveto approve it in the same step. -
List the waivers of the doc and their status:
Terminal window speccy waivers list docs/sdd-payments.md
A coding agent uses the MCP tools request_waiver, approve_waiver and list_waivers. The reason comes from you. The agent asks you for it, and it approves only when you tell it to.
Answer a conflict that only the linked doc can fix
Section titled “Answer a conflict that only the linked doc can fix”A coherence.contradiction finding is a conflict with a doc that this doc links to. When this doc is right, a waiver is the wrong answer: the conflict is not acceptable. Answer that the linked doc must change.
-
Under the conflict, click The linked doc must change.
-
Write the reason: why the linked doc is wrong. The author of the linked doc reads it. The reason needs at least 20 characters.
-
Click Ask. The request waits for approval under the waiver policy of
coherence.contradiction, as a waiver does.
After the approval, the finding reads Waiting on and the name of the linked doc. It does not block the verdict. The sidecar holds the request under upstream_changes. The linked doc gets the MUST finding coherence.downstream-request, which quotes both docs and gives your reason.
The author of the linked doc answers in one of three ways:
- An edit of the linked doc that removes its quote. The next reviews close the conflict on both docs.
- Ship it open on the
coherence.downstream-requestfinding. The waiver says the conflict is acceptable, and it closes the conflict on both docs. - The downstream doc must change on the
coherence.downstream-requestfinding, with a reason. After approval, the conflict blocks your doc again, and your finding shows that reason. Then edit your doc, or click Ship it open. A second upstream request of the same conflict is not possible.
From the terminal, add --upstream-change or --send-back to speccy waive:
speccy waive docs/sdd-payments.md 01a110a2-3aeb-719a-b706-5d03631f85a4 --upstream-change --reason "The shipped worker pays within 10 days, and support agreed."The MCP tool request_waiver takes upstream_change or send_back in the same way.
To keep a conflict blocking until the linked doc changes, set coherence.upstream_pending: block in the profile. Upstream requests and send-backs explains the flow.
Who approves
Section titled “Who approves”The profile’s waiver policy decides who approves. waivers.should names the policy for a SHOULD finding, and waivers.must for a MUST finding. A check can carry its own waiver, which wins.
| Policy | Who approves |
|---|---|
any_member |
Any member, the author too. |
non_author |
One member who is not an author of the bundle. |
n_approvals: N |
N different members who are not authors of the bundle. |
maintainer |
A maintainer of the profile, or an admin. |
forbidden |
Nobody. Speccy refuses Ship it open and Not needed for the check, and you fix the doc. |
The built-in PRD and SDD profiles use non_author for a SHOULD and maintainer for a MUST. Change a profile shows how to change them.
In local mode, you are the only person, and you have every role. Ship it open closes at once, so no request waits for you. This applies to verification waivers too.
An acknowledgement needs no approval in either mode. Another doc covers it, Out of scope and Mark it standalone close the finding at once. An upstream request and a send-back still wait for approval under the waiver policy.
Approve or reject a request
Section titled “Approve or reject a request”In hosted mode, an approver meets a request in four places:
- The Inbox holds a Waiver request item, with the check and the reason. A click opens the bundle on the finding.
- The next action in the control row reads “Decide the waiver of” and the check.
- The questions screen shows the request card at the top, under Waiting for your decision, with Approve and Reject.
- The findings rail puts the finding with the request at the top, with the request card under it.

-
Read the card. It shows the reason, the approvals so far against the policy, and the section. Decided on this section lists the waivers that people decided on the same section before.
-
Read the section in the preview. The reason alone does not support a decision.
-
Click Approve. Or click Reject, write a decision reason of at least 20 characters, and click Reject again. The card on the questions screen works in the same way.
-
When other requests wait for you on this bundle, click Next waiver under the card. The rail moves to the next request, and the control counts the requests that are left.
A decision reason tells the author what to change instead. An approval takes no reason: the request reason is the record.
When the policy cannot let you decide, the card says which role decides it. An author cannot approve a waiver of their own bundle under non_author or n_approvals.
What happens
Section titled “What happens”On approval. When the approvals reach the policy, Speccy writes the waiver to the sidecar, .speccy/decisions/<doc path>.yaml. The finding reads Waived, and it no longer counts in the verdict. The verdict counts the waivers it applied. With n_approvals, each approval before the last one only adds to the count.
waivers: - check: lint.sentence-length section: [Payment retries, Limits] reason: The retry table quotes the card network rule word for word. section_hash: sha256:3f1c9a7e2b8d4f60a1e5c7b9d2f4a6c8e0b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9 requested_by: priyaFor a folder that Speccy serves, the sidecar sits under the root of the folder, where git sees it. For a doc in a GitHub source, the approval writes the sidecar into a pull request.
When an approver rejects it. The request reads Rejected, with the decision reason. The person who asked gets a Waiver rejected item in their inbox, with the reason.
When a waiver ends
Section titled “When a waiver ends”A waiver of a section holds only while that section stays the same. Speccy records a hash of the section’s text with the request. Any edit of that text ends the waiver, and the check counts again. For a check that names a section, the text includes the subsections.
A waiver of a whole-doc check does not end on an edit. It ends in two cases:
- A full review passes the check, so nothing is left to excuse. When a later review fails the check again, the waiver becomes approved again. You do not ask again.
- The profile changes the
questionor thepass_whenof the check.
A waiver of links.has-upstream, or of another check that reads the whole doc outside the rubric stage, ends on any edit of the doc body.
-
Look under Waivers at the end of the findings rail. The ended waiver carries the status ended, and it says why it ended. For a changed section, it names the section that someone edited after the approval, and it asks you to run the review again.
-
Run the review again, so the check reads the new text. Lint checks read it on the save already.
-
When the finding is still there, click Ask for it again. The dialog opens with the old reason in the field. Change it or keep it, and click Ask.
The authors of the bundle get a Waiver ended item in their inbox, because an edit often ends a waiver without the author seeing it. The old entry stays in the sidecar until a later approval replaces it. Speccy ignores it while its hash does not match the section or the check.
Related
Section titled “Related”- Waivers and the sidecar: why a waiver lives beside the doc and not in it.
- Sidecar format: every key of the sidecar.
- Reply commands:
/speccy waiveasks for a waiver in a pull request. - Close a coverage gap: the acknowledgement, which closes at once with no approval.