Reviewing and refining

---
title: Reviewing and refining
description: Review a sealed revision, decide its findings and approve it explicitly.
---

## Review is its own run

Four kinds of document carry a review-and-refine loop: the PRD, the RFC, the
Feature Specification and the Feature-Slice Specification. `review-prd` and
`review-rfc` are pipeline operations, and the pipeline does not advance past
them. `review-feature` and `review-feature-slice` sit beside the pipeline: the
specification is already sealed, so reviewing it advances nothing.

Every review reads the sealed bytes of the one revision it names, on the same
independence terms: a run distinct from the author's, read-only access to the
subject and no inherited author reasoning. Each review issues one of five
verdicts: `PASS`, `PASS_WITH_ADVISORIES`, `REVISE`, `PROVISIONAL` or `BLOCKED`.

## A session decides; it never edits

`refine-prd`, `refine-rfc`, `refine-feature` and `refine-feature-slice` each run
a decision session over a sealed review. The owner decides each finding, and the
decisions are recorded in a separate overlay revision that the next review reads
alongside the document. The subject's bytes do not change, and a disputed
finding stays standing until the next review adjudicates it.

A session admits a subject on its current state, not its origin. A document
authored by Specgent, one imported from elsewhere and one compiled by an earlier
session are admitted on the same terms: the bound revision must be the subject's
latest, and a sealed review must be bound to it by content hash with a verdict
the policy admits.

## The loop

Compiling a session seals the next revision of the same subject, and that
revision needs its own sealed review. Each pass adds exactly one revision;
nothing earlier is amended, and every revision stays readable.

Nothing decides when the loop is done. There is no convergence threshold and no
round limit: the loop runs until the operator stops invoking it. A passing
verdict is still not acceptance, and a compiled revision stays unaccepted until
someone approves it.

## Choosing a lane

Re-running the operation that authored a document fits a change upstream of it,
such as a change to the idea, the research or the requirements, because the
operation rebuilds the whole document from the corrected inputs. A refine session fits a response to
review findings on the document as it stands. A document imported from outside
Specgent has no authoring run to re-enter, so for it the session is the only
lane.

## Approvals

Sealing is not acceptance. An approval is a separate record naming an authority,
a revision and an approval identifier, and nothing derives from a sealed
revision that has not been approved. Any user may invoke any operation; what is
bound to a role is approval.

| Document type        | Assurance basis                     | Approved by                              |
| -------------------- | ----------------------------------- | ---------------------------------------- |
| `workspace-context`  | phase validation and owner approval | product owner                            |
| `research-brief`     | phase validation and owner approval | product manager                          |
| `prd`                | independent review                  | product owner                            |
| `rfc`                | independent review                  | technical lead                           |
| `epic-portfolio`     | phase validation and owner approval | product owner                            |
| `feature-backlog`    | phase validation and owner approval | product owner and technical lead         |
| `feature-spec`       | phase validation and owner approval | technical lead                           |
| `feature-slice-set`  | phase validation and owner approval | technical lead, or a delegated developer |
| `feature-slice-spec` | phase validation and owner approval | technical lead, or a delegated developer |

Organization policy may strengthen this floor but not remove the review:
independent review of a PRD or an RFC is mandatory and cannot be skipped. A PRD
or RFC whose review came back `REVISE` or `BLOCKED` can still be accepted, but
only by the role the policy names, citing waivers that are issued by roles
owning their category and that together cover every open blocking finding. A
`PROVISIONAL` verdict is never waived; the review is re-run instead.

For a Feature Specification or a Slice Specification, a review is evidence that
an approval may cite, never a gate it has to break. The acceptance records
which review round the approver read and what was still open in it.