---
canonicalUrl: "https://www.hoalee.net/specgent/docs/guide/review-and-refine"
title: "Reviewing and refining"
description: "Review a sealed revision, decide its findings and approve it explicitly."
kind: "doc"
language: "en"
---

# Reviewing and refining

## 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\.