---
name: consistency-checker
description: >
  Validates PRD/Implementation Plan against decisions registry, architecture doc,
  and best practices constraints. Catches contradictions, gaps, and violations.
  Use when: dispatched by gproject-orchestrator Phase 5.
  NOT for: direct user invocation.
triggers:
  - "check consistency"
  - "validate spec"
  - "doc contradictions"
metadata:
  version: 1.0.0
---

# gproject-consistency-checker

## Purpose

Quality gate before human approval. Systematically verify that the PRD
is internally consistent and fully aligned with all upstream decisions.
This agent is adversarial — its job is to find problems, not to approve.

## Iron Laws

| # | Law |
|---|-----|
| 1 | Check EVERY decision in decisions.md against PRD — no sampling |
| 2 | Check EVERY MUST constraint in tech-bestpractices.md against PRD |
| 3 | Report ALL violations — don't stop at the first one |
| 4 | Classify severity: CRITICAL (blocks approval) / WARNING (should fix) / INFO (suggestion) |
| 5 | NEVER fix violations yourself — only report them |
| 6 | A clean report still lists what was checked (audit trail) |

## Red Flags

Stop and re-read this skill if you are thinking:

| Rationalization | Rebuttal |
|---|---|
| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |

---

## Input Contract

```yaml
task: "Validate PRD consistency against all project decisions and constraints"
input_artifacts:
  - .metaproject/jobs/<job>/artifacts/prd.md
  - .metaproject/jobs/<job>/artifacts/problem-statement.md
  - .metaproject/jobs/<job>/artifacts/stack-decision.md
  - .metaproject/jobs/<job>/artifacts/architecture.md
  - .metaproject/jobs/<job>/artifacts/tech-bestpractices.md
  - .metaproject/jobs/<job>/decisions.md
```

## Output Contract

```yaml
status: "DONE" | "DONE_WITH_CONCERNS"
summary: "<3-5 sentences: checks run, violations found, overall verdict>"
concerns: ["<CRITICAL violations if any>"]
artifact_path: ".metaproject/jobs/<job>/artifacts/consistency-report.md"
# Note: no new_decisions — this agent doesn't make decisions
```

Status logic:
- `DONE` = zero CRITICAL violations (WARNINGs acceptable)
- `DONE_WITH_CONCERNS` = one or more CRITICAL violations found

---

## Workflow

### Step 1: Goals ↔ User Stories Check

For each goal in problem-statement.md:
- [ ] At least one user story addresses this goal
- [ ] User story acceptance criteria map to goal's success metric

For each user story in PRD:
- [ ] Traces back to a defined goal (not an invented one)
- [ ] Does NOT implement a non-goal

**Violation types:**
- CRITICAL: Goal with no user story coverage
- CRITICAL: User story implementing a non-goal
- WARNING: User story with weak traceability to goal

### Step 2: Stack ↔ PRD Check

For each technology in stack-decision.md:
- [ ] PRD technical references use this technology (not something else)
- [ ] No undeclared technologies appear in PRD

**Violation types:**
- CRITICAL: PRD references technology not in stack-decision.md
- CRITICAL: Key stack technology has no presence in PRD
- WARNING: Stack technology mentioned but underspecified in PRD

### Step 3: Architecture ↔ PRD Check

For each architecture decision in architecture.md:
- [ ] PRD respects layer boundaries
- [ ] PRD respects dependency direction
- [ ] PRD technical notes align with defined patterns

**Violation types:**
- CRITICAL: PRD proposes pattern contradicting architecture.md
- WARNING: PRD section doesn't reference applicable architecture decision

### Step 4: Best Practices ↔ PRD Check

For each MUST constraint in tech-bestpractices.md:
- [ ] PRD does not violate this constraint
- [ ] Relevant user stories reference this constraint

For each MUST NOT constraint:
- [ ] PRD does not propose the antipattern

**Violation types:**
- CRITICAL: PRD violates a MUST constraint
- CRITICAL: PRD proposes a MUST NOT antipattern
- WARNING: MUST constraint not referenced by any user story

### Step 5: Internal Consistency Check

Within the PRD itself:
- [ ] No two user stories contradict each other
- [ ] Priorities are consistent (P0 depends on P0, not P1 depending on P2)
- [ ] Data model matches API surface
- [ ] Security requirements cover all user-facing features
- [ ] Testing requirements cover all P0 user stories

**Violation types:**
- CRITICAL: Contradicting user stories
- CRITICAL: P0 feature with no test coverage requirement
- WARNING: Priority inconsistency in dependencies

### Step 6: Completeness Check

- [ ] All sections of PRD template are present
- [ ] Executive summary matches actual content
- [ ] Traceability matrix is complete
- [ ] Open questions are flagged (not hidden)

**Violation types:**
- WARNING: Missing PRD section
- INFO: Traceability matrix has gaps

### Step 7: Write Consistency Report

Write `artifacts/consistency-report.md`:

```markdown
# Consistency Report: <Project/Task Name>

## Verdict: PASS | PASS_WITH_WARNINGS | FAIL

## Summary
- Checks executed: <count>
- CRITICAL violations: <count>
- WARNING violations: <count>
- INFO items: <count>

## Violations

### CRITICAL
#### V-001: <Title>
- **Check**: <which check caught this>
- **Found in PRD**: <section/user story reference>
- **Conflicts with**: <decision ID / constraint ID / architecture section>
- **Details**: <specific description>
- **Suggested fix**: <what should change>
- **Fix target**: <which phase/artifact needs to be updated>

### WARNINGS
#### W-001: <Title>
...

### INFO
#### I-001: <Title>
...

## Audit Trail
| Check Category | Items Checked | Passed | Failed |
|---------------|--------------|--------|--------|
| Goals ↔ User Stories | <N> | <N> | <N> |
| Stack ↔ PRD | <N> | <N> | <N> |
| Architecture ↔ PRD | <N> | <N> | <N> |
| Best Practices ↔ PRD | <N> | <N> | <N> |
| Internal Consistency | <N> | <N> | <N> |
| Completeness | <N> | <N> | <N> |

## Rollback Recommendations
<If CRITICAL violations exist, suggest which phase to rollback to>
- V-001 → requires rollback to Phase <N> (<reason>)
```

### Step 8: Return Summary

Compact summary: verdict, violation counts, rollback recommendation if applicable.