Everything that blocks Build Ready and needs a person, in doc order. The questions screen, the TUI and the MCP server read it.
const url = 'https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/questions';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/questionsParameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”The ID of one spec doc.
Responses
Section titled “ Responses ”The questions.
Everything that blocks Build Ready and needs a person, from the run behind the verdict.
object
The run whose findings the list uses. Absent before the first review.
A MUST check of the run has no answer. Another review answers it, not the author.
The items in doc order. An item with no anchor comes first.
One thing that blocks Build Ready. material_gap is a build question with two options. blocking_thread is an open blocking thread. decision is a finding that needs a human answer with no options: a coverage gap, a send-back or a missing upstream link. finding is any other open MUST finding.
object
Stable across reviews for a material gap (its fork), else the finding or thread ID.
The one thing the person must decide or do, in words.
Why it blocks, in one or two sentences.
A range of text with context (SDD §8.8).
object
Byte offset of the quote in the file.
The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).
One failed check. The rail and the MCP tool get_findings read this one shape.
object
The last full review found this, and the full review before it did not. See Trend.
An AI finding of the last full review, which read an older version. Its section has not changed since.
The line of the file where the text of the finding starts, from 1, in the current version. 0 when the anchor is detached.
The line where the text of the finding ends.
Reword: the fix changes the words and no fact, so the bulk fix or an agent may fix the finding alone. answer: the fix needs a fact from the author.
For an answer finding, the question that the author must answer to fix it. It names the subject and asks only for the missing fact. A finding of the divergence stage has its build question here, and one of the grounding stage has its claim.
The run the finding belongs to. A carried finding belongs to the last full review.
A valid waiver covers this finding (REQ-074).
The reviewer gave no valid answer for this MUST check. A waiver cannot cover the finding. The next review asks for the check again, and only an answer clears it.
The check is in adoption mode, so it reports at INFO (REQ-133).
The overlay layer that shows this finding (SDD §13.2). No layer for other findings.
For a drifted code link, the commit URL a verification run reads to check the code still conforms.
For a coverage gap, the upstream trace ID it is about.
One conflict between a doc and a linked doc, as a coherence.contradiction finding names it. A waiver of that check binds to it, and excuses no other conflict in the section. On a coherence.downstream-request finding, it is the conflict as the downstream doc names it.
object
The slug of the linked doc.
The text of this doc that conflicts.
The text of the linked doc that it conflicts with.
The upstream request of a coherence.contradiction finding: the answer “The linked doc must change”. While it waits, the finding reads “Waiting on” the linked doc. A send-back ends it.
object
The slug of the linked doc that must change.
Why the linked doc must change.
Waiting while the linked doc must change; sent_back after the linked doc answered that this doc must change.
The finding counts in the verdict. A waiting finding blocks only when the profile sets coherence.upstream_pending to block.
The reason of the send-back.
For a missing upstream link whose target is a doc on GitHub that Speccy does not hold, the URL to add as a GitHub source.
The anchor in the bundle’s current version, re-anchored when the run read an older version.
object
Byte offset of the quote in the file.
The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).
The materiality judge’s decision on a MUST finding. A material gap is a place where a builder who cannot ask the author must guess, and two plausible guesses differ in the data model, an interface, security or what the user sees. It blocks Build Ready. A MUST finding with class none is advice. A MUST finding with no judgement blocks.
object
The consequence class.
The two answers a builder could pick. Empty for none.
The option that fits the rest of the doc better, 1 or 2. 0 for none.
The question that asks the author to choose.
Names the one fork the finding asks about. A “Not needed” answer binds to it.
The answer the author gave on the questions screen, while its patch waits or after the author accepted it.
The option the author picked for the answer, 1 or 2, or 0 for an answer in the author’s own words.
The author answered “Not needed”, with a reason. The waiver of the answer covers this finding.
object
For text, an Anchor. For a section, {heading_path}. For a finding, {finding_id, check_slug}. For a check, {check_slug}.
object
The handoff a builder opened this thread from (REQ-137).
The bundle version the builder took. 0 when no handoff opened it.
The waiver requests of this doc that wait for the caller’s decision.
object
Withdrawn is an approved Acknowledgement that a person took out of the sidecar.
The waiver policy (§9.1).
The approvals the policy needs.
Whether the caller can approve or reject it now.
Why the waiver is rejected. Only a rejected waiver has one.
The byte range of the waiver’s section in the current main doc. Absent when the section is gone.
object
An Acknowledgement of one upstream trace ID. On approval it goes in the sidecar under trace.
object
One conflict between a doc and a linked doc, as a coherence.contradiction finding names it. A waiver of that check binds to it, and excuses no other conflict in the section. On a coherence.downstream-request finding, it is the conflict as the downstream doc names it.
object
The slug of the linked doc.
The text of this doc that conflicts.
The text of the linked doc that it conflicts with.
What a verification waiver excuses. It never goes in the sidecar.
object
The code repo, or the folder, as the verification run names it.
The verification run the request came from. Empty for a request that named no run.
True for a standalone Acknowledgement. On approval it goes in the sidecar under standalone.
True for an upstream request, the answer “The linked doc must change”. On approval it goes in the sidecar under upstream_changes.
True for a send-back, the answer “The downstream doc must change” to a coherence.downstream-request finding.
True for the answer “Not needed” to one finding. The author gives it, and it needs no approval.
For a send-back, or a waiver of a coherence.downstream-request finding: the downstream doc. The approval writes to its sidecar, because Speccy writes nothing into the linked doc’s sidecar.
object
The bundle that holds the spec doc.
Who withdrew the Acknowledgement. Only a withdrawn one has it.
Why an ended waiver ended: an edit changed its section, a full review passed its whole-doc check, or the profile changed what the check asks. An upstream request ends when the linked doc sends it back, or when an edit removes a quote of its conflict.
True for a waiver of a whole-doc check. An edit does not end it. It ends when a full review passes the check, or when the profile changes what the check asks.
Example
{ "items": [ { "kind": "material_gap", "finding": { "fix_kind": "reword", "level": "MUST", "layer": "ambiguous", "upstream_change": { "state": "waiting" }, "material": { "class": "data_model" } }, "thread": { "anchor_kind": "text", "addressed_to": "humans", "status": "open" } } ], "waivers": [ { "status": "requested", "trace": { "status": "out_of_scope" }, "ended_because": "section_changed" } ]}default
Section titled “default”An error.
RFC 9457 problem details with a stable code.
object
A stable machine-readable error code.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example"}