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-22T00:00:00.000Z","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.