Documentation Epic

User Journey

The Documentation bounded context enables automated generation, validation, and management of project documentation with strong quality guarantees. It combines template-based rendering with AI-powered context extraction to produce consistent, traceable documentation that stays synchronized with codebase changes. The context ensures freshness (≤24h old), template conformance, traceability to source specifications (ADR/PRD/SDS), and idempotent generation for reproducible outputs.

Jobs to be Done & EARS Requirements

Job: Execute GenerateDocumentation

User Story: As a developer or system, I want to generate documentation from project context using registered templates, so that I can maintain up-to-date, consistent documentation across multiple output formats.

EARS Requirement:

• While the system is operational, when a GenerateDocumentation command (CMD-DOC-001) is received with DocumentationRequest containing documentation type (README, API_REFERENCE, ARCHITECTURE, CHANGELOG), output format (MARKDOWN, HTML, PDF), and generation options, the documentation context shall:
  1. Create a DocumentationJob aggregate with unique jobId, status set to pending, and timestamp
  2. Extract holistic project context from Universal Context Service (architecture, business rules, technical stack)
  3. Select the appropriate TemplateSpec from TemplateRegistry based on documentation type
  4. Apply GenerationOptions (theme, sections, examples, diagrams) to customize output
  5. Generate documentation content conforming to template schema per TemplateConformance policy (POL-DOC-002)
  6. Create DocumentationArtifact with generated content, traceability links to ADR/PRD/SDS sources per TraceabilityRequired policy (POL-DOC-003)
  7. Ensure idempotent generation per IdempotentGeneration policy (POL-DOC-004): same input + context produces identical content (exclude GeneratedAt from comparisons)
  8. Update job status to completed with artifact reference, or failed with error details
  9. Emit DocumentationGenerated domain event with jobId and artifactId

Job: Execute ValidateDocumentation

User Story: As a quality assurance system or developer, I want to validate existing documentation against template schemas and quality rules, so that I can ensure correctness and completeness.

EARS Requirement:

• While the system is operational, when a ValidateDocumentation command (CMD-DOC-002) is received with ValidationRequest containing documentation artifact reference or content, the documentation context shall:
  1. Load the DocumentationArtifact to validate
  2. Validate content structure against registered TemplateSpec schema per TemplateConformance policy (POL-DOC-002)
  3. Verify presence of required traceability links to ADR/PRD/SDS sources per TraceabilityRequired policy (POL-DOC-003)
  4. Check document age against FreshnessGuarantee policy (POL-DOC-001): add error issue if >24h old
  5. Create ValidationResult entity with overall status (valid, invalid, warning)
  6. Generate ValidationIssue entities for each problem found with severity (error, warning, info)
  7. Return detailed validation report with issues grouped by category
  8. Emit DocumentationValidated domain event with validationResult

Job: Execute RefreshDocumentation

User Story: As a system or developer, I want to force regeneration of stale or outdated documentation, so that I can maintain synchronization with codebase changes.

EARS Requirement:

• While the system is operational, when a RefreshDocumentation command (CMD-DOC-003) is received with RefreshRequest containing artifactId or “all-stale” flag, the documentation context shall:
  1. Identify target artifacts: specific artifactId or all artifacts violating FreshnessGuarantee policy (POL-DOC-001) with age > 24h
  2. Create new DocumentationJob aggregates for each target with status pending
  3. Trigger full regeneration process using current project context (no incremental updates)
  4. Create a new immutable DocumentationArtifact version with a new artifactId and link to the prior artifact
  5. Update job status to completed with new artifact reference
  6. Emit DocumentationGenerated domain event for each refreshed artifact
  7. Enforce IdempotentGeneration policy (POL-DOC-004): same context produces same content

Job: Execute RegisterTemplate

User Story: As a developer or system administrator, I want to register custom documentation templates, so that I can customize documentation output for specific project needs.

EARS Requirement:

• While the system is operational, when a RegisterTemplate command (CMD-DOC-004) is received with TemplateRegistration containing template name, schema, and Handlebars template content, the documentation context shall:
  1. Validate template syntax and schema definition
  2. Create or update TemplateSpec in TemplateRegistry with unique templateId
  3. Store template metadata: name, version, supported documentation types, output formats
  4. Store template schema defining required sections, fields, and validation rules
  5. Associate template with specific DocumentationType (README, API_REFERENCE, etc.) and OutputFormat (MARKDOWN, HTML, PDF)
  6. Validate that template conforms to SEA (Software Engineering Architecture) documentation standards (see Document Operations Handbook)
  7. Return template registration confirmation with templateId
  8. Emit TemplateRegistered domain event with templateId and metadata

