stream-coding

# Stream Coding v3.4: 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.4 Core Addition:** Complete 13-item Clarity Gate with scoring rubric. The gate is the methodology—skip it and you're back to vibe coding. --- ## CHANGELOG | Version | Changes | |---------|---------| | 3.0 | Initial Stream Coding methodology | | 3.1 | Clearer terminology, mandatory Clarity 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 Clarity Gate, scoring rubric with weights, self-assessment questions, 4 mandatory section templates, Documentation Audit integrated into Phase 1** | --- ## 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 3: Execution | 15% | Code generation + implementation | | Phase 4: Quality & Iteration | 5% | Testing, refinement, divergence prevention | **The Counterintuitive Truth:** 80% of time goes to documentation. 20% to code. This is why velocity is 10-20x—not because coding is faster, but because rework approaches zero. --- ## PHASE 1: STRATEGIC THINKING (40% of time) ### Decision Tree: Where Do You Start? ``` Phase 1: Strategic Product Thinking │ ├─ Have existing documentation? │ └─ YES → Start with Documentation Audit → then 7 Questions │ └─ Starting fresh? └─ Skip to 7 Questions ``` ### Documentation Audit (Conditional) **Skip this step if starting from scratch.** The Documentation Audit only applies when you have existing documentation—previous specs, inherited docs, or accumulated notes. **Why clean existing docs?** Because most documentation accumulates cruft: - Aspirational statements ("We will revolutionize...") - Speculative futures ("In 2030, we might...") - Outdated decisions (v1 architecture in v3 docs) - Duplicate information across files - Motivational fluff with no implementation value **The Audit Process:** Apply the Clarity Test to all existing documentation: | Check | Question | |-------|----------| | **Actionable** | Can AI act on this? If aspirational, delete it. | | **Current** | Is this still the decision? If changed, update or remove. | | **Single Source** | Is this said elsewhere? Consolidate to one place. | | **Decision** | Is this decided? If not, don't include it. | | **Prompt-Ready** | Would you put this in an AI prompt? If not, delete. | **Audit Checklist:** - [ ] Remove all "vision" and "future state" language - [ ] Delete motivational conclusions and preambles - [ ] Consolidate duplicate information to single source - [ ] Update all outdated architectural decisions - [ ] Remove speculative features not in current scope **Target:** 40-50% reduction in volume without losing actionable information. Once clean, proceed to the 7 Questions. --- ### The 7 Questions Framework Before ANY new documentation, answer these with specificity. Vague answers = vague code. | # | Question | ❌ Reject | ✅ Require | |---|----------|-----------|------------| | 1 | What exact problem are you solving? | "Help users manage tasks" | "Help [specific persona] achieve [measurable outcome] in [specific context]" | | 2 | What are your success metrics? | "Users save time" | Numbers + timeline: "100 users, 25% conversion, 3 months" | | 3 | Why will you win? | "Better UI and features" | Structural advantage: architecture, data moat, business model | | 4 | What's the core architecture decision? | "Let AI decide" | Human decides based on explicit trade-off analysis | | 5 | What's the tech stack rationale? | "Node.js because I like it" | Business rationale: "Node—team expertise, ship fast" | | 6 | What are the MVP features? | 10+ "must-have" features | 3-5 truly essential, rest explicitly deferred | | 7 | What are you NOT building? | "We'll see what users want" | Explicit exclusions with rationale | ### Phase 1 Exit Criteria - [ ] All 7 questions answered at "Require" level - [ ] Strategic Blueprint document created - [ ] Architecture Decision Records (ADRs) for major choices - [ ] Zero ambiguity about WHAT you're building --- ## PHASE 2: AI-READY DOCUMENTATION (40% of time) ### The 4 Mandatory Sections (Implementation Docs) Every implementation document MUST include these four sections. Without them, AI guesses—and guessing creates the velocity mirage. #### 1. Anti-Patterns Section **Why:** AI needs to know what NOT to do. ```markdown ## Anti-Patterns (DO NOT) | ❌ Don't | ✅ Do Instead | Why | |----------|---------------|-----| | Store timestamps as Date objects | Use ISO 8601 strings | Serialization issues | | Hardcode configuration values | Use environment variables | Deployment flexibility | | Use generic error messages | Specific error codes per failure | Debugging impossible otherwise | | Skip validation on internal calls | Validate everything | Internal calls can have bugs too | | Expose internal IDs in APIs | Use UUIDs or slugs | Security and flexibility | ``` **Rules:** Minimum 5 anti-patterns per implementation document. #### 2. Test Case Specifications **Why:** AI needs concrete verification criteria. ```markdown ## Test Case Specifications ### Unit Tests Required | Test ID | Component | Input | Expected Output | Edge Cases | |---------|-----------|-------|-----------------|------------| | TC-001 | Tier classifier | 100 contacts | 20-30 in Critical tier | Empty list, all same score | | TC-002 | Score calculator | Activity array | Score 0-100 | No events, >1000 events | ### Integration Tests Required | Test ID | Flow | Setup | Verification | Teardown | |---------|------|-------|--------------|----------| | IT-001 | Auth flow | Create test user | Token refresh works | Delete test user | ``` **Rules:** Minimum 5 unit tests, 3 integration tests per component. #### 3. Error Handling Matrix **Why:** AI needs to know how to handle every failure mode. ```markdown ## Error Handling Matrix ### External Service Errors | Error Type | Detection | Response | Fallback | Logging | Alert | |------------|-----------|----------|----------|---------|-------| | API timeout | >5s response | Retry 3x exponential | Return cached | ERROR | If 3 in 5 min | | Rate limit | 429 response | Pause 15 min | Queue for retry | WARN | If >5/hour | ### User-Facing Errors | Error Type | User Message | Code | Recovery Action | |------------|--------------|------|-----------------| | Quota exceeded | "You've used all checks this month." | 403 | Show upgrade CTA | | Session expired | "Please sign in again." | 401 | Redirect to login | ``` **Rules:** Every external service and user-facing error must be specified. #### 4. Deep Links (All Document Types) **Why:** AI needs to navigate to exact locations. "See Technical Annexes" is useless. ```markdown ## References ### Schema References | Topic | Location | Anchor | |-------|----------|--------| | User profiles | [Schema Reference](../schemas/schema.md#user_profiles) | `user_profiles` | | Events table | [Schema Reference](../schemas/schema.md#events) | `events` | ### Implementation References | Topic | Document | Section | |-------|----------|---------| | Auth flow | [API Spec](../specs/api.md#authentication) | Section 3.2 | | Rate limiting | [API Spec](../specs/api.md#rate-limiting) | Section 5 | ``` **Rules:** NEVER use vague references. ALWAYS include document path + section anchor. --- ## ⚠️ THE CLARITY GATE (v3.4 - COMPLETE) **⛔ NEVER SKIP THIS GATE.** This is the difference between stream coding and vibe coding. A 7/10 spec generates 7/10 code that needs 30% rework. ### The 13-Item Clarity Gate Checklist Before ANY code generation, verify ALL items pass: #### Foundation Checks (7 items) | # | Check | Question | |---|-------|----------| | 1 | **Actionable** | Can AI act on every section? (No aspirational content) | | 2 | **Current** | Is everything up-to-date? (No outdated decisions) | | 3 | **Single Source** | No duplicate information across docs? | | 4 | **Decision, Not Wish** | Every statement is a decision, not a hope? | | 5 | **Prompt-Ready** | Would you put every section in an AI prompt? | | 6 | **No Future State** | All "will eventually," "might," "ideally" language removed? | | 7 | **No Fluff** | All motivational/aspirational content removed? | #### Document Architecture Checks (6 items - v3.3 Critical) | # | Check | Question | |---|-------|----------| | 8 | **Type Identified** | Document type clearly marked? (Strategic vs Implementation vs Reference) |