---
name: ssp-review-standards
description: Reviewer discipline for the SSP write pipeline — two-tier severity model (BLOCKER / AUTO-FIX), internal review loop (review → auto-fix → re-review until clean), halt-on-BLOCKER policy, full-plan review scope (narratives + structural fields), outer user-edit loop (final draft → user feedback → agents update → re-render → repeat until user approves), Reviewer Notes summary, sidecar audit log. Finding catalogs, loop procedures, and scope checklists live in reference-docs/ssp-review-procedures.md. Load when running or composing the review phase of /ssp-ingest.
---

# ssp-review-standards — Reviewer discipline for the SSP write pipeline

## References

| Reference | Type | Location | When to Use |
|---|---|---|---|
| `ssp-brand-voice` | Skill | `plugins/grcitsm-analyst/skills/ssp-brand-voice/` | Voice / format / preserve rules the reviewer applies |
| `ssp` | Skill | `plugins/grcitsm-analyst/skills/ssp/` | SSP asset workflow primer (Framework CF two-pass referenced in BLOCKER rules) |
| `ssp-ingest` | Skill | `plugins/grcitsm-analyst/skills/ssp-ingest/` | The pipeline this review fits into |
| `halo-ssp-asset-model` | Skill | `plugins/grcitsm-analyst/skills/halo-ssp-asset-model/` | What the fields ARE |
| `halo-ssp-asset-write-conventions` | Skill | `plugins/grcitsm-analyst/skills/halo-ssp-asset-write-conventions/` | The eight write rules the reviewer enforces |
| Review procedures | Reference | `reference-docs/ssp-review-procedures.md` | BLOCKER + AUTO-FIX finding catalogs, loop procedures verbatim, full-plan scope checklists, Reviewer Notes example, citation convention, pattern flagging |
| Write semantics | Reference | `reference-docs/halo-platform/write-semantics.md` | Lookup-value rules incl. zero-padding, comma-no-space, verbatim-typo matching (§3), framework-CF ordering (§5) |
| Narrative doctrine | Reference | `reference-docs/halo-platform/ssp-narrative-doctrine.md` | by-who taxonomy (§1), inheritance rules (§2), implementation-status vocabulary the State↔narrative check enforces (§3) |

The operational rules for the review phase that sits between reconciliation and user approval in `/ssp-ingest`. The reviewer is the quality gate before any write touches Halo.

## When to load

- During the review phase of `/ssp-ingest` (between Phase 3 reconcile and Phase 4 user approval).
- Composing or debugging the SSP reviewer agent.
- Auditing a previously-reviewed CHANGE-PLAN against these rules.

## The two-tier severity model

Every reviewer finding is one of two tiers. The tier determines whether the reviewer auto-fixes or halts the run. **There is no "suggestion" tier surfaced to the user.** The user gets one clean polished draft per cycle; the user provides edit feedback in chat after seeing the draft (see § Outer user-edit loop below).

### Tier 1 — BLOCKER

