# Documentation Consistency Check

## Context

App: {{APP_NAME}}
App README: {{APP_README}}
Actor docs: {{ACTOR_DOCS}}
Business flow docs: {{BUSINESS_FLOW_DOCS}}

## Schema Constraints

Read [erp-kit-shared/references/schema-constraints.md](../../erp-kit-shared/references/schema-constraints.md) before evaluating. When checking `naming_consistency`, validate that H1 headings follow the schema rules — different doc types have different heading formats.

## Tier 2 Scope

This review targets Tier 1-2 documentation only. Stories (`## Stories` section in business flows) are created in step 3 (`erp-kit-app-3-plan`). A `- TBD` placeholder in the Stories section is expected and correct at this stage — do **not** flag it as a broken link, missing content, or incomplete documentation.

## Instructions

1. Read the application README at the path above
2. Read ALL actor docs and business flow docs at the paths above
3. Cross-reference actors, flows, and requirements for internal consistency
4. **Verify** that none of your recommendations would violate the schema constraints above
5. Return results as markdown per the Output Format section

## Consistency Checks

| Check ID               | Question                                                                         |
| ---------------------- | -------------------------------------------------------------------------------- |
| actor_flow_cross_ref   | Is every actor referenced in at least one business flow?                         |
| flow_actor_cross_ref   | Does every business flow reference only actors that have actor docs?             |
| actor_link_validity    | Do actor docs link to business flows that exist?                                 |
| flow_link_validity     | Do business flow docs link to actor docs that exist?                             |
| readme_flow_coverage   | Does every requirement/feature in README have a corresponding business flow?     |
| naming_consistency     | Are actor and flow names consistent across all documents? (no typos, no aliases) |
| diagram_actor_match    | Do sequence diagram participants match the "Actors Involved" section?            |
| flow_step_completeness | Does every flow step identify a responsible actor?                               |

### How to Check

1. Extract all actor names from actor docs (filename slugs and H1 headings)
2. Extract all flow names from business flow docs (directory names and H1 headings)
3. For each actor doc, check "Authorized Flows" links resolve to existing flows
4. For each flow doc, check "Actors Involved" references match existing actor docs
5. For each sequence diagram, verify participants match the actors listed in "Actors Involved"
6. Compare README features/requirements against business flow coverage

## Common Consistency Issues

- **Phantom actors**: Flow references an actor with no actor doc
- **Orphaned actors**: Actor doc exists but no flow references them
- **Broken links**: Actor→flow or flow→actor links point to non-existent files
- **Name drift**: Actor called "Admin" in one doc and "Administrator" in another
- **Diagram mismatch**: Sequence diagram uses different participant names than "Actors Involved"
- **Uncovered requirements**: README lists a feature but no business flow implements it

## Output Format

Return your findings as a structured markdown report:

### Check Results

Table with columns: Actor/Flow, Check, Status (pass/fail/warn), Detail

One row per check performed.

### Recommendations

Numbered list grouped by priority (critical → high → medium → low). Each item is an actionable recommendation.

### Summary

Table with columns: Metric, Count

- Total checks
- Passed
- Failed
- Warned
