home / skills / duc01226 / easyplatform / business-feature-docs

business-feature-docs skill

safe

/docs/templates/skills/business-feature-docs

This skill creates and updates EasyPlatform business feature documentation in the designated module folder using GOLD STANDARD templates to ensure thorough,

npx playbooks add skill duc01226/easyplatform --skill business-feature-docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

16.5 KB

---
name: business-feature-docs
description: Create or update EasyPlatform business feature documentation in docs/business-features/{Module}/. Use when asked to document a feature, create module docs, update feature documentation, or add detailed feature specs. Triggers on "feature docs", "business feature documentation", "module documentation", "document feature", "update feature docs".
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task, TodoWrite
---

<!-- 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:

| #   | Section                    | Stakeholder Focus      |
| --- | -------------------------- | ---------------------- |
| 1   | Executive Summary          | PO, BA                 |
| 2   | Business Value             | PO, BA                 |
| 3   | Business Requirements      | PO, BA                 |
| 4   | Business Rules             | BA, Dev                |
| 5   | Process Flows              | BA, Dev, Architect     |
| 6   | Design Reference           | BA, UX, Dev            |
| 7   | System Design              | Dev, Architect         |
| 8   | Architecture               | Dev, Architect         |
| 9   | Domain Model               | Dev, Architect         |
| 10  | API Reference              | Dev, Architect         |
| 11  | Frontend Components        | Dev                    |
| 12  | Backend Controllers        | Dev                    |
| 13  | Cross-Service Integration  | Dev, Architect         |
| 14  | Security Architecture      | Dev, Architect         |
| 15  | Performance Considerations | Dev, Architect, DevOps |
| 16  | Implementation Guide       | Dev                    |
| 17  | Test Specifications        | QA                     |
| 18  | Test Data Requirements     | QA                     |
| 19  | Edge Cases Catalog         | QA, Dev                |
| 20  | Regression Impact          | QA                     |
| 21  | Troubleshooting            | Dev, QA, DevOps        |
| 22  | Operational Runbook        | DevOps                 |
| 23  | Roadmap and Dependencies   | PO, BA                 |
| 24  | Related Documentation      | All                    |
| 25  | Glossary                   | PO, BA                 |
| 26  | Version History            | All                    |

---

## 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

```markdown
| 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)

```markdown
#### 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)

```markdown
#### 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

```markdown
### 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

```markdown
### 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

```markdown
### 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)**:

```markdown
| 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**:

```markdown
#### 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

```markdown
### 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

```markdown
### 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

```markdown
## 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

```markdown
### 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

```markdown
## 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)

| Section         | Content                            | Source from Full Doc      |
| --------------- | ---------------------------------- | ------------------------- |
| Context         | Purpose, entities, service         | Executive Summary         |
| File Locations  | Exact paths to all key files       | Implementation Guide      |
| Domain Model    | Properties, expressions            | Domain Model              |
| API Contracts   | Endpoints, request/response shapes | API Reference             |
| Business Rules  | Validation, state transitions      | Business Rules            |
| Patterns        | Required ✅ / Anti-patterns ❌       | Architecture              |
| Integration     | Events, dependencies               | Cross-Service Integration |
| Security        | Authorization matrix               | Security Architecture     |
| Test Scenarios  | Key GIVEN/WHEN/THEN cases          | Test Specifications       |
| Quick Reference | Decision tree, code snippets       | Implementation Guide      |

### 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:
    ```markdown
    | **{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 (❌)

Overview

This skill creates or updates EasyPlatform business feature documentation using the GOLD STANDARD 26-section template and produces an AI-optimized companion file. It places files in docs/business-features/{Module}/ and ensures module index and master index updates when needed. Use it to generate full, stakeholder-focused feature specs that include evidence links to source code and an AI companion for quick agent use.

How this skill works

The skill detects the target module from user input, feature name, or by searching the codebase for entities, commands, queries and controllers. It reads existing docs (BUSINESS-FEATURES.md, module INDEX.md and README.md) to determine what to create or update, then generates a detailed feature document with the required 26 sections and an AI companion file. It outputs exact file paths and embeds evidence references to source files for verification.

When to use it

When asked to document a new business feature end-to-end
When updating or expanding existing module or feature documentation
When you need an AI-optimized companion summary for agents
When creating module-level indexes and navigation (INDEX.md, README.md)
When preparing documentation that must include code evidence and runbooks

Best practices

Always run module detection first: user-specified module > implied > code search
Read existing BUSINESS-FEATURES.md and module INDEX/README before adding files
Include evidence references in the form `FilePath:LineRange` for key claims
Follow the exact 26-section order to satisfy stakeholder needs and audits
Produce the AI companion alongside the full doc and keep it ≤300 lines

Example use cases

Create a new detailed-features/README.PaymentProcessing.md for a payments feature
Update Business Rules, Process Flows and Test Specifications for an existing module
Generate README.Feature.ai.md that lists file paths, API contracts and GIVEN/WHEN/THEN tests
Add Operational Runbook and Monitoring thresholds for a new service
Populate Domain Model, API Reference and Implementation Guide with evidence links

FAQ

Can the skill update the master BUSINESS-FEATURES.md index?

Yes. After creating or updating module docs it updates the master index to reflect new modules or features.

What code locations does the skill inspect for evidence?

It inspects standard paths such as src/Services/{Module}/{Module}.Domain/Entities, Application/UseCaseCommands, Service/Controllers and frontend apps under src/Frontend.