Organic Flow: Visual Overview
Created: 2025-07-29 Context: Visual representations and diagrams to understand Organic Flow at a glance
The Fundamental Inversion
Traditional Development
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Code │ ──> │ Maybe │ ──> │ Knowledge │
│ (Primary) │ │ Docs │ │(Often Lost) │
└─────────────┘ └─────────────┘ └─────────────┘
⬇ ❌
Preserved DiscardedOrganic Flow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Knowledge │ ──> │ Code │ ──> │ Learning │
│ (Primary) │ │ (Secondary) │ │ (Extracted) │
└─────────────┘ └─────────────┘ └─────────────┘
⬇ ❌ ⬇
Preserved Discardable Feeds backThe Complete Flow
┌─────────────────┐
│ INPUTS │
│ Problems │
│ Ideas │
│ Observations │
└────────┬────────┘
⬇
┌─────────────────┐
│ HYPOTHESES │
│ What might │
│ work? │
└────────┬────────┘
⬇
┌────────────┴────────────┐
⬇ ⬇
┌─────────────────┐ ┌─────────────────┐
│ EXPERIMENT/ │ │ IMPLEMENTATION/ │
│ Quick Test │ │ Full Feature │
│ (Hours-Days) │ │ (Days-Weeks) │
└────────┬────────┘ └────────┬────────┘
⬇ ⬇
┌─────────────────┐ ┌─────────────────┐
│ KNOWLEDGE │ │ KNOWLEDGE │
│ Patterns │ │ Constraints │
│ What works │ │ What doesn't │
└────────┬────────┘ └────────┬────────┘
⬇ ⬇
└────────────┬────────────┘
⬇
┌─────────────────┐
│ ACCUMULATED │
│ KNOWLEDGE │
│ Informs next │
│ experiments │
└─────────────────┘Repository Structure
your-project/
│
├── main branch (Knowledge Only)
│ │
│ ├── knowledge/
│ │ ├── inputs/
│ │ │ ├── problems/
│ │ │ │ └── slow-search.md
│ │ │ ├── ideas/
│ │ │ │ └── dark-mode.md
│ │ │ └── observations/
│ │ │ └── peak-load-pattern.md
│ │ │
│ │ ├── hypotheses/
│ │ │ ├── elasticsearch-migration.md
│ │ │ └── redis-caching.md
│ │ │
│ │ ├── learnings/
│ │ │ ├── elasticsearch-experiment.md
│ │ │ └── redis-limits.md
│ │ │
│ │ ├── patterns/
│ │ │ ├── search-optimization.md
│ │ │ └── caching-strategy.md
│ │ │
│ │ └── constraints/
│ │ ├── memory-limits.md
│ │ └── connection-pools.md
│ │
│ └── experiments.yaml
│
├── experiment/redis-cache (Quick Test Branch)
│ ├── src/
│ ├── tests/
│ └── README.md
│
├── impl/search-v2 (Implementation Branch)
│ ├── src/
│ ├── tests/
│ ├── experiments/ # Nested experiments
│ └── README.md
│
└── release/search-v2 (Production Branch)
└── (promoted from successful impl/)The Knowledge Lifecycle
1. INPUT CAPTURE
┌─────────┐
│ Problem │ ──> "Users losing work when logged out"
└─────────┘
2. HYPOTHESIS FORMATION
┌──────────────┐
│ Hypothesis │ ──> "Extend timeout to 4 hours"
│ Assumptions │ ──> "Infrastructure can handle it"
└──────────────┘
3. EXPERIMENTATION
┌──────────────┐
│ Experiment │ ──> Create branch
│ Implement │ ──> Write code
│ Discover │ ──> "Redis runs out of memory!"
└──────────────┘
4. KNOWLEDGE EXTRACTION
┌──────────────┐
│ Learning │ ──> "Memory scales linearly"
│ Pattern │ ──> "Question the obvious solution"
│ Constraint │ ──> "10k connection limit"
└──────────────┘
5. ACCUMULATION
┌──────────────┐
│ Knowledge │ ──> Informs next experiments
│ Repository │ ──> Patterns emerge
│ Grows │ ──> Understanding deepens
└──────────────┘Knowledge PR Flow
experiment/redis-test impl/search-v2
│ │
│ │
(complete) (complete)
│ │
⬇ ⬇
Knowledge PR #1 Knowledge PR #2
"What we learned "Implementation
from Redis test" insights"
│ │
└───────────┬───────────────┘
⬇
main branch
(knowledge updated)Commit Flow Visualization
main branch (knowledge only)
│
├─● Document problem: slow search
│
├─● Add hypothesis: try Elasticsearch
│
│ experiment/elasticsearch
│ ├─● Implement ES integration
│ ├─● Discover memory requirements
│ ├─● Find optimal batch size
│ └─● Complete experiment
│ │
│ └─── Knowledge PR ──┐
│ │
├─● Extract learnings from ES experiment ←─┘
│
├─● Document new pattern: search optimization stages
│
└─● Ready for next experiment (informed by learnings)Knowledge vs Code Over Time
Knowledge Growth Code Churn
│ │
│ ████████ │ ███
│ ██████████ │ ███ ███
│ ████████████ │ ███ ███
│ ██████████████ │ ███ ███
│ ████████████████ │███ ███
└───────────────── └─────────────────
Time → Time →
Knowledge accumulates Code is rewrittenThe Extraction Process
EXPERIMENT BRANCH MAIN BRANCH
│ │
│ const LIMIT = 5000; │ ## Discovered Limits
│ // Found by testing │
│ // Crashes at 5001 │ Batch processing limit: 5000
│ │ - Cause: Memory allocation
│ // Tried 1K - too slow │ - Sweet spot: 3K-5K range
│ // Tried 10K - OOM │ - Formula: limit = RAM/2MB
│ │
└──────── Extract ────────────>│
KnowledgeSuccess Metrics Dashboard
┌─────────────────────────────────────────┐
│ Knowledge Growth Metrics │
├─────────────────────────────────────────┤
│ Problems Documented: ████████ 45 │
│ Hypotheses Tested: ██████████ 67 │
│ Patterns Discovered: ██████ 23 │
│ Constraints Found: ███████ 31 │
│ │
│ Success Rate: 73% ▲ │
│ Avg Time to Solution: 3.2 days ▼ │
│ Knowledge Reuse: 12x/month ▲ │
└─────────────────────────────────────────┘Pattern Recognition
Multiple Experiments:
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Redis │ │ Memcached │ │ In-Memory │
│ Experiment │ │ Experiment │ │ Experiment │
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
└───────────────┴───────────────┘
│
⬇
┌─────────────────┐
│ Caching Pattern │
│ - When to use │
│ - Trade-offs │
│ - Formulas │
└─────────────────┘Before vs After Organic Flow
Before: Knowledge Scatter
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│Dev A│ │Dev B│ │Dev C│ │Wikis│
│Head │ │Head │ │Head │ │Docs │
└─────┘ └─────┘ └─────┘ └─────┘
❌ ❌ ✓ ❌
Left Left Here OutdatedAfter: Knowledge Persistence
┌─────────────────┐
│ Main Branch │
│ All Knowledge │
│ Ever Learned │
└────────┬────────┘
│
┌────────────┼────────────┐
⬇ ⬇ ⬇
┌─────┐ ┌─────┐ ┌─────┐
│Dev A│ │Dev B│ │Dev C│
│Reads│ │Adds │ │Uses │
└─────┘ └─────┘ └─────┘The Power of Failed Experiments
Failed Experiment Results:
┌─────────────────┐
│ ❌ Code Failed │ ──┐
│ ✓ Learned Why │ │
└─────────────────┘ │
⬇
┌──────────────┐
│ Knowledge │
│ - Limits │
│ - Anti- │
│ patterns │
│ - New ideas │
└──────────────┘
⬇
Next experiment
avoids this pathImplementation to Release Flow
main (knowledge)
│
├── impl/payment-v2
│ ├── Build feature over 2 weeks
│ ├── Spawn experiment/payment-retry-logic
│ ├── Spawn experiment/payment-webhook-handling
│ └── Feature complete ✓
│ │
│ ├─── Knowledge PR (learnings)
│ │
│ └─── release/payment-v2 (if successful)
│
└── Knowledge updated with all learningsSummary Visual
╔═══════════════════════════════════════╗
║ ORGANIC FLOW ║
║ Knowledge First, Code Second ║
╠═══════════════════════════════════════╣
║ ║
║ Problems ──> Hypotheses ──> Code ║
║ ⬆ │ ║
║ │ ⬇ ║
║ └──── Knowledge <─── Learning ║
║ ║
║ Main Branch = Knowledge Only ║
║ Experiment/* = Quick tests ║
║ Impl/* = Features to ship ║
║ Release/* = Production code ║
║ ║
║ All produce Knowledge PRs ║
║ Result: Understanding Accumulates ║
╚═══════════════════════════════════════╝The visual story is simple: Make knowledge primary, code secondary, and watch understanding compound over time.