Review Story Alignment

---
name: review-story-alignment
description: Adversarial review of generated stories against the Discovery Session Brief, referenced DECs, and Epic DoR. Detects contradictions, omissions, and intent drift BEFORE stories reach Delivery. Produces a structured verdict (PASS/FAIL) with specific findings per story. Triggers after generate-stories, before backlog registration as refined.
license: ELv2
compatibility: Works with any filesystem-based AI coding agent
metadata:
  author: gaai-framework
  version: "1.0"
  category: discovery
  track: discovery
  id: SKILL-RSA-001
  updated_at: 2026-03-22
  status: stable
  tags: [review, alignment, session-brief, quality-gate, adversarial, discovery]
inputs:
  - "Discovery Session Brief (compiled by Discovery Agent — 7 categories: Decisions, Observations, Hypotheses, Trade-offs, Scope Boundaries, Constraints, Qualitative Preferences)"
  - "Generated story files (1 or more .story.md files to review)"
  - "Parent Epic file (for mandatory_ac_categories / DoR)"
  - "Referenced DEC files (from each story's related_decs field)"
outputs:
  - "Inline: structured review verdict per story (PASS / FAIL + findings)"
  - "If all PASS: Discovery proceeds to backlog registration"
  - "If any FAIL: findings returned to Discovery Agent for refinement loop"
---

# Review Story Alignment (SKILL-RSA-001)

## Purpose

Stories generated by Discovery may contradict, omit, or drift from what was discussed during the human ↔ agent conversation. This skill acts as an **adversarial reviewer** — a separate agent that checks stories against the Discovery Session Brief BEFORE they reach Delivery.

**This skill does NOT check format** (that is validate-artefacts). It checks **alignment** — does the story faithfully represent what was decided, observed, and agreed during the Discovery session?

---

## When to Activate

- After `generate-stories` has produced story files
- After `validate-artefacts` has PASSED (format is already correct)
- Before stories are registered in the backlog as `refined`
- **Always** — for every story creation or modification, regardless of batch size, origin, or whether a Session Brief exists

**Do NOT activate:**
- For stories that are already `refined` or `done` (unless being modified)

### Reduced-Scope Mode (no Session Brief)

When no Discovery Session Brief is provided, the gate runs in **reduced-scope mode**:
- **Pass A (Session Brief contradictions): SKIPPED** — produce "SKIPPED — no Session Brief provided" in the verdict. No findings generated for this pass.
- **Pass B (DEC constraint check): RUNS NORMALLY** — DECs are always available from story frontmatter `related_decs`.
- **Pass C (DoR check): RUNS NORMALLY** — Epic `mandatory_ac_categories` is always available.

Reduced-scope mode ensures that DEC cross-referencing and DoR enforcement are never bypassed, even for single-story amendments or bug-triage stories created outside a full Discovery session.

---

## Architecture — Isolated Reviewer

This skill is executed by the **Review Sub-Agent** (SUB-AGENT-REVIEW-001) during Tier 2 review. The Review Sub-Agent already runs in an isolated context window with an adversarial prompt — this skill defines the 3-pass process it follows for story alignment specifically.

**If invoked standalone** (outside the Review Sub-Agent context), this skill MUST still run as a sub-agent in an isolated context window (via the Agent tool). The reviewer must NOT be the same agent instance that wrote the stories.

**Why isolation matters:** The author of the stories has confirmation bias — it wrote the stories believing they were correct. A separate agent with fresh context is more likely to detect contradictions.

**The reviewer receives ONLY:**
1. The Discovery Session Brief (full 7-category block)
2. The story files to review
3. The parent Epic (for DoR categories)
4. The referenced DEC files (full content, not just IDs)

**The reviewer does NOT receive:**
- The conversation history
- The codebase
- Other stories from other Epics
- Project memory beyond the referenced DECs

### Invocation Template

The Discovery Agent MUST invoke the reviewer using this prompt structure (via the Agent tool):

```
You are an adversarial story reviewer. Your job is to find contradictions,
omissions, and drift — not to confirm correctness. Assume stories contain
errors until proven otherwise.

DISCOVERY SESSION BRIEF (human-validated):
══════════════════════════════════════════
{paste the full structured Brief with D-N, O-N, H-N, T-N, S-N, C-N, Q-N items}

EPIC (for DoR categories):
{paste Epic frontmatter including mandatory_ac_categories}

STORIES TO REVIEW:
{paste each story file content}

REFERENCED DECs:
{paste full content of each DEC listed in related_decs}

Execute the review-story-alignment process: 3 passes per story
(Session Brief contradictions, DEC constraints, DoR coverage).

For each finding, reference the Brief item by ID (e.g., "contradicts D-1")
and the story element by AC number (e.g., "AC3 in {story_id}").

Produce a structured verdict per story.
```

**If a Session Brief exists, it MUST be included verbatim in the prompt — with all item IDs (D-N, O-N, etc.).** The Brief is the source of truth for Pass A.

**If no Session Brief exists (single-story amendment, bug-triage, DEC amendment):** replace the Brief block with `DISCOVERY SESSION BRIEF: NONE — reduced-scope mode (Passes B+C only)`. The reviewer skips Pass A and produces "SKIPPED — no Session Brief provided" in the verdict. Passes B and C run normally.

---

## Process

### Step 1 — Load Review Context

Load all inputs:
- Read the Discovery Session Brief
- Read each story file
- Read the parent Epic (extract `mandatory_ac_categories`)
- For each story's `related_decs`, read the full DEC file

### Step 2 — Per-Story Alignment Check (3 passes)

For EACH story, run three passes:

#### Pass A: Session Brief Contradiction Check

