The method

The 7-phase workflow that transforms requirements into deterministic, production-ready software

Why this method works

scientific foundations and experimental data

The problem: Ambiguity → Hallucination

Without deterministic specification:

"Create an authentication system"

10²⁰ possible implementations

AI chooses probabilistically

→ 60.4% hallucination rate

With structured specification:

Complete Arc42 + BDD + ADR spec

Entropy H ≈ 0.5 bits (vs 18 bits)

~1.4 possible implementations

→ 7.5% hallucination rate

88% reduction in hallucination rate through entropy reduction (Shannon, 1948)

Solution 1: Documentation-First Approach

Why? Language models are probabilistic: P(sequence) = P(t₁) × P(t₂|t₁) × ... × P(tₙ|...)

Even with 80% accuracy per token:

P(1000 correct tokens) = 0.8¹⁰⁰⁰ ≈ 10⁻⁹⁷ (essentially zero)

How? Arc42 (12 chapters) + C4 (3 levels) + BDD (Given-When-Then) + ADR (documented decisions)

Result: Reduces entropy from 18 bits → 0.5 bits = 262,144 possibilities → 1.4 possibilities

Solution 2: Task Decomposition (Phase 3.5)

Why? Attention mechanism has O(n²) complexity - large contexts cause degradation

Spec 3,570 lines (~25,000 tokens):

→ 625M attention operations

→ 60% loss in the middle of context ("Lost in the Middle", Liu et al. 2023)

Task 450 lines (~2,500 tokens):

→ 6.25M operations per task

→ <5% context loss

How? Orchestrator decomposes specs into tasks ~100 LOC (Vaswani et al. 2017 - Attention is All You Need)

Result: 10× fewer operations + maintained focus = additional 62.5% reduction in hallucination

Solution 3: Test-First Development

Why? Tests are executable specifications that validate behavior

Without tests: bugs found in production = 72 (3 months)

With TDD + ≥80% coverage: bugs found = 10 (3 months)

→ 86% bug reduction

How? RED (failing test) → GREEN (minimal implementation) → REFACTOR (improve while keeping green)

Solution 4: DDD Tactical Co-Located

Why? Technical layer organization obscures domain and increases context dispersion

Technical layers (services/, repositories/, controllers/):

→ AI needs to navigate 3-5 directories to understand one feature

→ Fragmented context = higher error probability

DDD Co-Located (src/[context]/[container]/[component]/):

→ Everything related to the feature in one place

→ Focused context = lower error probability

How? Screaming Architecture + Co-Location + Semantic Names + Flat Structure

Combined effect: 98.5% reduction in hallucination

Without method: 60.4% hallucination

+ Arc42 Spec: 35.0% (-42%)

+ Task Decomposition: 7.5% (-88%)

+ Iteration with validation: 0.9% (-98.5%)

Based on: Shannon (1948), Vaswani et al. (2017), Liu et al. (2023) + controlled experiments (Chronicle 10)

The 7-phase workflow

specification → decomposition → implementation → validation

1

Discovery

Analyst

Input: User requirement (text, doc, conversation)

Process:

  1. Understand requirement
  2. Ask questions to clarify
  3. Evaluate complexity (LOW/MEDIUM/HIGH)
  4. Generate proposal.md

Output: changes/[id]/proposal.md with problem, solution, complexity

Decision: HIGH → Phase 2 (Architecture) | MEDIUM/LOW → Skip to Phase 3

2

Architecture

Architect • [HIGH only]

Input: proposal.md (HIGH complexity)

Process:

  1. Design system architecture
  2. Create C4 diagrams (Context, Container, Component)
  3. Identify bounded contexts
  4. Document key decisions as ADRs
  5. Generate design.md

Output: changes/[id]/design.md + ADRs

3

Specification

Analyst

Input: proposal.md (+ design.md if HIGH)

Process:

  1. Write Arc42 documentation (adaptive by complexity)
  2. Create C4 diagrams
  3. Write BDD scenarios (GIVEN-WHEN-THEN)
  4. Document ADRs for key decisions
  5. Generate spec.md