A finding the reviewer cannot resolve and that would corrupt Halo state or produce a wrong SSP if applied. **The reviewer never auto-fixes a BLOCKER. The entire run halts until the user resolves it.** Typical classes: wrong control mapping, unmatched lookup values, self-contradicting metadata (Origination/Role vs narrative), off-allow-list relationships, missing required fields, uncited (hallucinated) narrative, identifier-format violations (IS Title/AFUUID embedding framework IDs; IR Title/AFUUID off-convention), Requirements-without-Controls framework CFs, duplicate identities, **KB-association violations** (an article on an IR or IS, on more than one Component, on a non-documentary Component Type, or with a Title that does not match its Component's exactly). Full catalog with rationale per finding: `reference-docs/ssp-review-procedures.md` § BLOCKER catalog.

### Tier 2 — AUTO-FIX

A finding the reviewer can resolve mechanically with high confidence. The fix is applied silently during the loop. The original is preserved in the sidecar audit log; the final CHANGE-PLAN shows only the reviewed text. Typical classes: lookup-value normalization (zero-padding, comma-space stripping, verbatim Halo strings — `reference-docs/halo-platform/write-semantics.md` §3), name canonicalization (Component Title / Provider verbatim), voice and format fixes per [[ssp-brand-voice]] (filler, passive, future tense, hedging, em-dash), separator fixes, and library-binding resolution (annotate `library:` from the AFUUID acronym; replace hand-composed content with library values verbatim). Full catalog with fix-per-finding: `reference-docs/ssp-review-procedures.md` § AUTO-FIX catalog.

## The internal review loop

The reviewer iterates ONLY between BLOCKER detection and AUTO-FIX application. The user is NOT in this loop — the user sees the polished result only after the loop terminates. Gate rules:

1. **Review → auto-fix → re-review.** Every AUTO-FIX pass is followed by a full re-review to catch downstream effects of the fixes.
2. **Termination:** zero BLOCKERs AND zero new AUTO-FIX changes in the current pass.
3. **Max-iterations guard:** hard cap 5 passes; a non-terminating loop halts with a "review oscillating" diagnostic — fix the underlying rule conflict before re-running.
4. **Post-loop decision:** BLOCKERs remain → HALT THE ENTIRE RUN (no writes execute) and emit `blockers.md` with row reference, rule cited, and required user action. Zero BLOCKERs → render the polished draft to the user (Phase 4 approval).
5. **Every AUTO-FIX is logged** to `review-log.md` (original → reviewed, finding category, rule citation).

Step-by-step procedure: `reference-docs/ssp-review-procedures.md` § internal review loop.

## Outer user-edit loop

After the internal loop terminates clean, the user sees the polished CHANGE-PLAN draft (with a Reviewer Notes summary). The user either approves, cancels, or provides edit feedback in natural language. On feedback: translate to concrete row mutations → apply → **re-run the internal review loop against the modified plan** (user edits can introduce BLOCKERs) → re-render → repeat until approve or cancel. **Nothing writes to Halo until explicit user approval.** Each iteration's diff is captured in `user-iterations.md` (feedback, mutations applied, internal-loop outcome). Full procedure, response shapes, and telemetry format: `reference-docs/ssp-review-procedures.md` § outer user-edit loop.

## Full-plan scope

The reviewer inspects **every field** in **every CHANGE-PLAN row** — no field is out of scope: all narrative fields (voice, accuracy, length targets, factual alignment with cited evidence), all structural fields (identifier formats, Origination↔Role↔narrative consistency, Implementation State vs narrative per `ssp-narrative-doctrine.md` §3, lookup conformance, framework-CF ordering and shape, relationship allow-list, AFUUID presence/preservation), and cross-row consistency (canonical naming, no duplicate identities, two-pass CF splits, every framework-CF'd IS has a rel-7 parent IR per catalog). Field-by-field checklists: `reference-docs/ssp-review-procedures.md` § Full-plan scope checklists.

## What the user sees

The user never sees verbose `original → reviewed` diffs — only the FINAL polished draft per outer-loop iteration, headed by brief Reviewer Notes (pass count, auto-fix summary by category, BLOCKER count, audit-file paths). Repeated findings surface once as a **pattern** in Reviewer Notes; the per-row audit lives in `review-log.md`. Rendered example + the rule-category citation convention: `reference-docs/ssp-review-procedures.md`.

## Output artifacts

```
outputs/ssp-ingest-{date}-{run-id}/
  change-plan.md        # CURRENT polished plan (overwritten on every outer-loop iteration)
  review-log.md         # Full audit of every AUTO-FIX (original → reviewed, category, rule cited) across all iterations
  blockers.md           # Present only if run halted on unresolvable BLOCKERs
  user-iterations.md    # Per-iteration log: user feedback + mutations applied + internal-loop outcome
```

## Anti-patterns for the reviewer itself

1. **Don't auto-fix a BLOCKER.** If technical accuracy is in doubt, escalate as BLOCKER. The reviewer's authority on technical correctness is bounded by confidence.
2. **Don't introduce a SUGGESTION tier.** There are exactly two tiers: BLOCKER and AUTO-FIX. The user provides editorial feedback through the outer user-edit loop, not through reviewer suggestions.
3. **Don't loop forever (internal loop).** Hard cap at 5 passes per outer-loop iteration. If the loop oscillates, surface the conflict in the diagnostic.
4. **Don't add verbose diffs to the CHANGE-PLAN.** The plan is for approval; the audit is in `review-log.md`.
5. **Don't strip preserve-unconditionally items** (control IDs, framework terms, Halo Lookup values). Verify against [[ssp-brand-voice]] Preserve list every time.
6. **Don't change Halo identity fields silently.** AFUUID, Component Title, Provider — these are identity. If the reviewer wants to change them, it's a BLOCKER for user resolution.
7. **Don't render to the user mid-internal-loop.** The user only sees the polished draft after the internal review loop terminates clean OR after the loop halts on BLOCKERs. Never render an intermediate (still-being-fixed) draft.
8. **Don't apply user edits without re-running the internal review loop.** Every outer-loop iteration's user edits go through internal review before re-rendering. The reviewer is the gate, even for user-driven changes.
9. **Don't skip the internal loop on outer-loop iterations after the first.** Even when the user's edits are small, they may introduce BLOCKERs (e.g. wrong control mapping) or warrant AUTO-FIXes (e.g. user's hand-typed text uses passive voice).

## Cross-references

[[ssp-brand-voice]] (voice / format / preserve rules) · [[ssp]] (SSP asset workflow primer) · [[ssp-ingest]] (the pipeline this review fits into) · [[halo-ssp-asset-model]] (what the fields ARE) · [[halo-ssp-asset-write-conventions]] (the eight write rules) · `reference-docs/ssp-review-procedures.md` (finding catalogs + procedures).
