stream-coding

# Stream Coding v3.5: Documentation-First Development

## ⚠️ CRITICAL REFRAME: THIS IS A DOCUMENTATION METHODOLOGY, NOT A CODING METHODOLOGY

**The Goal:** AI-ready documentation. When documentation is clear enough, code generation becomes automatic.

**The Insight:**
> "If your docs are good enough, AI writes the code. The hard work IS the documentation. Code is just the printout."

**v3.5 Core Additions:**
1. Phase 2.5 Adversarial Review — stress-test specs with a hostile critic before execution. New time allocation: 40/40/5/10/5.
2. Renamed internal 13-item checklist to **Spec Gate** (structural completeness for code generation)

> **Two-gate pipeline — know the difference:**
> - **Spec Gate** (13 items, this skill) → *"Can AI execute this without asking questions?"*
> - **Clarity Gate** (9 points, separate tool) → *"Will AI mistake assumptions for facts?"*
>
> Spec Gate → Clarity Gate → Adversarial Review → Verified Specification → Execution

---

## CHANGELOG

| Version | Changes |
|---------|---------|
| 3.0 | Initial Stream Coding methodology |
| 3.1 | Clearer terminology, mandatory Spec Gate |
| 3.3 | Document-type-aware placement (Anti-patterns, Test Cases, Error Handling in implementation docs) |
| 3.3.1 | Corrected time allocation (40/40/20), added Phase 4, added Rule of Divergence |
| 3.4 | Complete 13-item Spec Gate, scoring rubric with weights, self-assessment questions, 4 mandatory section templates, Documentation Audit integrated into Phase 1 |
| **3.5** | **Phase 2.5 Adversarial Review added. New time allocation: 40/40/5/10/5. Internal 13-item checklist renamed from "Clarity Gate" → "Spec Gate". Two-gate pipeline documented: Spec Gate (structural) + Clarity Gate standalone (epistemic).** |

---

## THE STREAM CODING TRUTH

```
Messy Docs → Vague Specs → AI Guesses → Rework Cycles → 2-3x Velocity
Clear Docs → Clear Specs → AI Executes → Minimal Rework → 10-20x Velocity
```

**Why Most "AI-Assisted Development" Fails:**
- People feed AI messy docs
- AI generates code based on assumptions
- Code doesn't match intent
- Endless revision cycles
- Result: Marginally faster than manual coding

**Why Stream Coding Achieves 10-20x:**
- Documentation is clarified FIRST
- AI has zero ambiguity
- Code matches intent on first pass
- Minimal revision
- Result: Documentation time + automatic code generation

---

## DOCUMENT TYPE ARCHITECTURE

**The Rule:** Not all documents need all sections. Putting implementation details in strategic documents violates single-source-of-truth.

> "If AI has to decide where to find information, you've already lost velocity."

### Document Types

| Type | Purpose | Examples |
|------|---------|----------|
| **Strategic** | WHAT and WHY | Master Blueprint, PRD, Vision docs, Business cases |
| **Implementation** | HOW | Technical Specs, API docs, Module specs, Architecture docs |
| **Reference** | Lookup | Schema Reference, Glossary, Configuration |

### Section Placement Matrix

| Section | Strategic Docs | Implementation Docs | Reference Docs |
|---------|---------------|---------------------|----------------|
| **Deep Links (References)** | ✅ Required | ✅ Required | ✅ Required |
| **Anti-patterns** | ❌ Pointer only | ✅ Required | ❌ N/A |
| **Test Case Specifications** | ❌ Pointer only | ✅ Required | ❌ N/A |
| **Error Handling Matrix** | ❌ Pointer only | ✅ Required | ❌ N/A |

### Why This Matters

**Wrong (violates single-source-of-truth):**
```
Master Blueprint
├── Strategy content
├── Anti-patterns ← WRONG: duplicates Technical Spec
├── Test Cases ← WRONG: duplicates Testing doc
└── Error Matrix ← WRONG: duplicates Error Handling doc
```

**Right (single-source-of-truth):**
```
Master Blueprint (Strategic)
├── Strategy content
└── References
    └── Pointer: "Anti-patterns → Technical Spec, Section 7"

Technical Spec (Implementation)
├── Implementation details
├── Anti-patterns ← CORRECT: lives here
├── Test Cases ← CORRECT: lives here
└── Error Matrix ← CORRECT: lives here
```

---

## THE 4-PHASE METHODOLOGY

### Time Allocation

| Phase | Time | Focus |
|-------|------|-------|
| Phase 1: Strategic Thinking | 40% | WHAT to build, WHY it matters |
| Phase 2: AI-Ready Documentation | 40% | HOW to build (specs so clear AI has zero decisions) |
| **Phase 2.5: Adversarial Review** | **5%** | **Stress-test specs with a hostile critic before execution** |
| Phase 3: Execution | 10% | Code generation + implementation |
| Phase 4: Quality & Iteration | 5% | Testing, refinement, divergence prevention |

**The logic:** Spending 5% upfront to break specs saves more than 5% in Phase 3 rework. If you bulletproof docs adversarially, execution gets faster — not slower.

---

## PHASE 2.5: ADVERSARIAL REVIEW (5% of time)

### When to Run

After Spec Gate passes (9+/10). Before any code generation.

**The principle:** The same AI that wrote your specs has the same blind spots you do. A different model — or a human with instructions to attack — finds what you can't see.

> "When code fails, fix the spec — not the code. Phase 2.5 finds spec failures before there's any code to fail."

### The Process

```
1. Spec Gate passes (9+/10) → proceed to adversarial step
2. Submit specs to DIFFERENT AI model (Gemini, GPT-4, Perplexity)
   OR trusted human reviewer
3. Use the adversarial prompt below
4. Categorize findings: CRITICAL / HIGH / MEDIUM / LOW
5. Fix ALL CRITICAL issues → return to Spec Gate → re-score
6. Document HIGH issues with explicit accept/defer decision
7. Gate: zero CRITICAL remaining → proceed to Phase 3
```

**Why a different model:** The AI that generated or reviewed your docs learned your assumptions. A different model has no context, no charitable interpretation, no benefit of the doubt. It finds gaps your primary AI normalizes.

### The Adversarial Prompt Template

```markdown
You are a skeptical senior developer and hostile critic reviewing 
this specification before it goes to an AI agent for execution.

## Your Mission
Find every flaw. Assume proble