Output: changes/[id]/spec.md (OpenSpec delta format)

3.5

Task Decomposition

CRÍTICOOrchestrator

⚠️ THIS IS WHAT PREVENTS AI HALLUCINATIONS

Input: spec.md

Process:

  1. Analyze size and complexity of spec
  2. Break into atomic tasks: each <100 LOC, <2 hours
  3. Define clear dependencies
  4. Map tasks to BDD scenarios
  5. Generate tasks.md

Output: changes/[id]/tasks.md

Why this matters:

  • • Large context (5000+ LOC) → Attention decay O(n²)
  • • AI loses focus → Hallucinations increase
  • • Small tasks (~100 LOC) → Deterministic output

changes/ folder structure:

changes/[feature-id]/
├── proposal.md       # Problem, solution, complexity
├── design.md         # Architecture (HIGH only)
├── spec.md           # Arc42 + C4 + BDD + ADR
└── tasks.md          # Atomic tasks <100 LOC

Each changes/ folder orchestrates:
• Complete isolated specification
• Decomposed and prioritized tasks
• Traceability from requirement → code
4

Implementation

Developer + Gatekeeper

Input: changes/[id]/tasks.md

Process:

  1. Implement task by task sequentially
  2. Write tests BEFORE implementation (TDD)
  3. Apply DDD Tactical Co-Located structure
  4. Gatekeeper validates SOLID, Object Calisthenics
  5. Run tests (≥80% coverage mandatory)

Output: Implemented code + passing tests

5

Validation

Reviewer + Tester

Input: Implemented code (Phase 4)

Process:

  1. Reviewer: code review focused on quality, maintainability
  2. Reviewer: validate adherence to constitution.md
  3. Tester: execute BDD scenarios from spec
  4. Tester: validate test coverage ≥80%
  5. Tester: verify edge cases

Output: Validated code + quality report

6

Documentation

Documenter

Input: Validated code (Phase 5)

Process:

  1. Update README with new features
  2. Generate/update API documentation
  3. Create migration guides (if breaking changes)
  4. Update CHANGELOG
  5. Sync specs/ with implemented code

Output: Updated and synchronized documentation

7

Pre-Commit Validation

Guardian

Input: Code + updated docs (Phase 6)

Process:

  1. Validate compliance with constitution.md
  2. Run all tests (full regression)
  3. Verify linters (zero warnings)
  4. Validate updated specs/
  5. Verify BDD → code mapping

Output: ✅ Approved for commit or ❌ Blocked with feedback

Phase 3.5: Task decomposition - THE KEY

Why? Context >5000 lines = AI loses focus (attention decay O(n²))

How? Orchestrator breaks specs into tasks <100 LOC

Result? Deterministic output, predictable quality

Complexity-driven approach

not all features are equal - we adapt the workflow

LOW
2-8 hours

Phases

1 → 3 → 3.5 → 4 → 7

Arc42 Chapters

Only 6, 10

Criteria

1 context, <5 files, established patterns

Examples: Add validation, new field, small bug fix

MEDIUM
1-3 days

Phases

1 → 3 → 3.5 → 4 → 5 → 7

Arc42 Chapters

3, 5, 6, 8, 9, 10

Criteria

1-2 contexts, 5-15 files, some new patterns

Examples: New feature, module, 3-5 use cases

HIGH
1-2 weeks

Phases

All 7 phases

Arc42 Chapters

All 12 chapters

Criteria

3+ contexts, >15 files, new architectural patterns

Examples: Payment system, authentication, messaging

Scientific References

A Mathematical Theory of Communication

Claude Shannon, 1948 • Information Theory and Entropy

Read paper (PDF)

Attention Is All You Need

Vaswani et al., 2017 • Transformer Architecture and O(n²) complexity

Read paper (arXiv)

Lost in the Middle: How Language Models Use Long Contexts

Liu et al., 2023 • Context degradation in language models

Read paper (arXiv)