Core Concepts
Understanding these fundamental concepts will help you get the most out of Organic Flow.
Knowledge-First Development
Traditional development treats code as primary and documentation as secondary. Organic Flow inverts this: knowledge becomes primary, code becomes one possible implementation.
Traditional Approach
- • Write code first
- • Document later (maybe)
- • Knowledge lives in developers' heads
- • Lost when code is deleted
Organic Flow Approach
- • Capture understanding first
- • Code implements knowledge
- • Knowledge persists in repository
- • Survives code changes
The Knowledge Flow
Click on a stage to learn more
The Organic Flow process is a continuous cycle where knowledge compounds over time. Each stage builds on the previous, creating a sustainable development methodology.
Key Concepts
Inputs
Starting points for development: problems to solve, ideas to explore, or observations about the system.
Captured without judgment in inputs/.
inputs/problems/slow-build-times.md
inputs/ideas/caching-strategy.md
inputs/observations/user-behavior-patterns.md
Assumptions
Hypotheses about what might work, stated as clear if/then statements with validation criteria. Forces clear thinking before implementation.
If we implement Redis caching for API responses,
then we can reduce response times by 80%,
given most requests are for unchanged data.
Experiments
Isolated branches where assumptions are tested. Every experiment produces learning, whether it succeeds or fails. Code is temporary, learning is permanent.
Successful
Validates assumption
Failed
Equally valuable insight
Knowledge PRs
The mechanism for extracting learning from experiments. Unlike code PRs, Knowledge PRs add only documentation to the main branch.
- ✓ No code in main branch
- ✓ Captures what worked and what didn't
- ✓ Provides recommendations
- ✓ Links to experiment branch for reference
The Harvest
The process of extracting reusable knowledge from experiments. Like harvesting crops, you gather what's valuable and leave the rest to decompose.
Extract: Learnings, patterns, insights
Document: What worked, what didn't, why
Share: Via Knowledge PR to main branch
Living Documentation
Documentation that can't become outdated because it IS the source of truth. The main branch contains only knowledge, making docs always accurate.
"Documentation that can't drift from reality because it IS the reality"
The Philosophy
"Code is temporary, knowledge is eternal"
Software changes constantly. Languages evolve, frameworks come and go, requirements shift. But the understanding of why decisions were made, what was tried, what worked, and what didn't—this knowledge remains valuable forever. Organic Flow captures this knowledge systematically, making it the primary artifact of development.