Attribution Requirements:

When sharing content publicly (repositories, documentation, articles): Include the full attribution above
When working with AI systems (ChatGPT, Claude, etc.): Attribution not required during collaboration sessions
When distributing or modifying the methodology: Full CC BY-SA 4.0 compliance required

For optimal machine parsing, use the METHODOLOGY.XML document as context, while the current document provides human-readable formatting for documentation review.

For structured language with explicit validation gates, see PAG Documentation.

PAG Documents: PAG-COLLABORATION.md | PAG-AGENT-ORCHESTRATION.md

Project Documentation Methodology

Core Architectural Principles

Foundational Philosophy

Architectural Minimalism with Deterministic Reliability: Every line of code must earn its place through measurable value. Build systems that work predictably in production, not demonstrations of sophistication.

Code Architecture Principles

Separation of Concerns (SoC):

Each module has single, well-defined responsibility
Strict modular boundaries with clear interfaces
Recognize when separation would harm rather than help architecture
Centralized main entry points with modular project layout

Deterministic Operations:

Synchronous, predictable behavior over async complexity
Long-runtime stability over cutting-edge patterns
Production stability over development convenience
Cross-platform considerations in design decisions

Performance-Driven Decisions:

Choose based on workload requirements, not popular trends
Apply optimizations only to proven bottlenecks with measurable impact
Avoid premature optimization that clutters codebase
Maintain performance baselines and regression detection

Code Quality Standards:

Files never exceed 150 lines (split into separate modules if needed)
Self-explanatory code without comments
Preserve readability and maintainability as primary concerns
KISS and DRY principles expertly applied
Reuse existing functions before creating new ones

Error Handling Philosophy:

Robust without over-engineering
Implement what's necessary for production reliability
Avoid handling every possible edge case
Graceful failure modes and resource cleanup

Feature Control:

Resist feature bloat and complexity creep
Every addition must serve core project purpose
Surgical approach: target exact problem with minimal code
Multi-language use only when justified by measurable gains

Web Development Adaptations:

No inlining: Styles to separate files, handlers to named functions, configurations as constants
File size accommodation: Components ≤250 lines (DOM complexity), modules ≤150 lines
Async operations: API calls, user interactions, data fetching only
Error boundaries: Network operations, user inputs, third-party integrations
File colocation: Component.jsx, Component.module.css, Component.test.js
Component splitting: Multiple purposes or testing difficulty
Implementation protocol: Request architectural compliance clarification for code generation tasks

Structured Instruction Formats

This methodology can be expressed in multiple formats depending on your AI environment:

Prose (Markdown/XML): Natural language with structural headings. Works well with web-based AI interfaces where you paste instructions directly.

PAG (Pattern Abstract Grammar): Structured language using explicit keywords like READ, WRITE, SET, VALIDATE. Reduces interpretive ambiguity through code-like patterns. Particularly effective for CLI-based AI agents.

The principles remain identical; the format adapts to the interface.

PAG Constraint Equivalents

Methodology constraints translate directly to PAG syntax:

CONSTRAINT file_size_limit:
    SET max_lines = 150
    ALWAYS: Split files exceeding max_lines INTO separate_modules
    NEVER: Create monolithic files

CONSTRAINT separation_of_concerns:
    FOR EACH module IN codebase:
        VALIDATE module HAS single_responsibility
        VALIDATE module HAS clear_interfaces
    END FOR

CONSTRAINT deterministic_operations:
    ALWAYS: Prefer synchronous operations
    NEVER: Introduce async complexity without justification

These explicit patterns may reduce interpretation variance compared to prose equivalents.

Basic Must-Haves (Phase 0 - Always First)

Every project, regardless of size, must establish these foundational systems before any feature development:

Benchmarking Suite

Core Framework: Performance measurement with component isolation
Regression Detection: Compare against previous results, fail on performance drops
Baseline Management: Save and track performance baselines over time
JSON Output: Structured data for automated analysis and CI integration
Timeline Tracking: Historical performance data across project evolution

CI/CD Infrastructure

Release Workflows: Automated versioning, building, and deployment
Regression Detection: Benchmark comparison on every commit/PR
Quality Gates: Block merges that fail performance or quality thresholds
Automated Testing: Run full test suite on code changes

