Reviewer workflow
This contract owns delegated review and the reviewer-to-PM handoff. PM mode workflows own orchestration and persistence.
Rule ownership
| Source | Owns |
|---|---|
| Rubric router | Rubric selection by file extension |
| Routed rubric | Review lenses, rating, MDX expectations, and exceptions |
| Review context | Permitted context, validation, dispositions, and limits |
| Review reporting | Evidence, editorial context, completion, and report order |
| This workflow | Inputs, isolation, snapshot, and PM acceptance |
Procedure
- Read this workflow and the assigned brief.
- Read the rubric at the path the brief supplies. Use the router only when the brief has none.
- Read the assigned document in full.
- Read the supplied effective review context, when present.
- Read the editorial guidance required by Review reporting.
- Examine every applicable review lens and form evidence-backed findings.
- Assess each applicable lens as Strong, Mixed, or Weak.
- Assign the holistic quality rating from the rubric’s core-task boundary.
- Apply Review reporting’s completion checks, write the report to the assigned scratch path, and return only that path to the PM.
Do not delegate the review or adjust a rating towards an expected result.
Inputs
| Input | Reviewer action |
|---|---|
| Assigned document | Review this document only. The PM supplies its project-root-relative path; use that path, never a file-system path, in the report heading. |
| Routed rubric path | Read it and apply all relevant lens, rating, and exception rules. |
| Mechanical-validation result | Report separately. Do not turn it into a quality finding without a reader consequence. |
| Source hash | Return the exact supplied sha256: value in the snapshot. |
| Snapshot timestamp | Echo the PM-supplied timestamp exactly (Review-only startedAt; in Iterate, the UTC time the PM captured for this review); never estimate the current time. |
| Editorial guidance | Use it to interpret style and support edits, not as another lens. |
| Optional effective review-context path and hash | Read only this frozen file and account for every item. |
| Review-only review ID | Return it in supporting metadata. |
| Assigned scratch report path | Write the complete report here, and nowhere else. Return only this path. |
Isolation
Do not read or use:
- another version of the document;
- writer handoffs, notes, or explanations outside effective review context;
- research files;
- content-quality ledgers;
- previous reports, ratings, or run manifests;
- sibling Review-only reports.
Required editorial guidance, the PM’s mechanical-validation result, and frozen effective context are permitted. Ignore prohibited material supplied accidentally and disclose it.
The reviewer writes exactly one file: the scratch report at the path the brief assigns. It never writes the document, another path, or a durable run output, and never reads another reviewer’s scratch report. The brief is the only limit on its writes, so the PM re-hashes the source after every review (reviewer brief).
Draft scaffolding
Apply the MDX rubric’s draft exceptions only to cache drafts/ and
ak-<document-key>-best-draft/ files. Never apply them to a live page or non-MDX file.
Report and snapshot
Follow Review reporting and start with the rating. Use F1, F2, and so on for substantive
findings. Identify all applicable lenses on each finding, show the three-column
Lens | Assessment | Rationale table, and keep optional polish separate. Give every applicable
lens one short rationale: name concrete successful guidance for Strong, and cite the relevant
finding ID or IDs for Mixed or Weak.
Include exactly one snapshot JSON block:
The snapshot is the reviewer’s own handoff. It reports the model the reviewer ran with and
omits sourcePath and reviewProvenance: the PM adds those, and lifts model into
reviewProvenance.reviews[], when it persists
content-quality.json. The persisted shape is defined by
content-quality.schema.json.
Do not include score, criteria, issue counts, complexity, or Coverage. General-copy reviews use
the same snapshot schema but omit structure from lensAssessments. Rationales remain in the
narrative report and do not enter the snapshot.
When review context exists, include every item ID, its disposition, and effect in Supporting detail,
and return the supplied context hash. Report each matching known-deviation item under Known items
as Review context describes: it never enters the findings, the lens
assessments, or the rating, and its ID is never an F-number.
PM acceptance
The reviewer brief owns what the PM supplies and its acceptance checks. Every Mixed or Weak rationale must cite at least one substantive finding ID.
Persistence
The scratch report is a disposable handoff, not the final artefact. The PM checks it and copies the
accepted report: an Iterate report becomes draft-<nnn>-review-report.md and a Review-only report becomes
reviewer-report-<n>.md, both in the cache. See the selected PM
mode for exact paths and manifest rules.