@windagency/valora 2.0.1

package/data/prompts/01_onboard/analyze-documentation-requirements.md

@@ -0,0 +1,543 @@
+---
+id: onboard.analyze-documentation-requirements
+version: 1.0.0
+category: onboard
+experimental: true
+name: Analyse Documentation Requirements
+description: Plan documentation structure, identify diagram requirements, and establish cross-references
+tags:
+  - documentation
+  - planning
+  - analysis
+model_requirements:
+  min_context: 128000
+  recommended:
+    - claude-haiku-4.5
+agents:
+  - lead
+dependencies:
+  requires:
+    - context.use-modern-cli-tools
+    - context.load-documentation-context
+inputs:
+  - name: prd
+    description: Parsed PRD document from context stage
+    type: object
+    required: true
+  - name: functional
+    description: Parsed FUNCTIONAL document from context stage
+    type: object
+    required: true
+  - name: backlog
+    description: Parsed BACKLOG document from context stage
+    type: object
+    required: true
+  - name: codebase
+    description: Codebase context from context stage
+    type: object
+    required: true
+  - name: metadata
+    description: Project metadata from context stage
+    type: object
+    required: true
+  - name: domain_filter
+    description: Domain filter from --domain argument
+    type: string
+    required: false
+  - name: doc_type_filter
+    description: Document type filter from --doc-type argument
+    type: string
+    required: false
+outputs:
+  - documentation_plan
+  - diagram_requirements
+  - cross_references
+  - domain_assignments
+tokens:
+  avg: 8000
+  max: 15000
+  min: 4000
+---
+
+# Analyse Documentation Requirements
+
+## Objective
+
+Analyse loaded context to create a comprehensive documentation plan, identify required diagrams, establish cross-references between documents, and assign domain responsibilities.
+
+## CRITICAL: Output Format Requirement
+
+**You MUST output ONLY valid JSON. Do NOT output markdown, do NOT wrap in code blocks, do NOT add any text before or after the JSON.**
+
+Your response must be a single JSON object matching the schema defined in the "Output Format" section at the end of this prompt.
+
+## Instructions
+
+### Step 1: Determine Documentation Scope
+
+Based on domain filter and codebase analysis:
+
+**If `domain_filter` is "all" or not provided**:
+
+- Plan all 15 documents
+- Enable infrastructure, backend, and frontend domains
+
+**If `domain_filter` is specific**:
+
+- Filter to requested domain only
+- Infrastructure: 6 documents
+- Backend: 5 documents
+- Frontend: 4 documents
+
+**If `doc_type_filter` is provided**:
+
+- Generate only the specified document type
+- Match against document names (HLD, API, ARCHITECTURE, etc.)
+
+### Step 2: Plan Infrastructure Documentation (6 files)
+
+For each infrastructure document, plan content based on context:
+
+**HLD.md (High-Level Design)**:
+
+- Content: System overview, C4 Context diagram, C4 Container diagram
+- Sources: PRD architecture decisions, technology stack, NFRs
+- Diagrams: C4 Context, C4 Container
+- Key sections: Technology stack, system boundaries, external integrations
+
+**CONTAINER.md (Container Architecture)**:
+
+- Content: Docker configuration, image management, compose setup
+- Sources: Dockerfile, docker-compose.yml, container registry config
+- Diagrams: Container topology, build pipeline
+- Key sections: Image structure, environment configuration, volumes
+
+**DEPLOYMENT.md (Deployment Guide)**:
+
+- Content: Deployment processes, environments, CI/CD pipelines
+- Sources: CI config, deployment scripts, environment configs
+- Diagrams: Deployment pipeline, environment topology
+- Key sections: Release process, rollback procedures, health checks
+
+**LOGGING.md (Observability)**:
+
+- Content: Logging strategy, monitoring, alerting, tracing
+- Sources: Logging config, monitoring setup, alert rules
+- Diagrams: Observability architecture, log flow
+- Key sections: Log levels, metrics, alerts, dashboards
+
+**LZ.md (Landing Zone)**:
+
+- Content: Network architecture, security boundaries, cloud resources
+- Sources: Infrastructure code, network config, security policies
+- Diagrams: Network topology, security zones
+- Key sections: VPC structure, IAM policies, resource groups
+
+**WORKFLOW.md (Development Workflow)**:
+
+- Content: Development processes, branching strategy, release flow
+- Sources: Git config, PR templates, CI/CD config
+- Diagrams: Git flow, release pipeline
+- Key sections: Branch naming, PR process, code review
+
+### Step 3: Plan Backend Documentation (5 files)
+
+**ARCHITECTURE.md (Backend Architecture)**:
+
+- Content: Service design, patterns, dependencies, layering
+- Sources: Backend code structure, service files, dependency graph
+- Diagrams: Component diagram, dependency graph, layer diagram
+- Key sections: Service boundaries, patterns used, error handling
+
+**API.md (API Documentation)**:
+
+- Content: Endpoint documentation, request/response schemas, auth
+- Sources: Route files, controller code, API schemas
+- Diagrams: Sequence diagrams for key flows
+- Key sections: Endpoints by resource, authentication, error codes
+
+**DATA.md (Data Architecture)**:
+
+- Content: Data models, database design, migrations, relationships
+- Sources: Schema files, model definitions, migration scripts
+- Diagrams: ERD, data flow diagram
+- Key sections: Entity definitions, relationships, indexing strategy
+
+**TESTING.md (Backend Testing)**:
+
+- Content: Testing strategy, coverage, patterns, fixtures
+- Sources: Test files, test configuration, coverage reports
+- Diagrams: Test pyramid, coverage map
+- Key sections: Unit tests, integration tests, test data management
+
+**CODING-ASSERTIONS.md (Backend Standards)**:
+
+- Content: Coding standards, validation rules, assertions
+- Sources: Lint config, code style guides, validation utilities
+- Key sections: Naming conventions, error handling, validation patterns
+
+### Step 4: Plan Frontend Documentation (4 files)
+
+**ARCHITECTURE.md (Frontend Architecture)**:
+
+- Content: Component hierarchy, state management, routing
+- Sources: Component files, store configuration, route definitions
+- Diagrams: Component tree, state flow, route hierarchy
+- Key sections: Component patterns, state management, data fetching
+
+**DESIGN.md (Design System)**:
+
+- Content: UI components, styling patterns, design tokens
+- Sources: Component library, style files, theme configuration
+- Diagrams: Component catalogue, colour palette, typography
+- Key sections: Design tokens, component variants, accessibility
+
+**TESTING.md (Frontend Testing)**:
+
+- Content: Component testing, E2E testing, visual regression
+- Sources: Test files, E2E configuration, snapshot tests
+- Diagrams: Test coverage map
+- Key sections: Component tests, E2E scenarios, mocking strategy
+
+**CODING-ASSERTIONS.md (Frontend Standards)**:
+
+- Content: Frontend coding standards, accessibility rules
+- Sources: Lint config, accessibility config, style guides
+- Key sections: Component patterns, accessibility checklist, performance
+
+### Step 5: Identify Diagram Requirements
+
+For each document, specify required diagrams:
+
+**Diagram types**:
+
+- **C4 Context**: System context and external actors
+- **C4 Container**: Container-level architecture
+- **C4 Component**: Internal component structure
+- **Sequence**: Request/response flows
+- **ERD**: Entity relationships
+- **Flowchart**: Process flows
+- **State**: State transitions
+- **Network**: Network topology
+
+**For each diagram specify**:
+
+- Diagram ID (unique identifier)
+- Diagram type (from above list)
+- Target document
+- Description of what to illustrate
+- Key elements to include
+- Mermaid syntax guidance
+
+### Step 6: Establish Cross-References
+
+Map relationships between documents:
+
+**Cross-reference types**:
+
+- **Depends on**: Document A requires understanding of Document B
+- **Related to**: Documents cover overlapping topics
+- **See also**: Optional additional context
+- **Implements**: Technical doc implements concept from another
+
+**Required cross-references**:
+
+- HLD → CONTAINER, DEPLOYMENT (infrastructure relationships)
+- API → DATA (endpoint to data model mapping)
+- Backend ARCHITECTURE → API (service to endpoint mapping)
+- Frontend ARCHITECTURE → Backend API (integration points)
+- All TESTING docs → respective ARCHITECTURE docs
+
+### Step 7: Assign Domain Responsibilities
+
+Determine which domains to generate based on:
+
+**Criteria for domain enablement**:
+
+- `domain_filter` argument value
+- Codebase structure (has_frontend, has_backend, has_infrastructure)
+- Prerequisites available
+
+**Assignment logic**:
+
+```
+infrastructure_enabled = (domain_filter in ["all", "infrastructure"]) AND has_infrastructure_code
+backend_enabled = (domain_filter in ["all", "backend"]) AND has_backend_code
+frontend_enabled = (domain_filter in ["all", "frontend"]) AND has_frontend_code
+```
+
+## Output Format
+
+```json
+{
+	"documentation_plan": {
+		"infrastructure": {
+			"enabled": true,
+			"documents": [
+				{
+					"id": "INFRA-HLD",
+					"filename": "HLD.md",
+					"title": "High-Level Design",
+					"target_path": "knowledge-base/infrastructure/HLD.md",
+					"priority": 1,
+					"content_outline": [
+						"Purpose and scope",
+						"System context",
+						"Technology stack overview",
+						"C4 Context diagram",
+						"C4 Container diagram",
+						"Non-functional requirements mapping",
+						"External integrations",
+						"Troubleshooting",
+						"Best practices",
+						"Changelog"
+					],
+					"source_references": {
+						"prd_sections": ["Technology Stack", "NFRs", "Architecture Decisions"],
+						"codebase_files": ["package.json", "docker-compose.yml"]
+					},
+					"estimated_sections": 10,
+					"estimated_diagrams": 2
+				}
+			]
+		},
+		"backend": {
+			"enabled": true,
+			"documents": [
+				{
+					"id": "BE-ARCH",
+					"filename": "ARCHITECTURE.md",
+					"title": "Backend Architecture",
+					"target_path": "knowledge-base/backend/ARCHITECTURE.md",
+					"priority": 1,
+					"content_outline": [
+						"Purpose and scope",
+						"Architecture overview",
+						"Component diagram",
+						"Service design patterns",
+						"Dependency management",
+						"Error handling strategy",
+						"Troubleshooting",
+						"Best practices",
+						"Changelog"
+					],
+					"source_references": {
+						"prd_sections": ["Technical Requirements", "Architecture Decisions"],
+						"codebase_files": ["src/server/", "src/services/"]
+					},
+					"estimated_sections": 9,
+					"estimated_diagrams": 3
+				}
+			]
+		},
+		"frontend": {
+			"enabled": true,
+			"documents": [
+				{
+					"id": "FE-ARCH",
+					"filename": "ARCHITECTURE.md",
+					"title": "Frontend Architecture",
+					"target_path": "knowledge-base/frontend/ARCHITECTURE.md",
+					"priority": 1,
+					"content_outline": [
+						"Purpose and scope",
+						"Component hierarchy",
+						"State management",
+						"Routing structure",
+						"Data fetching patterns",
+						"Troubleshooting",
+						"Best practices",
+						"Changelog"
+					],
+					"source_references": {
+						"prd_sections": ["User Stories", "Functional Requirements"],
+						"codebase_files": ["src/client/", "src/components/"]
+					},
+					"estimated_sections": 8,
+					"estimated_diagrams": 3
+				}
+			]
+		}
+	},
+	"diagram_requirements": {
+		"infrastructure": [
+			{
+				"id": "DIAG-C4-CONTEXT",
+				"type": "c4_context",
+				"target_document": "INFRA-HLD",
+				"title": "System Context Diagram",
+				"description": "High-level view of system and external actors",
+				"elements": ["System", "Users", "External Services", "Databases"],
+				"mermaid_type": "C4Context"
+			},
+			{
+				"id": "DIAG-C4-CONTAINER",
+				"type": "c4_container",
+				"target_document": "INFRA-HLD",
+				"title": "Container Diagram",
+				"description": "Container-level architecture showing API, Web App, Database",
+				"elements": ["API Container", "Web App Container", "Database", "Cache"],
+				"mermaid_type": "C4Container"
+			}
+		],
+		"backend": [
+			{
+				"id": "DIAG-BE-COMPONENT",
+				"type": "component",
+				"target_document": "BE-ARCH",
+				"title": "Backend Component Diagram",
+				"description": "Internal structure of backend services",
+				"elements": ["Controllers", "Services", "Repositories", "Middleware"],
+				"mermaid_type": "flowchart"
+			},
+			{
+				"id": "DIAG-ERD",
+				"type": "erd",
+				"target_document": "BE-DATA",
+				"title": "Entity Relationship Diagram",
+				"description": "Data model relationships",
+				"elements": ["User", "Task", "Project", "Comment"],
+				"mermaid_type": "erDiagram"
+			},
+			{
+				"id": "DIAG-API-SEQ",
+				"type": "sequence",
+				"target_document": "BE-API",
+				"title": "API Request Flow",
+				"description": "Typical API request/response sequence",
+				"elements": ["Client", "API Gateway", "Service", "Database"],
+				"mermaid_type": "sequenceDiagram"
+			}
+		],
+		"frontend": [
+			{
+				"id": "DIAG-FE-COMPONENT",
+				"type": "component",
+				"target_document": "FE-ARCH",
+				"title": "Component Hierarchy",
+				"description": "Frontend component tree structure",
+				"elements": ["App", "Layout", "Pages", "Components"],
+				"mermaid_type": "flowchart"
+			},
+			{
+				"id": "DIAG-FE-STATE",
+				"type": "state",
+				"target_document": "FE-ARCH",
+				"title": "State Management Flow",
+				"description": "State flow through the application",
+				"elements": ["Actions", "Store", "Selectors", "Components"],
+				"mermaid_type": "flowchart"
+			}
+		]
+	},
+	"cross_references": {
+		"INFRA-HLD": {
+			"depends_on": [],
+			"related_to": ["INFRA-CONTAINER", "INFRA-DEPLOYMENT"],
+			"see_also": ["BE-ARCH", "FE-ARCH"]
+		},
+		"BE-API": {
+			"depends_on": ["BE-ARCH"],
+			"related_to": ["BE-DATA"],
+			"see_also": ["FE-ARCH"]
+		},
+		"FE-ARCH": {
+			"depends_on": [],
+			"related_to": ["FE-DESIGN"],
+			"see_also": ["BE-API"]
+		}
+	},
+	"domain_assignments": {
+		"infrastructure": true,
+		"backend": true,
+		"frontend": true
+	},
+	"generation_order": [
+		{ "domain": "infrastructure", "parallel_group": 1 },
+		{ "domain": "backend", "parallel_group": 1 },
+		{ "domain": "frontend", "parallel_group": 1 }
+	],
+	"statistics": {
+		"total_documents": 15,
+		"total_diagrams": 12,
+		"total_cross_references": 24,
+		"estimated_generation_time_minutes": 15
+	}
+}
+```
+
+## Success Criteria
+
+- ✅ Documentation plan covers all enabled domains
+- ✅ Each document has clear content outline
+- ✅ Diagram requirements specified with Mermaid types
+- ✅ Cross-references established between related documents
+- ✅ Domain assignments reflect filter and codebase
+- ✅ Generation order enables parallel execution
+- ✅ Source references map to available context
+
+## Error Handling
+
+### Insufficient Context for Domain
+
+**Issue**: Cannot plan documentation for a domain due to missing context
+
+**Action**:
+
+1. Disable that domain in assignments
+2. Warn user about limited scope
+3. Proceed with available domains
+
+### Conflicting Requirements
+
+**Issue**: Filter requests domain but codebase lacks relevant code
+
+**Action**:
+
+1. Warn user about mismatch
+2. Generate documentation from prerequisites only
+3. Flag sections that need manual completion
+
+## Notes
+
+- This prompt focuses on PLANNING and ANALYSIS only
+- No documentation content is generated here
+- Output structures work for the three parallel generation prompts
+- Diagram requirements include Mermaid syntax guidance
+- Cross-references enable link validation in review stage
+
+## CRITICAL: Complete Output Structure Required
+
+**You MUST include ALL THREE domains in your output, even if some are disabled:**
+
+- `documentation_plan` MUST contain keys: `infrastructure`, `backend`, `frontend`
+- `diagram_requirements` MUST contain keys: `infrastructure`, `backend`, `frontend`
+- `domain_assignments` MUST contain keys: `infrastructure`, `backend`, `frontend`
+
+**For disabled domains**, use this structure:
+
+```json
+{
+  "documentation_plan": {
+    "infrastructure": { "enabled": false, "documents": [] },
+    "backend": { "enabled": false, "documents": [] },
+    "frontend": { "enabled": true, "documents": [...] }
+  },
+  "diagram_requirements": {
+    "infrastructure": [],
+    "backend": [],
+    "frontend": [...]
+  },
+  "domain_assignments": {
+    "infrastructure": false,
+    "backend": false,
+    "frontend": true
+  }
+}
+```
+
+**DO NOT omit any domain keys. The pipeline requires all three domains to be present.**
+
+## REMINDER: Output Requirements
+
+**Output ONLY the JSON object. No markdown, no code blocks, no explanatory text. Start directly with `{` and end with `}`.**