Core Concepts
What is a Yawn?
A yawn is a relationship contract between an entity (person, org, AI agent) and something they care about. The platform helps users capture raw thoughts, extract structure, run experiments, submit evidence, and learn through a closed feedback loop.
The Holarchy
Yawns form a holarchy — a nested hierarchy where every yawn can contain child yawns, and every child can itself be a parent. This enables fractal decomposition of complex intentions.
Root Yawn (Company)
├── Product Launch (Project)
│ ├── Build MVP (Task)
│ │ ├── Design API (Subtask)
│ │ └── Write Tests (Subtask)
│ └── Market Research (Task)
└── Hiring Plan (Project)
└── Post Job Listings (Task)Parent-child relationships are tracked via parent_yawn_id and yawn_links. Create children via POST /api/yawn/{id}/children.
18 Fundamental Questions
Every yawn is assessed against 18 questions in 6 categories. Answering these drives the coherence score and determines when a yawn promotes to a higher level. Questions marked with * are critical — required for first promotion.
Identity (3)
identity.awakeningWhat is trying to wake up here?*identity.subjectWho owns this intention?identity.targetWhat is this in relationship with?Position (4)
position.parentWhere does this fit in the holarchy?*position.domainWhat domain is this?position.keywordsHow can others find this?position.inIndexIs this registered in the index?State (5)
state.currentStateWhat is the current state?*state.desiredStateWhat is the desired state?*state.blockersWhat forces block progress?state.boostersWhat forces accelerate progress?state.boundariesWhat are the hard limits?Completion (3)
completion.conditionsHow will we know when this is done?*completion.experimentsWhat experiments test this?completion.evidenceWhat evidence exists?Learning (4)
learning.evolutionLogWhat have we learned?learning.emergenceNotesWhat patterns have emerged?learning.dosWhat should we always do?learning.dontsWhat should we never do?Risk (3)
risk.vulnerabilitiesWhat could kill this?risk.earlyWarningsDo we have early warning signs?risk.mitigationsDo we have contingencies?Coherence & Promotion
Coherence is the percentage of fundamental questions answered. It drives the promotion axis — how a yawn matures from a raw seed to a full venture:
| Status | Score | Meaning |
|---|---|---|
| critical | < 70% | Missing essential information |
| needs_attention | 70–89% | Functional but incomplete |
| coherent | ≥ 90% | Well-defined and actionable |
Experiments & Evidence
Every yawn can have experiments — structured hypotheses with success criteria and branching logic (on_yes / on_no). Evidence proves outcomes.
Experiment: "Ship MVP in 2 weeks" ├── Hypothesis: "Users will sign up if we launch quickly" ├── Success criteria: 10+ signups in first week ├── on_yes → Scale marketing └── on_no → Pivot to different audience Evidence types: artifact — Files, reports, build outputs test_log — CI/CD results, test passes screenshot — Visual proof, before/after link — External URLs, commits self_attest — "I manually verified this"
Workers & YawnJobs
A YawnJob is a yawn with scheduling, task execution, and learning built in. Think of it as a "multi-dimensional cronjob" — it runs on a schedule, tracks experiments, and submits evidence of its outcomes.
Workers are yawns that have been activated with defined input_spec, output_spec, and proof_spec. They can be dispatched by the flywheel orchestrator based on capability matching.