Skip to content

Everything that blocks Build Ready and needs a person, in doc order. The questions screen, the TUI and the MCP server read it.

GET
/docs/{docId}/questions
curl --request GET \
--url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/questions
docId
required
string format: uuid

The ID of one spec doc.

The questions.

Media typeapplication/json

Everything that blocks Build Ready and needs a person, from the run behind the verdict.

object
run_id

The run whose findings the list uses. Absent before the first review.

string format: uuid
recheck
required

A MUST check of the run has no answer. Another review answers it, not the author.

boolean
items
required

The items in doc order. An item with no anchor comes first.

Array<object>

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
key
required

Stable across reviews for a material gap (its fork), else the finding or thread ID.

string
kind
required
string
Allowed values: material_gap blocking_thread decision finding
ask
required

The one thing the person must decide or do, in words.

string
context

Why it blocks, in one or two sentences.

string
anchor

A range of text with context (SDD §8.8).

object
file
required
string
heading_path
required
Array<string>
quote
required
string
prefix
required
string
suffix
required
string
start
required

Byte offset of the quote in the file.

integer
end
required
integer
detached

The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).

boolean
finding

One failed check. The rail and the MCP tool get_findings read this one shape.

object
new

The last full review found this, and the full review before it did not. See Trend.

boolean
carried

An AI finding of the last full review, which read an older version. Its section has not changed since.

boolean
line
required

The line of the file where the text of the finding starts, from 1, in the current version. 0 when the anchor is detached.

integer
end_line
required

The line where the text of the finding ends.

integer
fix_kind
required

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.

string
Allowed values: reword answer
question

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.

string
run_id
required

The run the finding belongs to. A carried finding belongs to the last full review.

string format: uuid
waived
required

A valid waiver covers this finding (REQ-074).

boolean
unanswered

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.

boolean
id
required
string format: uuid
check_slug
required
string
level
required
string
Allowed values: MUST SHOULD INFO
stage
required
string
relaxed
required

The check is in adoption mode, so it reports at INFO (REQ-133).

boolean
message
required
string
fix
string
layer

The overlay layer that shows this finding (SDD §13.2). No layer for other findings.

string
Allowed values: ambiguous unverified contradicted risk slop
verify_target

For a drifted code link, the commit URL a verification run reads to check the code still conforms.

string
trace_id

For a coverage gap, the upstream trace ID it is about.

string
conflict

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
with
required

The slug of the linked doc.

string
quote
required

The text of this doc that conflicts.

string
with_quote
required

The text of the linked doc that it conflicts with.

string
upstream_change

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
upstream
required

The slug of the linked doc that must change.

string
upstream_title
string
reason
required

Why the linked doc must change.

string
requested_by
string
state
required

Waiting while the linked doc must change; sent_back after the linked doc answered that this doc must change.

string
Allowed values: waiting sent_back
blocks
required

The finding counts in the verdict. A waiting finding blocks only when the profile sets coherence.upstream_pending to block.

boolean
sent_back_reason

The reason of the send-back.

string
sent_back_by
string
source_url

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.

string
anchor
required

The anchor in the bundle’s current version, re-anchored when the run read an older version.

object
file
required
string
heading_path
required
Array<string>
quote
required
string
prefix
required
string
suffix
required
string
start
required

Byte offset of the quote in the file.

integer
end
required
integer
detached

The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).

boolean
material

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
class
required

The consequence class.

string
Allowed values: data_model interface security user_visible none
options

The two answers a builder could pick. Empty for none.

Array<string>
pick

The option that fits the rest of the doc better, 1 or 2. 0 for none.

integer
question

The question that asks the author to choose.

string
fork

Names the one fork the finding asks about. A “Not needed” answer binds to it.

string
answer

The answer the author gave on the questions screen, while its patch waits or after the author accepted it.

string
option

The option the author picked for the answer, 1 or 2, or 0 for an answer in the author’s own words.

integer
not_needed

The author answered “Not needed”, with a reason. The waiver of the answer covers this finding.

boolean
thread
object
id
required
string format: uuid
doc_id
string format: uuid
profile_key
string
anchor_kind
required
string
Allowed values: text section finding check
anchor
required

For text, an Anchor. For a section, {heading_path}. For a finding, {finding_id, check_slug}. For a check, {check_slug}.

object
key
additional properties
any
addressed_to
required
string
Allowed values: humans ai
title
required
string
handoff_id

The handoff a builder opened this thread from (REQ-137).

string format: uuid
handoff_version

The bundle version the builder took. 0 when no handoff opened it.

integer format: int64
blocking
required
boolean
status
required
string
Allowed values: open resolved
created_by
required
string
created_at
required
string format: date-time
last_message_at
required
string format: date-time
message_count
required
integer
waivers
required

The waiver requests of this doc that wait for the caller’s decision.

Array<object>
object
id
required
string format: uuid
doc_id
required
string format: uuid
check_slug
required
string
level
required
string
section
required
Array<string>
reason
required
string
status
required

Withdrawn is an approved Acknowledgement that a person took out of the sidecar.

string
Allowed values: requested approved rejected invalidated withdrawn
requested_by
required
string
approvals
required
Array<string>
policy
required

The waiver policy (§9.1).

string
needed
required

The approvals the policy needs.

integer
can_approve
required

Whether the caller can approve or reject it now.

boolean
decision_reason

Why the waiver is rejected. Only a rejected waiver has one.

string
section_range

The byte range of the waiver’s section in the current main doc. Absent when the section is gone.

object
start
required
integer
end
required
integer
trace

An Acknowledgement of one upstream trace ID. On approval it goes in the sidecar under trace.

object
id
required
string
status
required
string
Allowed values: out_of_scope covered_by
target
string
conflict

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
with
required

The slug of the linked doc.

string
quote
required

The text of this doc that conflicts.

string
with_quote
required

The text of the linked doc that it conflicts with.

string
verification

What a verification waiver excuses. It never goes in the sidecar.

object
trace_id
required
string
repo
required

The code repo, or the folder, as the verification run names it.

string
run_id

The verification run the request came from. Empty for a request that named no run.

string format: uuid
standalone

True for a standalone Acknowledgement. On approval it goes in the sidecar under standalone.

boolean
upstream_change

True for an upstream request, the answer “The linked doc must change”. On approval it goes in the sidecar under upstream_changes.

boolean
send_back

True for a send-back, the answer “The downstream doc must change” to a coherence.downstream-request finding.

boolean
not_needed

True for the answer “Not needed” to one finding. The author gives it, and it needs no approval.

boolean
downstream

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
id
required
string format: uuid
bundle_id
required

The bundle that holds the spec doc.

string format: uuid
slug
required
string
title
required
string
profile_key
required
string
withdrawn_by

Who withdrew the Acknowledgement. Only a withdrawn one has it.

string
ended_because

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.

string
Allowed values: section_changed check_passed check_changed sent_back conflict_closed
whole_doc

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.

boolean
created_at
required
string format: date-time
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"
}
]
}

An error.

Media typeapplication/problem+json

RFC 9457 problem details with a stable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
code
required

A stable machine-readable error code.

string
Examplegenerated
{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example",
"code": "example"
}