# Data Change Specifications

This directory contains idempotent data change specs for modifying the NexusCRM
production database. Each spec is a markdown file with SQL blocks and structured
YAML frontmatter.

## Quick Reference

- **Format**: See `.agent/skills/data-change-spec/SKILL.md`
- **How to apply**: See `.agent/skills/data-spec-apply/SKILL.md`
- **Compaction**: See `.agent/skills/data-spec-compaction/SKILL.md`
- **Data vs code guide**: See `.agent/skills/data-vs-code/SKILL.md`

## Directory Structure

```
data-specs/
├── README.md              ← you are here
├── *.md                   ← pending and applied specs
├── compacted/             ← merged specs (after compaction)
├── archive/               ← original specs superseded by compaction
└── backups/               ← row-level backups taken before apply
```

## Spec Lifecycle

1. **Created** by the fix pipeline (or manually) — `status: pending`
2. **Reviewed** via PR (idempotency, rollback, safety checks)
3. **Applied** to production — `status: applied`
4. **Compacted** periodically — originals archived, merged spec created
5. **Rolled back** if needed — `status: rolled-back`

## Creating a Spec

Name: `YYYY-MM-DD-<descriptive-slug>.md`

Required sections:
- YAML frontmatter with `apiVersion`, `id`, `scope`, `status`, `tables`
- Summary
- Changes (numbered, each with SQL block + idempotency note)
- Rollback (SQL to reverse all changes)

See the `data-change-spec` skill for the full format specification and examples.