EasyPlatform Business Feature Documentation

Generate comprehensive business feature documentation following the GOLD STANDARD template pattern.

GOLD STANDARD Reference: docs/features/README.ExampleFeature1.md (Example App) Template File: docs/templates/detailed-feature-docs-template.md

Output Structure

All documentation MUST be placed in the correct folder structure:

docs/
├── BUSINESS-FEATURES.md              # Master index (UPDATE if new module)
└── business-features/
    ├── {Module}/                     # Module folder
    │   ├── README.md                 # Complete module documentation
    │   ├── INDEX.md                  # Navigation hub
    │   ├── API-REFERENCE.md          # Endpoint documentation
    │   ├── TROUBLESHOOTING.md        # Issue resolution guide
    │   └── detailed-features/
    │       ├── README.{FeatureName}.md     # Deep dive (~1000 lines)
    │       └── README.{FeatureName}.ai.md  # AI companion (~300 lines)
    └── ...

MANDATORY 26-SECTION STRUCTURE

All feature documentation in detailed-features/ MUST follow this section order:

Phase 1: Module Detection & Context Gathering

Step 1.1: Identify Target Module

Determine which module the feature belongs to by:

1. User explicitly specifies module name
2. Feature name/domain implies module
3. Search codebase for feature-related entities/commands

Step 1.2: Read Existing Documentation

Before creating new docs, read existing structure:

1. Read docs/BUSINESS-FEATURES.md (master index)
2. Read docs/business-features/{Module}/INDEX.md (if exists)
3. Read docs/business-features/{Module}/README.md (if exists)
4. Identify what already exists vs what needs creation/update

Step 1.3: Codebase Analysis

Gather evidence from source code:

• Entities: src/Services/{Module}/{Module}.Domain/Entities/
• Commands: src/Services/{Module}/{Module}.Application/UseCaseCommands/
• Queries: src/Services/{Module}/{Module}.Application/UseCaseQueries/
• Controllers: src/Services/{Module}/{Module}.Service/Controllers/
• Frontend: src/BravoWeb/apps/bravo-{module}/ or src/BravoWeb/libs/apps-domains/

Phase 2: Key Format Examples

Quick Navigation by Role

| Role | Priority Sections | Key Concerns |
|------|------------------|--------------|
| **Product Owner** | Executive Summary, Business Value, Roadmap | ROI, scope, timeline, dependencies |
| **Business Analyst** | Business Requirements, Business Rules, Process Flows | Requirements traceability, acceptance criteria |
| **Developer** | Architecture, Domain Model, API Reference, Implementation Guide | Code patterns, integration points |
| **Tech Architect** | System Design, Architecture, Cross-Service Integration, Performance | System design, scalability, tech debt |
| **QA Engineer** | Test Specifications, Test Data Requirements, Edge Cases Catalog | Test coverage, automation feasibility |
| **QC Analyst** | All sections | Evidence verification, documentation accuracy |
| **DevOps** | Operational Runbook, Troubleshooting, Performance | Deployment, monitoring, incident response |

Business Requirements (FR-XX)

#### FR-{MOD}-01: {Requirement Title}

| Aspect          | Details                                              |
| --------------- | ---------------------------------------------------- |
| **Description** | {What this requirement enables}                      |
| **Scope**       | {Who can use / affected entities}                    |
| **Validation**  | {Business rules and constraints}                     |
| **Priority**    | {P0/P1/P2/P3}                                        |
| **Evidence**    | `{FilePath}:{LineRange}`                             |

User Stories (US-XX)

#### US-{MOD}-01: {Story Title}

**As a** {role}
**I want** {goal/desire}
**So that** {benefit/value}

**Acceptance Criteria**:
- [ ] AC-01: {Criterion with evidence reference}
- [ ] AC-02: {Criterion with evidence reference}

**Related Requirements**: FR-{MOD}-01, FR-{MOD}-02
**Evidence**: `{FilePath}:{LineRange}`

Business Value

### Value Proposition

