EasyPlatform Business Feature Documentation

<!-- SOURCE OF TRUTH: docs/​templates/​skills/​business-feature-docs/​SKILL.md --> <!-- Synced to: .claude/​skills/ and .github/​skills/ -->

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/​Frontend/​apps/​playground-{module}/ or src/​Frontend/​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 (❌)