Core Architecture

Centralized Entry Points: Single main module that orchestrates everything
Configuration Management: Externalized settings with validation
Centralized Logging: Error handling and diagnostic output with JSON integration
Dependency Injection: Clean separation and testable components

Testing Infrastructure

Test Suite: Unit and integration tests for all components
Stress Testing: Load and boundary condition validation
Test Data Management: Reproducible test scenarios and cleanup
Coverage Tracking: Ensure adequate test coverage before releases

Documentation System

Automated Generation: Extract documentation from code and structure
Architecture Documentation: System design and component relationships
API Documentation: Interface specifications and usage examples
Performance Documentation: Benchmark results and optimization guides

Critical: These systems must be operational before writing any application logic. They become the foundation that enables rapid, confident development.

Phase 0 in PAG Format

# PHASE 0: Infrastructure Foundation

## PURPOSE
Establish foundational systems for reliable development.

## DELIVERABLES
- Benchmarking suite WITH component isolation
- Regression detection WITH baseline management
- GitHub workflows FOR release automation
- Test suite infrastructure FOR unit AND stress testing
- Documentation generation system
- Centralized entry points AND configuration

## VALIDATION GATE
✅ Benchmark suite measures all core operations
✅ CI fails on performance regressions
✅ Test suite runs automatically on commits
✅ Documentation generates from current codebase
✅ All systems integrated and operational

The Documentation Building Process

Step 1: Project Decomposition

Ask yourself:

What does "finished" look like?
What are the major pieces that need to exist?
What depends on what?
Where are the natural stopping points?

Create sections based on dependencies:

Major Piece A → Major Piece B → Major Piece C
     ↓              ↓              ↓
  Sub-tasks     Sub-tasks     Sub-tasks

Step 2: Phase Creation

Phase 0 is mandatory for all projects:

Benchmarking suite with regression detection
GitHub workflows for releases and quality gates
Test infrastructure (unit + stress testing)
Documentation generation system
Centralized architecture setup

Group remaining work into phases based on:

Dependency chains: Things that must happen in sequence
Logical groupings: Related functionality that makes sense together
Natural checkpoints: Places where you can validate progress

Phase Template (Prose):

## Phase N: [Descriptive Name] ([Status])

### Purpose: [Why this phase exists - what it enables]

### Dependencies: [What must be complete first]

### Deliverables:
- [ ] [Specific output or component]
- [ ] [Another specific output]