| Value Type | Description | Impact | Quantification |
|------------|-------------|--------|----------------|
| Revenue | {Revenue impact} | {H/M/L} | {$ or % if available} |
| Efficiency | {Time/cost savings} | {H/M/L} | {Hours/costs saved} |
| User Experience | {UX improvement} | {H/M/L} | {NPS/satisfaction improvement} |
| Compliance | {Regulatory/audit benefit} | {H/M/L} | {Risk reduction} |

Business Rules

### Validation Rules

| Rule ID | Rule | Condition | Action | Evidence |
|---------|------|-----------|--------|----------|
| BR-{MOD}-01 | {Rule name} | {When condition} | {Then action} | `{File}:{Line}` |

### State Transitions

| From State | Event | To State | Conditions | Evidence |
|------------|-------|----------|------------|----------|
| Draft | Activate | Active | {Conditions} | `{File}:{Line}` |

Technical Decisions Log

### Technical Decisions Log

| Decision | Date | Options Considered | Chosen | Rationale | Evidence |
|----------|------|-------------------|--------|-----------|----------|
| {Decision title} | {Date} | {Option A, B} | {Chosen} | {Why} | `{File}:{Line}` |

### Technical Debt

| Item | Severity | Impact | Remediation Plan | Evidence |
|------|----------|--------|------------------|----------|
| {Debt item} | H/M/L | {Impact} | {Plan} | `{File}:{Line}` |

Test Specifications (TC-XX)

Test Summary Table (MANDATORY):

| Category               | P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low) | Total |
| ---------------------- | :-----------: | :-------: | :---------: | :------: | :---: |
| {Category1}            | {N}           | {N}       | {N}         | {N}      | {N}   |
| **Total**              | **{N}**       | **{N}**   | **{N}**     | **{N}**  | **{N}**|

Test Case Format:

#### TC-{MOD}-001: {Test Name} [P0]

**Acceptance Criteria**:
- ✅ {Passing criteria 1}
- ✅ {Passing criteria 2}

**GIVEN** {initial context}
**WHEN** {action performed}
**THEN** {expected outcome}

**Edge Cases**:
- ❌ {Invalid scenario} → {Expected error/behavior}

**Evidence**: `{FilePath}:{LineRange}`

Edge Cases Catalog

### Input Validation Edge Cases

| ID | Scenario | Input | Expected Behavior | Evidence |
|----|----------|-------|-------------------|----------|
| EC-01 | Empty string | `""` | Validation error | `{File}:{Line}` |
| EC-02 | Max length | `{256 chars}` | Truncate/Error | `{File}:{Line}` |

### Business Logic Edge Cases

| ID | Scenario | Condition | Expected Behavior | Evidence |
|----|----------|-----------|-------------------|----------|
| EC-10 | {Scenario} | {Condition} | {Behavior} | `{File}:{Line}` |

Operational Runbook

### Deployment Checklist

- [ ] Database migrations applied
- [ ] Configuration values verified
- [ ] Health checks passing
- [ ] Smoke tests executed
- [ ] Rollback plan ready

### Monitoring

| Metric | Alert Threshold | Dashboard | Escalation |
|--------|-----------------|-----------|------------|
| Error Rate | >1% | {Dashboard URL} | {Team} |

Evidence Verification Protocol

## Evidence Verification Protocol

### Verification Summary

| Category | Total Claims | Verified | Stale | Missing | Last Verified |
|----------|-------------|----------|-------|---------|---------------|
| Business Requirements | {N} | {N} | {N} | {N} | {Date} |
| Architecture | {N} | {N} | {N} | {N} | {Date} |
| Test Specifications | {N} | {N} | {N} | {N} | {Date} |
| **Total** | **{N}** | **{N}** | **{N}** | **{N}** | |

### Evidence Verification Table

| Claim ID | Claim | File | Documented Lines | Actual Lines | Status | Verified By |
|----------|-------|------|-----------------|--------------|--------|-------------|
| FR-{MOD}-01 | {Claim} | `{File}` | L{X}-{Y} | L{X}-{Y} | ✅ Verified | {Name/Date} |

