# Application Best Practices Check

## Context

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

## Schema Constraints

Read [erp-kit-app-shared/references/schema-constraints.md](../../erp-kit-app-shared/references/schema-constraints.md) before evaluating. **Never recommend changes that violate the schema.**

## 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 incomplete or missing.

## Instructions

1. Read the application README at the path above
2. Read ALL actor docs and business flow docs at the paths above
3. **Web search** ERP application best practices (actor modeling, business flow design, user journey patterns)
4. Evaluate whether the Tier 1-2 documentation follows best practices
5. **Verify** that none of your recommendations would violate the schema constraints above
6. Return results as markdown per the Output Format section

## Application Design Checks

For each actor and business flow, evaluate:

| Check ID                 | Question                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| actor_completeness       | Does each actor have a clear role description, permissions scope, and linked business flows? |
| actor_separation         | Are actor responsibilities well-separated? No single actor doing everything?                 |
| flow_coherence           | Does each business flow have a clear trigger, logical step sequence, and defined outcome?    |
| sequence_diagram_quality | Do sequence diagrams accurately represent actor interactions and system responses?           |
| requirement_coverage     | Do business flows collectively cover the requirements stated in README?                      |
| missing_flows            | Are there obvious workflows missing based on the stated requirements?                        |
| flow_granularity         | Are flows at the right level of granularity? (not too coarse, not too fine)                  |
| error_path_coverage      | Do flows account for error paths and edge cases, not just happy paths?                       |

## Common Application Design Issues

- **Overloaded actors**: A single actor responsible for too many unrelated flows
- **Missing system actor**: Automated/system-triggered flows not represented as an actor
- **Disconnected flows**: Flows that don't link to each other when they should (e.g., an approval flow that doesn't connect to the submission flow)
- **Missing error flows**: Only happy-path documented, no handling of rejections, cancellations, or failures
- **Vague requirements**: README states features that no business flow implements
- **Inconsistent granularity**: Some flows are very detailed while others are hand-wavy

## Output Format

Return your findings as a structured markdown report:

### Check Results

For each finding:

- **Scope:** actor name, flow name, or "application-level"
- **Check:** check ID
- **Status:** pass / fail / warn
- **Detail:** what was found and why it matters

### Recommendations

Numbered list grouped by priority (critical → high → medium → low). Each item should explain the issue and the recommended fix.

### Summary

Table with columns: Metric, Count

- Total checks
- Passed
- Failed
- Warned