### Completion Criteria:
- [ ] [How you know it's done]
- [ ] [Quality threshold or validation method]

### Architectural Compliance:
- [ ] **SoC VALIDATION**: Each module single responsibility, clear boundaries
- [ ] **FILE SIZE COMPLIANCE**: All files ≤150 lines or properly modularized
- [ ] **DRY ENFORCEMENT**: No duplicate code, existing functions reused
- [ ] **PERFORMANCE INTEGRATION**: Benchmarks operational, gates passing

**PHASE RESULTS:**
- [Component]: [outcome/metric] [status]
- [Component]: [outcome/metric] [status]

Phase Template (PAG):

# PHASE N: [Descriptive Name]

## PURPOSE
[Why this phase exists - what it enables]

## DEPENDENCIES
[What must be complete first]

## DELIVERABLES
- [Specific output or component]
- [Another specific output]

## VALIDATION GATE
✅ [How you know it's done]
✅ [Quality threshold or validation method]

## CONSTRAINTS
ALWAYS: Maintain single responsibility per module
ALWAYS: Keep files under 150 lines
NEVER: Duplicate existing function logic
NEVER: Skip benchmark integration

## PHASE RESULTS
- [Component]: [outcome/metric] [status]

Step 3: Task Breakdown

For each deliverable, define:

Specific action: What exactly needs to be done
Output: What will exist when complete
Success criteria: How to verify completion
Integration points: How it connects to other work

Task Template:

### [Component/Output Name]
- [ ] [Action producing specific outcome]
- [ ] [Validation or testing requirement]
- [ ] **[CONNECTION]**: [How this integrates with other components]
- [ ] **[COMPLETE WHEN]**: [Specific, measurable criteria]
- [ ] **[COMPLIANCE CHECK]**: [DRY/KISS/Architecture validation]
- [ ] **[PERFORMANCE GATE]**: [Benchmark threshold to meet]

Step 4: Progress Tracking System

Status Indicators:

✅ COMPLETED: Done and validated
🔒 BLOCKED: Cannot proceed due to dependency
📋 READY: Dependencies met, can start
⚠️ UNCERTAIN: Need clarification or decision

Progress Metrics:

**PHASE STATUS:**
- Component A: [result/metric] ✅
- Component B: [current state] ⚠️
- Overall: [description of current state]

Step 5: Quality Gates

Define completion criteria that prevent moving forward with incomplete work:

Does the output match what was specified?
Can the next phase actually use this output?
Is there enough documentation for future reference?
Are there any obvious issues that need fixing?

Systematic Enforcement Framework

Mandatory Checkpoints (Per Phase):

**Architectural Compliance:**

- [ ] **SoC VALIDATION**: Each module single responsibility, clear boundaries
- [ ] **DETERMINISTIC BEHAVIOR**: Synchronous operations, predictable outcomes
- [ ] **FILE SIZE COMPLIANCE**: All files ≤150 lines or properly modularized
- [ ] **DRY ENFORCEMENT**: No duplicate code, existing functions reused
- [ ] **KISS VALIDATION**: Minimal complexity, surgical implementations
- [ ] **CONFIG CENTRALIZATION**: No hardcoded values outside constants
- [ ] **PERFORMANCE INTEGRATION**: Benchmarks operational, gates passing
- [ ] **PRODUCTION READINESS**: Error handling, resource cleanup, cross-platform

**Code Quality Gates:**

- [ ] Self-explanatory naming, no comments needed
- [ ] Performance characteristics match workload requirements
- [ ] Every addition serves core project purpose
- [ ] Regression detection prevents performance degradation
- [ ] Resource utilization within defined thresholds

**⚠️ PROGRESSION BLOCKER**: Any failed checkpoint blocks phase advancement

PAG Validation Gate Equivalent:

## VALIDATION GATE: Phase Completion
✅ SoC: Each module has single responsibility
✅ Deterministic: Synchronous operations used
✅ File size: All files ≤150 lines
✅ DRY: No duplicate code detected
✅ KISS: Minimal complexity verified
✅ Config: No hardcoded values outside constants
✅ Performance: Benchmarks passing
✅ Production: Error handling complete

BLOCK_IF: Any gate fails

Mid-Phase Validation Points:

**During Development:**

- [ ] **INCREMENTAL COMPLIANCE**: Check after each significant change
- [ ] **BENCHMARK INTEGRATION**: New components measured immediately
- [ ] **DEPENDENCY ALIGNMENT**: Imports match architectural boundaries
- [ ] **EDGE CASE HANDLING**: Document but don't implement without plan
- [ ] **FEATURE CREEP CHECK**: Question necessity of each addition

**Before Phase Completion:**

- [ ] **FULL ARCHITECTURE AUDIT**: All principles systematically verified
- [ ] **PERFORMANCE REGRESSION**: Compare against established baselines
- [ ] **INTEGRATION VALIDATION**: Components work within system boundaries
- [ ] **PRODUCTION SIMULATION**: Test under realistic deployment constraints

Quality Gates Template

### Phase [N] Enforcement Checkpoint

**DRY/KISS Validation:**

- [ ] No duplicate logic between modules
- [ ] Each component has single responsibility
- [ ] Complexity justified by measurable benefit

**Architecture Compliance:**

- [ ] Centralized configuration used throughout
- [ ] Constants referenced, no magic numbers
- [ ] Modular separation maintained
- [ ] Dependencies clearly defined

**Performance Requirements:**

- [ ] [Component A]: < [X]ms ✅/⚠️/❌
- [ ] [Component B]: < [X]ms ✅/⚠️/❌
- [ ] Memory usage: < [X]MB ✅/⚠️/❌
- [ ] Regression detection: PASS/FAIL

**Production Readiness:**

- [ ] Error handling appropriate for production
- [ ] No hardcoded environment-specific values
- [ ] Graceful failure modes implemented
- [ ] Resource cleanup on shutdown

**⚠️ BLOCK PROGRESSION**: Any failed checkpoint blocks moving to next phase

Enforcement Automation

Required Scripts:

### `scripts/validate-phase`

- [ ] Check file sizes (fail if >150 lines)
- [ ] Scan for hardcoded values outside config
- [ ] Validate import dependencies match architecture
- [ ] Run benchmark suite and check gates
- [ ] Generate compliance report

### `scripts/dry-audit`

- [ ] Detect duplicate function implementations
- [ ] Find unused imports and functions
- [ ] Identify constants that should be centralized
- [ ] Flag potential separation of concerns violations

### CI/CD Workflow Integration

- [ ] Run validation on every commit
- [ ] Block merges that fail compliance checks
- [ ] Generate performance regression reports
- [ ] Maintain baseline measurements over time

Documentation Structure Template

# [Project Name] Development Plan

## Project Overview

**Goal**: [What you're building and why]
**Done When**: [Specific completion criteria]
**Current Status**: [Brief description of where you are]

## Phase 0: Infrastructure (MANDATORY - ALWAYS FIRST)

### Purpose: Establish foundational systems for reliable development

### Dependencies: None (this is the starting point)

### Deliverables:

- [ ] Benchmarking suite with component isolation
- [ ] Regression detection system with baseline management
- [ ] GitHub workflows (release automation, quality gates)
- [ ] Test suite infrastructure (unit + stress testing)
- [ ] Documentation generation system
- [ ] Centralized main entry points and configuration

### Quality Gates:

- [ ] Benchmark suite measures all core operations
- [ ] CI fails on performance regressions
- [ ] Test suite runs automatically on commits
- [ ] Documentation generates from current codebase
- [ ] All systems integrated and operational

**PHASE 0 RESULTS:**

- Benchmarking: [performance baseline] ✅
- CI/CD: [workflow status] ✅
- Testing: [coverage percentage] ✅
- Documentation: [generation status] ✅

## Phase [N]: [Name] ([STATUS])

### Purpose: [What this phase accomplishes]

### Dependencies: [Phase 0 + any other requirements]

### Deliverables:

- [ ] [Specific output 1]
- [ ] [Specific output 2]

### Quality Gates:

- [ ] [Completion criteria]
- [ ] [Validation method]
- [ ] **BENCHMARK INTEGRATION**: [Performance measurements added]

### Architectural Compliance:

- [ ] **SoC VALIDATION**: Each module single responsibility
- [ ] **FILE SIZE COMPLIANCE**: All files ≤150 lines
- [ ] **DRY ENFORCEMENT**: No duplicate code
- [ ] **PERFORMANCE INTEGRATION**: Benchmarks passing

**PHASE RESULTS:**

- [Component]: [outcome] [status]
- [Component]: [outcome] [status]

## Implementation Notes

- [Decisions made and why]
- [Things learned during development]
- [Issues encountered and solutions]

## Quality Assurance Checkpoints

- [ ] [Project-specific quality measures]
- [ ] [Integration validations]

## Architectural Debt Prevention

**Before Each Development Session:**

1. **Current State Audit**: Run validation scripts
2. **Compliance Review**: Check last enforcement checkpoint
3. **Regression Check**: Verify benchmarks still pass
4. **Technical Debt Assessment**: Identify cleanup needed

**During Development:**

1. **Incremental Validation**: Check compliance after each file
2. **Performance Monitoring**: Benchmark new components immediately
3. **Dependency Tracking**: Verify imports align with architecture
4. **Code Quality**: Maintain self-explanatory naming and structure

**End of Development Session:**

1. **Full Compliance Check**: Run all validation scripts
2. **Performance Regression**: Compare against baselines
3. **Documentation Update**: Record decisions and reasoning
4. **Checkpoint Status**: Update phase progress with evidence

Building Your Documentation

Start With These Questions:

What am I building? (Concrete description)
How will I know it's done? (Completion criteria)
What are the major pieces? (High-level components)
What order must things happen in? (Dependencies)
Where are the natural checkpoints? (Phase boundaries)

Create Phases Based On:

Dependency requirements: A needs B, B needs C
Logical groupings: Related functionality
Validation points: Where you can test progress
Risk management: Tackle uncertain parts early

For Each Phase, Define:

Purpose: Why this phase exists
Prerequisites: What must be complete first
Deliverables: Specific outputs
Success criteria: How to know it's done
Enforcement checkpoints: Systematic validation points
Quality gates: Automated compliance verification

Track Progress By:

Status indicators: Visual progress markers
Completion metrics: Measurable outcomes
Integration validation: Does it work with other components?
Quality assessment: Does it meet requirements?

Principle Integration (All Project Types)

Implementation Enforcement:

File and Module Constraints:

- [ ] Each file ≤ 150 lines or properly split
- [ ] Module serves single, clear purpose
- [ ] No redundant code between modules
- [ ] Existing functions reused before creating new ones
- [ ] Naming conventions consistent across codebase

Architecture Validation:

- [ ] Centralized configuration used throughout
- [ ] Constants referenced, no magic numbers
- [ ] Modular separation maintained with clear boundaries
- [ ] Dependencies align with separation of concerns
- [ ] Synchronous operations preferred over async complexity

Performance Integration:

- [ ] Benchmarking suite integrated with all modules
- [ ] Regression detection operational
- [ ] JSON output for automated analysis
- [ ] Performance gates defined and enforced
- [ ] Timeline tracking for historical comparison

Production Readiness:

- [ ] Cross-platform deployment considerations
- [ ] Real-world constraints addressed
- [ ] Resource cleanup on shutdown
- [ ] Deterministic behavior under load
- [ ] Error handling appropriate for production

Scaling Adaptation Guidelines:

Single File Scripts:

Apply SoC within functions (input, processing, output)
Benchmark core operation even if simple
Validate against 150-line limit
Self-explanatory function and variable names

Small Applications:

Strict modular boundaries with clear interfaces
Centralized configuration and constants
Synchronous operations with predictable flow
Performance baseline establishment

Production Systems:

Full architectural compliance with all principles
Comprehensive benchmarking and regression detection
Cross-platform deployment considerations
Production-grade error handling and resource management

Multi-Language Projects:

Each language justified by measurable performance gains
Maintain architectural principles across language boundaries
Unified benchmarking system for all components
Consistent error handling patterns across languages

Domain-Specific Adaptations:

Web Development Projects:

No Inlining: Styles to separate files, handlers to named functions, configs as constants
File Size Exemption: Components ≤250 lines (DOM complexity), modules ≤150 lines
Async Permitted: API calls, user interactions, data fetching only
Error Boundaries: Network ops, user inputs, third-party integrations
File Colocation: Component.jsx, Component.module.css, Component.test.js
Component Splitting: Multiple purposes or testing difficulty

Success Metrics

Technical Indicators:

All architectural principles consistently applied across codebase
Performance baselines maintained throughout development lifecycle
Zero production incidents related to architectural violations
File size constraints adhered to without compromising functionality

Operational Indicators:

System uptime and reliability under production load
Predictable resource utilization patterns
Graceful degradation under stress conditions
Maintainability preserved as codebase grows

Development Indicators:

Enforcement checkpoints prevent architectural drift
Performance regression detection catches optimizations and degradations
Code review efficiency improved through systematic validation
Technical debt accumulation prevented through continuous compliance

Documentation Quality:

Enforcement checkpoints prevent architectural drift
Quality gates block progression with incomplete work
Automated validation catches compliance violations
Performance baselines maintained throughout development

Project Execution:

Systematic validation prevents technical debt accumulation
Architectural principles consistently applied across codebase
Performance characteristics predictable and measurable
Production readiness verified at each phase

This methodology enforces discipline through automated checking and explicit validation points, preventing the gradual erosion of architectural principles during development.

Format Selection Guide

Format	Best For	Characteristics
Markdown	Web browser AI, documentation review	Human-readable, easy paste
XML	Machine parsing, structured data	Explicit tags, schema validation
JSON	Configuration, data exchange	Programmatic access, strict syntax
PAG	CLI agents, explicit constraints	Code-like patterns, validation gates

Choose based on your AI interface and workflow requirements. The underlying principles remain constant across all formats.

FilesExpand file tree

METHODOLOGY.md

Latest commit

History