### Audit Trail

| Date | Action | Reviewer | Notes |
|------|--------|----------|-------|
| {Date} | Initial verification | {Name} | {Notes} |

Security Architecture

### Authorization Matrix

| Role | View | Create | Edit | Delete | Special Permissions |
|------|:----:|:------:|:----:|:------:|---------------------|
| Admin | ✅ | ✅ | ✅ | ✅ | Full access |
| Manager | ✅ | ✅ | ✅ | ❌ | Company scope |
| User | ✅ | ❌ | ❌ | ❌ | Own data only |

### Data Protection

| Data Type | Protection | Evidence |
|-----------|------------|----------|
| PII | Encrypted at rest | `{File}:{Line}` |

Glossary

## Glossary

| Term | Definition | Context |
|------|------------|---------|
| {Term} | {Definition for non-technical stakeholders} | {Where used} |
| {Acronym} | {Full form and meaning} | {Where used} |

Phase 2.5: AI Companion Generation

Generate AI-agent optimized companion file alongside the comprehensive documentation.

Output: docs/business-features/{Module}/detailed-features/README.{FeatureName}.ai.md Template: docs/templates/detailed-feature-docs-template.ai.md

AI Companion Structure (10 Sections, ~260 lines)

Compression Rules

1. Tables over prose – Convert paragraphs to table rows
2. Paths over descriptions – File:Line over “located in…”
3. Signatures over examples – { id: string } → { entity: Dto } over full code
4. Decisions over explanations – What to do, not why

AI Companion Quality Check

• File size ≤300 lines
• All file paths are exact and current
• API contracts include request/response shapes
• Business rules have evidence references
• Patterns section has ✅/❌ markers
• Evidence chain preserved from full doc

Phase 3: Master Index Update

After creating/updating module docs, update docs/BUSINESS-FEATURES.md:

1. Read current content
2. Verify module is listed in the “Detailed Module Documentation” table
3. Add link if missing:

   | **{Module}** | [Description] | [View Details](./business-features/{Module}/README.md) |
   

Anti-Hallucination Protocols

EVIDENCE_CHAIN_VALIDATION

• Every feature claim MUST have code reference with file path and line numbers
• Read actual source files before documenting
• Never assume behavior without code evidence

ACCURACY_CHECKPOINT

Before writing any documentation:

• “Have I read the actual code?”
• “Are my line number references accurate?”
• “Can I provide a code snippet as evidence?”

Quality Checklist

• All 26 mandatory sections present in correct order
• Quick Navigation by Role included
• Executive Summary with key capabilities
• Business Value with ROI analysis
• User Stories with acceptance criteria (US-XX format)
• Business Requirements use FR-{MOD}-XX format
• Business Rules with state transitions
• Process Flows with diagrams
• System Design with technical decisions log
• Security Architecture with authorization matrix
• Performance Considerations with targets
• Implementation Guide with code examples
• Test Summary table with P0-P3 counts
• Test Data Requirements and fixtures
• Edge Cases Catalog (validation, business, concurrency)
• Regression Impact analysis
• Test cases use TC-{MOD}-XXX format with GIVEN/WHEN/THEN
• Acceptance criteria use ✅/❌ markers
• Troubleshooting uses Symptoms/Causes/Resolution format
• Operational Runbook with deployment checklist
• Roadmap and Dependencies
• Evidence Verification Protocol with audit trail
• Glossary for non-technical stakeholders
• Version History table at end
• All code references verified with actual files
• ASCII diagrams for architecture
• Master index (BUSINESS-FEATURES.md) updated

AI Companion Checklist

• AI companion file created at README.{FeatureName}.ai.md
• AI companion ≤300 lines
• File locations section complete with exact paths
• API contracts include request/response shapes
• All evidence references preserved from full doc
• Patterns section has required (✅) and anti-patterns (❌)