Compare every item in the Session Brief against every AC and Context section in the story.

For each Session Brief item, ask:
- "Does any AC in this story CONTRADICT this item?"
- "Does the story's Context section CONTRADICT this item?"
- "Does the story's User Story (As a / I want / so that) CONTRADICT this item?"

**Contradiction = any statement in the story that implies the OPPOSITE of a Session Brief item.**

Examples:
- Brief: "Dashboard = admin-first" → Story: "end-user-facing dashboard" → **CONTRADICTION**
- Brief: "EN only for V1" → Story has zero i18n ACs → **OMISSION** (not contradiction, caught in Pass C)
- Brief: "Pro tier = experiment" → Story treats Pro as guaranteed pillar → **DRIFT**

Classification:
- `CONTRADICTION` — story says the opposite of the brief (severity: CRITICAL)
- `DRIFT` — story subtly reinterprets the brief (severity: HIGH)
- `UNRELATED` — story doesn't touch this brief item (severity: NONE — acceptable)

#### Pass B: DEC Constraint Check

For each DEC in the story's `related_decs`:
1. Read the DEC's decision statement
2. Check: does any AC in the story violate the DEC's constraint?
3. Check: should additional ACs exist to enforce the DEC?

Also perform a **DEC coverage scan**:
- Read the story's keywords (from title, User Story, ACs)
- Scan ALL DEC titles provided
- Flag any DEC that SHOULD be referenced but ISN'T in `related_decs`

Classification:
- `DEC_VIOLATION` — AC contradicts a referenced DEC (severity: CRITICAL)
- `DEC_MISSING` — a relevant DEC is not cross-referenced (severity: HIGH)
- `DEC_PARTIAL` — DEC is referenced but not all constraints are reflected in ACs (severity: MEDIUM)

#### Pass C: Definition of Ready (DoR) Check

Read the Epic's `mandatory_ac_categories`. For each category:
- Does the story have at least one AC that explicitly addresses this category?
- "Explicitly" means the AC mentions the category's concern — not that a related word appears somewhere

Classification:
- `DOR_MISSING` — mandatory AC category has zero coverage (severity: HIGH)
- `DOR_WEAK` — category is mentioned but AC is vague or untestable (severity: MEDIUM)

### Step 3 — Produce Verdict

For each story, produce a structured verdict:

```
## Review: {story_id}

**Verdict: PASS | FAIL**

### Findings

| # | Type | Severity | Brief Item | Story Element | Finding |
|---|------|----------|-----------|---------------|---------|
| 1 | CONTRADICTION | CRITICAL | **D-1** (Dashboard = admin-first) | AC1 | Story says "end-user-facing" — contradicts D-1 |
| 2 | DEC_MISSING | HIGH | **C-1** (<DEC-id>: EN only) | related_decs | The EN-only DEC should be referenced — story has URL routing implications |
| 3 | DOR_MISSING | HIGH | DoR: `error-handling` | No AC | No AC addresses error handling |
| 4 | DRIFT | HIGH | **Q-2** (actionable errors) | AC5 | AC says "return error code" — Q-2 requires actionable guidance, not just codes |

### Refinement Guidance

For each FAIL finding, state:
- What needs to change in the story
- Whether the Discovery Agent has enough information (from the Session Brief) to make the fix autonomously
- If NOT enough information → what question to ask the human
```

### Step 4 — Aggregate Verdict

```
## Batch Review Summary

Stories reviewed: N
PASS: X
FAIL: Y

Critical findings: Z (must be resolved before any story reaches backlog)
```

---

## Reviewer Stance

The reviewer is **adversarial by design**. Its instruction set:

> "You are a reviewer, not a validator. Your job is to find problems, not confirm correctness. Assume the stories contain errors until proven otherwise. For every Session Brief item, actively look for the contradiction — don't look for confirmation. When in doubt, it's a FAIL, not a PASS. A false positive (flagging something that's actually fine) costs 5 minutes to dismiss. A false negative (missing a real problem) costs hours of wrong implementation."

**Calibration:** The reviewer should err on the side of strictness. 1-2 false positives per batch is acceptable. Zero false negatives is the target.

**Severity calibration (founder-confirmed):** MEDIUM (and lower) findings are advisory and non-blocking for a PASS verdict: a story may PASS with open MEDIUM findings provided they are recorded in the finding table. The adversarial "when in doubt, FAIL" stance applies to CRITICAL/HIGH judgments only — i.e. when uncertain whether something is CRITICAL/HIGH, treat it as such; do not inflate a genuine MEDIUM into a blocker.

---

## Quality Checks

- [ ] Every Session Brief item was checked against every story (no items skipped)
- [ ] Every referenced DEC was read in full (not just the title)
- [ ] DoR categories from Epic were verified per story
- [ ] Each finding includes a specific reference (Brief item # or DEC ID or category name)
- [ ] Each FAIL finding includes refinement guidance (what to change + info sufficiency)
- [ ] Verdict is binary per story (PASS or FAIL — no "conditional pass")
- [ ] Reviewer did not modify any story file (review only, no edits)

---

## Non-Goals

- **Does not check format** — that is validate-artefacts (SKILL-VALIDATE-ARTEFACTS-001)
- **Does not refine stories** — it produces findings; the Discovery Agent decides how to act
- **Does not replace human judgment** — Discovery escalates to the human when it lacks information to resolve a finding, but a PASS verdict is sufficient for stories to enter the backlog as `refined`
- **Does not check implementation feasibility** — that is Delivery's Planning Sub-Agent
- **Does not skip when no Session Brief exists** — runs in reduced-scope mode (Passes B+C only). DEC and DoR checks are always valuable.