/reconciling-predev-docs

name: ring:reconciling-predev-docs
description: "Reconciling pre-dev artifacts (research.md, prd.md, feature-map.md, trd.md, openapi.yaml, schema file, dependencies.md, plan.md) against each other to surface contradictions and gaps that break implementation, then applying approved corrections before ring:running-dev-cycle. Use after ring:planning-small-features or ring:planning-large-features. Skip for end-user docs (use ring:reviewing-docs), code review (use ring:reviewing-code), or before the docs exist."

Deep Doc Review

When to use

• Before starting dev-cycle (validate doc quality as a pre-gate)
• After completing pre-dev workflow (ring:planning-small-features or ring:planning-large-features)
• When user requests project documentation review
• After significant changes to reference docs (PRD, TRD, OpenAPI spec, schema, plan)

Skip when

• Code review needed (use ring:reviewing-code instead)
• Docs do not exist yet (run pre-dev workflow first)
• Reviewing a single simple file (do it directly without the skill)

Sequence

**Runs before:** ring:running-dev-cycle, ring:writing-plans **Runs after:** ring:planning-small-features, ring:planning-large-features

Related

**Complementary:** ring:writing-prds, ring:writing-trds, ring:designing-api-contracts, ring:designing-data-model, ring:writing-plans **Differentiation:** ring:reviewing-code reviews code. ring:reconciling-predev-docs reviews documentation artifacts against each other.

> Adapted from alexgarzao/optimus (optimus-deep-doc-review)

Deep cross-reference review of project documentation to catch contradictions before they become implementation bugs. Emphasis is on **inconsistencies between docs**, not just intra-doc quality.

Phase 0: Discover and Load Docs

Step 0.1: Identify Docs to Review

If user specified files, use those. Otherwise, auto-discover:

**Search locations:**

• `docs/pre-dev/<feature>/` (Ring pre-dev artifacts)
• `docs/` (general project docs)
• Root directory (README, CHANGELOG, ARCHITECTURE)

**Include:** research.md, prd.md, feature-map.md, trd.md, openapi.yaml, schema file (schema.sql / schema.prisma), dependencies.md, plan.md, design-validation.md (if present), coding standards, README, CHANGELOG

**Exclude:** generated files, node_modules, build artifacts, binary files, test fixtures

Present discovered docs list to user before proceeding.

Step 0.2: User Confirms Scope

Show doc list and ask: "Are there additional documents to include or any to exclude?"

Step 0.3: Load All Docs

Read each document. Build a cross-reference map: entities, fields, endpoints, and decisions mentioned in each doc. Parse openapi.yaml and the schema file as machine-readable specs (paths, operations, components; tables, columns, types) — not prose.

Phase 1: Cross-Reference Analysis

For each pair of docs that share entities or concepts, check for contradictions:

| Cross-Reference | What to Check | |----------------|---------------| | research.md ↔ TRD | Chosen architecture traces to research findings; rejected alternatives not silently reintroduced | | PRD ↔ TRD | TRD covers all PRD requirements; TRD doesn't add new requirements; NFRs align | | PRD ↔ feature-map.md | Every in-scope PRD feature appears in the map; `## Phases` cover full PRD scope (Large) | | TRD ↔ openapi.yaml | Paths/operations match TRD component interfaces and data flow; spec is valid OpenAPI 3.1 | | openapi.yaml ↔ schema file | Request/response schema fields exist as columns; names consistent; types compatible (machine-readable cross-check) | | TRD ↔ schema file | All TRD entities have tables/models; relationships and constraints match the architecture | | schema file ↔ plan.md | All entities have creation/migration tasks; relationships implemented | | TRD ↔ dependencies.md | All TRD components have explicit pinned dependencies; no undeclared tech | | feature-map.md ↔ plan.md | plan.md phases mirror feature-map `## Phases` one-to-one (Large) | | PRD ↔ plan.md | Every PRD requirement covered by at least one epic/task; acceptance criteria traceable | | design-validation.md ↔ TRD/plan.md (optional, if present) | UI surfaces honor the standalone UX verdict; flagged gaps have tasks |

Phase 2: Intra-Document Quality

For each document:

| Check | Description | |-------|-------------| | Completeness | Required sections present; no "TBD" or placeholder content | | Internal consistency | Same entity/field named the same way throughout | | Format compliance | Gate-specific format requirements met | | Clarity | No ambiguous language; success criteria testable |

Phase 3: Findings Report

Classify findings:

| Severity | Criteria | Action | |----------|----------|--------| | **CRITICAL** | Contradiction that will cause implementation failure | MUST fix before dev-cycle | | **HIGH** | Missing information that blocks a specific task | Should fix before dev-cycle | | **MEDIUM** | Inconsistency that will cause confusion | Fix preferred | | **LOW** | Style, formatting, minor clarity | Optional |

Present findings to user with:

• Finding description
• Documents affected
• Specific location (doc → section → line reference)
• Suggested correction

Phase 4: Apply Approved Corrections

For each finding user approves: 1. Make the correction directly in the affected document 2. Mark finding as FIXED 3. Continue to next finding

Phase 5: Summary

# Deep Doc Review Summary

**Date:** {YYYY-MM-DD}
**Documents Reviewed:** {N}
**Cross-References Checked:** {N pairs}

## Finding Summary
| Severity | Found | Fixed | Skipped |
|----------|-------|-------|---------|
| CRITICAL | N | N | N |
| HIGH | N | N | N |
| MEDIUM | N | N | N |
| LOW | N | N | N |

## Status
✅ CLEARED — Ready for ring:running-dev-cycle
⚠️ ISSUES REMAIN — {N} unfixed critical/high findings

**Output:** `docs/pre-dev/{feature}/doc-review-{date}.md`