/archetype-review-base

name: archetype-review-base
description: Shared review framework that every domain reviewer (pci, oracle, gov, edtech, healthcare, mlops, etc.) MUST follow. Defines the output artifact (TM-{slug}.md), mandatory sections, severity scale, verdict format, the workflow scaffold (when-invoked, Step-0 read-inputs, HANDOFF), and the "domain heuristic vs generic check" boundary. Eliminates duplication across the ~30 reviewer prompts.
when_to_use: |
  Apply when invoked as ANY domain reviewer:
  - pci-reviewer, oracle-reviewer, gov-reviewer, healthcare-reviewer,
    mlops-reviewer, ai-security-reviewer, edtech-reviewer,
    enterprise-saas-reviewer, insurance-reviewer, regulated-reviewer,
    marketplace-reviewer, cms-reviewer, devtools-reviewer,
    library-reviewer, cli-reviewer, data-platform-reviewer,
    streaming-reviewer, infra-reviewer, firmware-reviewer,
    game-reviewer, web-store-reviewer, mobile-store-reviewer,
    db-migration-reviewer, ai-prompt-architect, ai-eval-engineer
  Do NOT apply when running security-officer general STRIDE — that's a
  different review tier (cross-domain, fallback for archetypes without
  a domain reviewer).
effort: medium
allowed-tools: Read, Write, Grep, Glob, Bash(git:*), Bash(bd:*)
paths:
  - "docs/**"
  - ".great_cto/verdicts/**"

Archetype-review-base — shared review framework

Every domain reviewer follows this skeleton. Each reviewer's own SKILL.md adds the domain heuristics on top. This skill defines the parts that must be IDENTICAL across all reviewers.

Output artifact (canonical)

Pre-implementation reviewers (the `*-reviewer` agents — ~30 in `agents/` — invoked by architect BEFORE senior-dev claims tasks) write a **threat model** at `docs/sec-threats/TM-{slug}.md` and append a `<!-- HANDOFF -->` block (see "Workflow scaffold" below). That is the single convention for every reviewer.

**One TM file per feature slug.** Per-reviewer filename suffixes (`TM-api-{slug}.md`, `TM-extension-{slug}.md`) are deprecated — consumers glob `TM-{slug}.md` and per-suffix files silently escape their checks. When multiple domain reviewers run on the same slug, each APPENDS its own `## {reviewer} findings` section and its own `<!-- HANDOFF -->` block to the shared `TM-{slug}.md` — never overwrite another reviewer's sections.

The **Findings / Severity / Verdict** structure below is the CONTENT format that goes inside that artifact (and inside any post-implementation `docs/reviews/REVIEW-{slug}.md` produced by a review-tier agent). Path differs by phase; the section grammar is identical.

Mandatory report sections

The report (TM or REVIEW) MUST contain these sections in this exact order:

# TM-{slug} — {reviewer name}      <!-- pre-impl; post-impl review-tier files use REVIEW-{slug} -->

Reviewed: {commit-sha or file paths or ARCH doc reference}
Standard: {regulation / framework you applied — list specific clauses}
Date: {ISO timestamp}

## Scope

2-3 sentences. What did you look at? What's intentionally out of scope?

## Findings

For each finding, use this exact format:

- **[Critical|High|Medium|Low]** {one-sentence finding title}
  - Location: {file:line or component name}
  - Rationale: {why this matters IN THIS DOMAIN — cite a regulation or
    domain-specific best practice. Generic "could be a problem" is
    rejected.}
  - Repro: {a command, or numbered steps, that SHOWS the finding. Required for
    Critical and High.}
  - Remediation: {specific fix — code change, config change, or
    architectural change. NOT "consider adding X" — write the exact change.}
  - References: {URL or document section}

Order findings: Critical → High → Medium → Low.
If no findings at a tier, write: "_None at {tier} severity._"

### Repro, and why it is required at Critical and High

A finding with no reproduction cannot be shown to be fixed, so closing it is an
opinion. A security review on 2026-08-07 said exactly this about its own weaker
items and scored them lower for it — the rule is that reviewer's own standard,
written down.

It is also what makes the finding survive you. The person who fixes it is not
you, and neither is the person who checks the fix; a reproduction is the only
part of a finding that both of them can run.

### File Critical and High as beads

A finding that lives only in a report is one nobody can track, and one whose
closure nobody can check. Two of them were closed on 2026-08-07 by the author of
the fix, which is not a check at all — `scripts/lib/finding-closure.mjs` calls
that `self-verified` and refuses it, but only for findings it can see.

```bash
bd create "[Critical] {title}" --label finding --type bug \
  -d "Location: {file:line}
Repro: {command or steps}
Rationale: {why}
Remediation: {exact fix}"

Then, as the finding moves:

bd comment <id> "fixed-by: <agent>"      # whoever writes the fix
bd comment <id> "verified-by: <agent>
repro-result: passed"                    # someone who did NOT write it,
                                         # stating what the repro did NOW
bd close <id> --reason "repro re-run after the fix, now passing"

`repro-result` is `passed`, `failed` or `not_run`, and the VERIFIER writes it in the same comment as `verified-by`. Nothing re-executes the reproduction on your behalf: running a command out of a bead description is how a reporting channel becomes an execution channel, and it produced three CRITICALs in `execution-claims` on 2026-08-07. So this rung checks who says the repro passes and whether they wrote the fix — not the command. That is a real limit and it is the deliberate one.

A verification that does not say what the reproduction did leaves the finding `repro-not-run`. "Looks fine to me" is not a result.

The verifier may not be the fixer, the verification must come after the fix, and the repro must pass now. Those are checked, not merely asked for.

Verdict

VERDICT: {APPROVED|BLOCKED} reason="{specific reason}"

## Severity scale (DOMAIN-anchored)