Juanjoarranz Ja Agentic Components Feature Docs

Feature Documentation Generation & Verification

Generate comprehensive feature documentation following the GOLD STANDARD template pattern.

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

Summary

Goal: Generate comprehensive single-file feature documentation with verified test cases following the mandatory 26-section GOLD STANDARD template.

Key Principles:

• All 26 sections are mandatory — follow exact order from template
• Every claim must have code evidence (file:line references)
• Use .agents/skills/feature-docs/references/README.ExampleFeature1.md as gold standard reference

MANDATORY 26-SECTION STRUCTURE

All feature documentation MUST follow this section order:

Phase 1: Feature Analysis

Build knowledge model in .vscode/.ai/workspace/analysis/[feature-name].md.

Discovery Areas

1. Domain Entity Discovery: Entities, value objects, enums
2. Workflow Discovery: Commands, Queries, Event Handlers, Background Jobs
3. API Discovery: Controllers, endpoints, DTOs
4. Frontend Discovery: Components, Services, Stores
5. Cross-Service Discovery: Message Bus messages, producers, consumers

Phase 2: Documentation Generation

Generate at .vscode/docs/features/{Module}/detailed-features/README.{FeatureName}.md.

Key Format Examples

Business Requirements (FR-XX):

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

| Aspect          | Details                           |
| --------------- | --------------------------------- |
| **Description** | {What this requirement enables}   |
| **Scope**       | {Who can use / affected entities} |
| **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}`

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-XX):

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

Troubleshooting Format:

#### {Issue Title}

**Symptoms**: {Observable problem}

**Causes**:

1. {Cause 1}
2. {Cause 2}

**Resolution**:

- {Step 1}
- {Step 2}

Permission Matrix:

| Role  | View | Create | Edit | Delete | Special     |
| ----- | :--: | :----: | :--: | :----: | ----------- |
| Admin |  ✅  |   ✅   |  ✅  |   ✅   | Full access |

Phase 2.5: AI Companion Generation

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

Output: .vscode/docs/features/{Module}/detailed-features/README.{FeatureName}.ai.md Template: .agents/skills/feature-docs/references/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: Verification (2-Pass System)

First Pass

For EACH code reference:

• Read actual source file at referenced lines
• Compare character-by-character
• Verify line numbers are accurate
• Log mismatches and correct immediately

Second Pass

• Random sampling (10 code references)
• Cross-reference and TOC verification
• Completeness check

CRITICAL: If Second Pass finds MORE THAN 5 issues, HALT and re-run Phase 3.

Anti-Hallucination Protocols

EVIDENCE_CHAIN_VALIDATION

Before claiming any relationship:

• "I believe X calls Y because..." → show actual code
• "This follows pattern Z because..." → cite specific examples

DOCUMENTATION_ACCURACY_CHECKPOINT

Before writing any documentation:

• "Have I read the actual code that implements this?"
• "Are my line number references accurate and current?"
• "Can I provide a code snippet as evidence?"

Evidence Verification Protocol (QC)

Verification Summary Table

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

Status Markers

• ✅ Verified - Line numbers match actual source
• ⚠️ Stale - Line numbers shifted, content still exists
• ❌ Missing - Referenced code no longer exists

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

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 (❌)

IMPORTANT Task Planning Notes

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed

Converted and distributed by TomeVault — claim your Tome and manage your conversions.