Job: Retrieve GetDocumentation

User Story: As a developer or UI component, I want to retrieve generated documentation artifacts, so that I can display or serve documentation content.

EARS Requirement:

• While the system is operational, when a GetDocumentation query (QRY-DOC-001) is received with DocumentationQuery containing artifactId or filter criteria, the documentation context shall:
  1. Retrieve DocumentationArtifact matching the query criteria
  2. Validate artifact freshness per FreshnessGuarantee policy (POL-DOC-001); return error with policy ID if >24h old
  3. Return artifact content with metadata:
     • Content: Generated documentation in requested format
     • ArtifactId: Unique artifact identifier
     • TemplateId: Template used for generation
     • GeneratedAt: Timestamp of generation
     • TraceabilityLinks: References to ADR/PRD/SDS sources
     • DocumentationType and OutputFormat
  4. Return null or 404 if artifact not found

Job: Retrieve GetJobStatus

User Story: As a monitoring system or UI, I want to check the status of documentation generation jobs, so that I can track progress and handle completion.

EARS Requirement:

• While the system is operational, when a GetJobStatus query (QRY-DOC-002) is received with JobQuery containing jobId, the documentation context shall:
  1. Retrieve DocumentationJob aggregate matching the jobId
  2. Return job status including:
     • JobId: Unique job identifier
     • Status: Current state (pending, processing, completed, failed, cancelled)
     • Progress: Completion percentage (0-100)
     • ArtifactId: Reference to generated artifact (if completed)
     • ErrorDetails: Error information (if failed)
     • CreatedAt and UpdatedAt timestamps
  3. Return null or error if job not found

Job: Retrieve ListTemplates

User Story: As a developer or UI, I want to query available documentation templates, so that I can select appropriate templates for generation.

EARS Requirement:

• While the system is operational, when a ListTemplates query (QRY-DOC-003) is received with TemplateQuery containing optional filters (documentation type, output format), the documentation context shall:
  1. Query TemplateRegistry for available templates
  2. Apply filters if provided: by DocumentationType, OutputFormat, or both
  3. Return list of TemplateSpec entries including:
     • TemplateId: Unique template identifier
     • Name: Human-readable template name
     • Description: Template purpose and usage
     • SupportedTypes: Compatible documentation types
     • SupportedFormats: Compatible output formats
     • Schema: Template structure definition
     • Version: Template version number
  4. Return empty array if no templates match filters

Domain Entities Summary

Root Aggregates

• DocumentationJob: Manages the lifecycle of documentation generation requests with status tracking (pending, processing, completed, failed, cancelled)
• DocumentationArtifact: Represents generated documentation output with content, traceability links, and metadata
• TemplateRegistry: Manages documentation templates with schemas, versions, and compatibility information

Value Objects

• GenerationOptions: Configuration for documentation generation (formatting, themes, sections, examples, diagrams)
• ValidationResult: Quality assurance outcome with overall status
• ValidationIssue: Individual validation problems with severity levels (error, warning, info)
• TraceabilityLink: References to source specifications (ADR, PRD, SDS)
• DocumentationType: Enum of supported types (README, API_REFERENCE, ARCHITECTURE, CHANGELOG)
• OutputFormat: Enum of supported formats (MARKDOWN, HTML, PDF)
• TemplateSpec: Template specification with schema and metadata

Domain Events

• DocumentationGenerated: Emitted when a DocumentationJob completes successfully with jobId, artifactId, documentationType, outputFormat, timestamp
• DocumentationValidated: Emitted when validation finishes with artifactId, validationResult, timestamp
• TemplateRegistered: Emitted when a TemplateSpec is registered with templateId, name, supportedTypes, supportedFormats, timestamp

Policy Rules

• FreshnessGuarantee (POL-DOC-001): Docs older than 24h are flagged during validation/retrieval
• TemplateConformance (POL-DOC-002): All output must conform to registered template schema
• TraceabilityRequired (POL-DOC-003): Generated docs must include ADR/PRD/SDS references
• IdempotentGeneration (POL-DOC-004): Same input + context must produce identical content (GeneratedAt excluded)

Integration Points

• Universal Context Service (SDS-051): Extracts holistic project context (architecture, business rules, technical stack) for documentation generation
• Artifact Engine (SDS-005): Leverages CADSL (Computer-Aided Document Specification Language) for document generation and rendering in multiple formats (see SDS-005)
• Semantic Core Context: Vocabulary alignment and semantic consistency
• CALM CLI Service: Architectural context and compliance status
• Knowledge Graph Service: Provides traceability links and relationships
• Context Context: Provides project context and conversational context for AI-powered generation