---
name: ao-narrative-audit
description: "Audit the project's story for coherence. Ensure issues, commits, plans, docs, and changelog tell a consistent narrative."
category: analysis
invokes: [ao-state, ao-git, ao-docs]
invoked_by: [ao-critical-review, ao-retrospective]
state_files:
  read: [issues/*.md, memory.md, baseline.md]
  write: [memory.md]
---

# ao-narrative-audit

Audit the project's story for coherence. Ensure issues, commits, plans, docs, and changelog tell a consistent narrative.

## Purpose

Great projects tell a consistent story. Broken projects have unexplained decisions, orphaned features, contradictory docs, and missing chapters. This skill identifies narrative gaps.

## Trigger

- Before major releases
- During documentation updates
- After significant refactoring
- On demand for project health check

## Narrative Sources

| Source | Story Contribution | Location |
|--------|-------------------|----------|
| **Issues** | What we intended to do | `.agent/ops/issues/` |
| **Commits** | What we actually did | Git log |
| **Plans** | How we thought to do it | `.agent/ops/specs/` |
| **Docs** | What we say we did | `.github/docs/`, README |
| **Changelog** | What we tell users | CHANGELOG |

## Narrative Gaps

| Gap Type | Example | Detection |
|----------|---------|-----------|
| **Orphaned feature** | Code exists, no issue | Commits without issue ref |
| **Zombie issue** | Issue closed, no code | Done but no implementation |
| **Contradiction** | Docs say X, code does Y | Doc vs code mismatch |
| **Silent change** | Code changed, no docs | Missing changelog entry |

## Related Skills

- `ao-git` — commit history analysis
- `ao-docs` — documentation consistency
- `ao-housekeeping` — includes narrative checks
