# Story Quality Gates (RCA-020 Fix)

This reference documents evidence verification requirements added after RCA-020
identified false claims in generated stories.

---

## Required Story Elements

All stories generated by batch creation MUST include:

1. **verified_violations section** — When technical specifications claim violations
   exist, the story MUST include a verified_violations section proving those
   violations were found.

2. **Specific file paths and line numbers** — Verified violations must include
   actual line numbers like `lines: [469, 598, 599]`, not generic descriptions.

3. **Target file validation** — All files mentioned in verified_violations are
   checked to exist and contain the claimed violations.

4. **No placeholders** — Values like "TBD", "TODO", or "N/A" are not permitted
   in verified_violations sections.

---

## Story Creation Failure Reasons

| Failure Reason | Description | Fix |
|----------------|-------------|-----|
| Target file not found | File path in verified_violations does not exist | Verify file path with Glob/Read before citing |
| Claim not verified | Claimed violation not found at specified lines | Run Grep to confirm violation exists |
| Generic description | Line numbers missing or described generically | Use actual line numbers from Read output |
| Placeholder values | TBD, TODO, N/A in verified_violations | Replace with verified evidence or remove claim |

---

## Example Error Message

```
CRITICAL: Story creation blocked - Evidence verification failed

Claim: "No specific test output validation patterns"
File: .claude/skills/spec-driven-stories/SKILL.md
Issue: Claimed violation not found at lines 598-599

Action: Verify claim with Read() before including in story.
```

---

## Why Evidence-Based Verification?

DevForgeAI enforces evidence-based story creation to ensure:

1. **No false claims** — Every technical specification is backed by verified evidence
2. **Implementable stories** — Developers can trust that claimed violations actually exist
3. **No post-hoc verification** — Stories are ready to implement without re-checking claims
4. **Framework integrity** — Follows Read-Quote-Cite-Verify protocol from
   `.claude/rules/core/citation-requirements.md`

---

## References

- Grounding Protocol: `.claude/rules/core/citation-requirements.md` (Grounding Protocol section)
- Evidence Gate Implementation: STORY-211
- Citation Validation: STORY-212
- RCA-020: Root Cause Analysis for false claims in generated stories

---

**Created:** 2026-02-20 (STORY-457)
**Migrated:** 2026-03-18 (verbatim from validating-epic-coverage/references/story-quality-gates.md)
