A general pattern for organising any substantial undertaking in notes — technical, personal or organisational — so that research, risks, decisions and next steps are kept, and work can resume cleanly after interruptions. Companion to principles/shared-resource-coordination and PROGRAMMING_RULES/project-documentation.
When to use it
- The work will run over several sessions or weeks.
- There is a risk of getting side-tracked and losing ideas.
- Exploration came first (a wide net) and filtering will come later.
- Decisions depend on context that may be forgotten or change.
- The subject is sensitive and needs a clear storage boundary.
The structure
One hub note plus a small set of single-purpose children under a shared key prefix. Each child answers one question.
- <topic> (hub) — purpose in one paragraph, current status, guiding principles, links to every child, related notes, and how to resume.
- <topic>/background — what is true: people or systems involved, the trigger, stated positions, key insights. Facts only, dated.
- <topic>/research — what we found: options, techniques and evidence, each with a fit assessment, plus sources.
- <topic>/risks — what may not work out: a deliberately wide list grouped by category. Things to prepare for, not predictions.
- <topic>/look-ahead — a structured foresight exercise (see below), with a results section.
- <topic>/plan — what needs to be done: phased checklist with dependencies and alternative branches.
- <topic>/open-questions — questions to answer and parked topics, so nothing raised is lost.
- <topic>/log — dated record of sessions, decisions and outcomes, newest last.
Scale down for small work (hub + plan + log may suffice); add children rather than enlarging one note when a section outgrows its page.
Principles behind it
- Separate concerns: facts, findings, risks, actions, questions and history each have one home. This prevents a single long note where actions hide among background.
- Cast wide, then filter: record all candidate options first; mark fit or rejection with a reason rather than deleting. Rejected options and their reasons are valuable later.
- Every child links back to the hub; the hub links to every child. No orphans.
- The hub carries a short 'current status' and a 'how to resume after a detour' procedure: read hub → latest log entry → open questions → next unticked plan item.
- Write principles explicitly in the hub. They act as a test for every later decision.
- Name the next step. The hub and the latest log entry should always say what happens next.
- Record stated facts, not interpretations; keep conclusions in research or log with attribution.
- Date everything that can go stale.
- Keep sources with the findings they support.
- Plans are phased, with dependencies and with branches for different outcomes (including the outcome you don't want).
- Checklists use [ ] and [x] so progress is visible at a glance.
- Park, don't drop: anything raised but not settled goes to open-questions.
Look-ahead review (a positively framed pre-mortem)
Prospective hindsight: imagine the future has already happened and explain why. Run it both ways.
- It went well: imagine success a set time ahead and work backwards (backcasting). What made it work?
- It went badly: imagine failure and list every cause. Use the risks note as a prompt.
- Convert: for each success factor, how to make it more likely; for each cause, prevent, prepare for or accept. Feed results into the plan.
- Run first alone or with an assistant; optionally later with the other people involved; repeat when circumstances change.
Risks note — categories to consider
To avoid a narrow list, sweep across categories such as: the other party's response; your own motives, biases and capacity; the process or conversation itself; the existing relationship or system; third parties; wider social or organisational effects; practical, legal, financial and health factors; and ethical lines that would make the effort wrong.
Privacy boundary
- Decide the store before writing anything. When uncertain, start private.
- Keep a sensitive workstream under its own prefix, separate from unrelated material.
- Never link from a public note to a private key. A public index may say that private items exist and to check the private index, without detail.
- Generic lessons can be distilled into public notes (like this one) with all specifics removed.
Integration
- Link the hub from the store's CONTENTS and, if it has actions, from the TODO index.
- Close or update the originating todo note when work moves into the hub.
- Follow the normal editing workflow: read before write, preserve metadata, use block IDs and revision tokens.