20260213-build-flow¶

📋 Draft

Date: 2026-02-13 Version: 1.0

Overview¶

Create comprehensive documentation explaining the automated build flow that transforms specifications from source files into enhanced, displayable website content. This feature will document the complete pipeline from "git push" to live website deployment, serving as both user education and a demonstration of NextPM's self-referential spec-driven development approach.

Problem¶

Current State: - Users understand they can create specs in engineering/specs/ folder - CI/CD pipeline works correctly but process is opaque to users - No clear documentation showing what happens between "git push" and "website live" - Users may assume it's "auto-publishing" when it's actually build-time processing

Pain Points: - Confusion about timing: Users don't know when their changes will appear - Black box process: No visibility into what the build system actually does - Troubleshooting difficulty: When builds fail, users don't understand the pipeline - Missing educational value: The sophisticated build process isn't showcased as a feature

User Impact¶

Primary Users: - Spec Authors - Need to understand when and how their changes become visible - AI Assistants - Require accurate workflow information for guidance - NextPM Visitors - Want to understand the sophisticated automation behind the scenes

User Benefits: - Clear understanding of git → build → deploy workflow - Transparency into build process timing and steps - Educational value showing advanced CI/CD practices - Troubleshooting guidance when builds fail - Appreciation for the automated enhancement features

Proposed Solution¶

High-Level Approach¶

Create a detailed specification and accompanying documentation that explains:

1. Complete Build Pipeline: From local editing to live website
2. Two Build Environments: Local development vs CI/CD cloud builds
3. Processing Steps: What happens during mkdocs-scripts/build-specs.py
4. Timing Expectations: How long each step takes
5. Visual Enhancements: How specs get transformed with timelines, state badges, etc.
6. Troubleshooting Guide: Common issues and resolution steps

Technical Components¶

Documentation Files: - Primary Spec: This specification (2026-02-13-02-automated-build-flow-documentation.md) - User Guide: mkdocs-docs/engineering/build-workflow.md - Developer Reference: Enhanced section in CLAUDE.md

Content Structure:

Build Flow Documentation
├── Overview: What happens when you push
├── Local vs CI/CD: Two build environments
├── Step-by-Step Pipeline: Detailed process breakdown
├── Enhancement Features: Visual timeline generation, etc.
├── Timing Guide: Expected duration for each step
├── Monitoring: How to watch builds in progress
└── Troubleshooting: Common issues and fixes

Key Features¶

1. Complete Pipeline Visualization

graph LR
    A[Edit Spec] --> B[Git Commit]
    B --> C[Git Push]
    C --> D[GitHub Actions Trigger]
    D --> E[Setup Environment]
    E --> F[Run build-specs.py]
    F --> G[Process Enhancements]
    G --> H[MkDocs Build]
    H --> I[Deploy to Azure]
    I --> J[Live Website]

2. Detailed Step Breakdown - Step 1: GitHub Actions checkout and setup (30s) - Step 2: Python dependencies installation (20s) - Step 3: Spec processing and enhancement (10s) - Step 4: MkDocs site generation (15s) - Step 5: Azure Static Web Apps deployment (30s) - Total: ~1.5-2 minutes from push to live

3. Enhancement Process Explanation - YAML frontmatter parsing for state management - Visual timeline injection with git commit data - State badge generation with CSS classes - Search index updating with spec content - Dashboard statistics recalculation - Navigation menu auto-generation

4. Environment Comparison | Aspect | Local Build | CI/CD Build | |--------|-------------|-------------| | Trigger | Manual command | Git push | | Environment | Your computer | GitHub Ubuntu | | Purpose | Development/testing | Production deployment | | Output | Local preview | Live website | | Duration | 5-10 seconds | 1.5-2 minutes |

Implementation Plan¶

Phase 1: Core Documentation 1. Create primary specification (this document) 2. Write comprehensive user guide 3. Enhance CLAUDE.md with build details 4. Test documentation with local builds

Phase 2: Visual Enhancements 1. Add Mermaid diagrams showing pipeline flow 2. Create timing breakdown with expected durations 3. Include screenshots of GitHub Actions in progress 4. Add troubleshooting flowchart

Phase 3: Integration 1. Link from main README.md 2. Add to Engineering section navigation 3. Reference from spec templates 4. Update existing documentation for consistency

Acceptance Criteria¶

Documentation Quality: - [ ] Complete pipeline explanation from edit to deployment - [ ] Clear distinction between local vs CI/CD builds - [ ] Accurate timing expectations for each step - [ ] Visual diagrams showing process flow - [ ] Troubleshooting guide with common issues

User Understanding: - [ ] New users can understand when changes will be live - [ ] Spec authors know how to monitor build progress - [ ] AI assistants have accurate workflow information - [ ] Troubleshooting guidance resolves common problems

Self-Referential Demonstration: - [ ] This spec itself demonstrates the process it documents - [ ] Commit linking shows spec → implementation traceability - [ ] Visual timeline displays the development progression - [ ] Search functionality includes this documentation

Technical Requirements¶

Documentation Standards: - Follow NextPM markdown conventions - Include Mermaid diagrams for complex processes - Use consistent terminology throughout - Link to relevant GitHub Actions and Azure documentation

Integration Points: - Reference from CLAUDE.md build section - Link from main project README - Include in Engineering navigation menu - Connect to existing spec workflow documentation

Maintenance: - Update when build process changes - Keep timing estimates current - Maintain accuracy of GitHub Actions references - Ensure troubleshooting remains relevant

Dependencies¶

Required Information: - Current GitHub Actions workflow files - Azure Static Web Apps deployment process - mkdocs-scripts/build-specs.py functionality - Typical build timing measurements

Related Documentation: - README.md project overview - CLAUDE.md development guidelines - Existing spec templates and examples

Risks and Mitigations¶

Success Metrics¶

User Understanding: - Reduced confusion about build timing - Faster troubleshooting of build issues - Improved confidence in the development workflow

Documentation Quality: - Complete coverage of build pipeline - Accurate process descriptions - Helpful troubleshooting guidance

Self-Referential Value: - Demonstrates NextPM's transparency principles - Shows advanced automation capabilities - Provides concrete example of spec-driven development

Implementation Notes¶

Content Priorities: 1. Essential: Basic pipeline understanding 2. Important: Local vs CI/CD distinction 3. Nice-to-have: Advanced troubleshooting scenarios

Writing Approach: - Start with user journey (edit → live website) - Include specific examples and commands - Use visual aids for complex processes - Provide both overview and detailed reference

Testing Plan: - Verify all commands and references - Test with fresh users for clarity - Ensure accuracy of timing estimates - Validate troubleshooting guidance

Change History¶

Version 1.0 - 2026-02-13¶

• Initial spec creation for automated build flow documentation
• Complete pipeline analysis and documentation requirements
• Self-referential demonstration of spec-driven development process