This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 5a53f350101c2e3325af2c18f525d6e23e1ac5a0 Author: Stephen Mallette <[email protected]> AuthorDate: Fri Aug 7 18:28:58 2026 -0400 Hoist decision capture out of the execution section Capture was housed under "While working", so the rules for recording a decision made while planning with the operator lived in the section about writing code. They now sit in Core rules, which state they hold throughout, and sections 2 and 3 point back rather than restate. Assisted-by: Claude Code:claude-opus-5 --- .beads/PRIME.md | 127 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 68 insertions(+), 59 deletions(-) diff --git a/.beads/PRIME.md b/.beads/PRIME.md index 5716ceac17..fce3c9bda8 100644 --- a/.beads/PRIME.md +++ b/.beads/PRIME.md @@ -5,14 +5,14 @@ changed, but why — decisions made, alternatives rejected, and directions aband every bead as something a contributor will read in three years. This file is what must survive context compaction. -## Core rules +## Workflow -An index, not the rules. Each line names a section; **the section is the rule, and the -section holds the exceptions.** Do not act on a line here without reading it. +An index. Each line names a section; **the section is the rule, and the section holds the +exceptions.** Do not act on a line here without reading it. 1. **Bind to a root bead before you write code** — section 1 -2. **Beads is the only tracker, and the plan is a dependency graph** — section 2 -3. **Claim before editing, close as work finishes, record every road not taken** — section 3 +2. **Plan the work with the operator as a dependency graph** — section 2 +3. **Claim before editing, close as work finishes** — section 3 4. **At merge, close the root and pin the whole subtree** — section 4 5. **Never rewrite or discard history** — section 5 6. **Records, edge types and bead IDs follow fixed conventions** — section 6 @@ -20,6 +20,61 @@ section holds the exceptions.** Do not act on a line here without reading it. --- +## Core rules + +These hold throughout — while planning with the operator and while executing. + +**Think in graph.** Work, decisions, external artifacts and the relations between them are +nodes and edges. The plan lives in beads and nowhere else: not `TodoWrite`, not `TaskCreate`, +not a markdown plan file. Those are session-scoped, so nothing in one is memory. Your harness +may prompt you to use them. Decline. + +**A decision needs a bead to hang off**, so create the root when the conversation starts, not +when the code does. + +**Watch for these five things. They are observable events, not judgment calls:** + +1. **The operator redirects you** — "no, do X instead", "we tried that", "that breaks + providers". Highest signal. Capture every time. +2. **What you built diverged from the JIRA / proposal / dev@ thread.** +3. **An approach was tried and abandoned.** +4. **You presented options** — a decision point exists by construction. +5. **A discovery contradicted an assumption.** + +**Then pick the instrument. The only test is whether a road was not taken:** + +| What happened | Do | +|---|---| +| A specific course was considered and **not taken** — a design, a scope item, a validation step, a target branch, a task you wrote and threw away | Decision bead **plus** its `rejected-alternative` sibling, now | +| Something is simply true, with no fork in it — evidence, a measurement, a discovery, a constraint | `bd comment <root> "..."` | + +**The rejected thing does not have to be a design.** "The operator declined X" is a road not +taken. So is "we were going to target master, we targeted 3.7-dev instead." If you can name +what was *not* done, it is a decision — write both beads. + +**Self-check before writing any comment: name what was *not* done.** If you can name it — a +course declined, a branch not targeted, an approach dropped — it is a decision bead, not a +comment. Wording like "the operator declined" or "X rather than Y" is the tell, but check +what it refers to: a choice about *the work* is a decision, while "the test frames HashMap +instead of OptionsStrategy" is just describing code and stays a comment. + +```bash +# Only when something was actually ruled out. No fork = implementation; the code documents that. +bd create --type=decision --parent=<root> --title="Chose X" --design="why, and what X rules out" +# The sibling is the road not taken — an approach you tried and abandoned counts, and is stronger +# evidence than a hypothetical, because someone already walked it. +bd create --type=decision --parent=<root> --title="Y" --labels="rejected-alternative" \ + --design="why Y was rejected" +bd dep add <decision> <alternative> -t related # never put either of these on a task bead +``` + +**Record what actually happened.** If you cannot point to the moment, do not write the bead. +When you sense a decision you were not party to, create a bead labelled `human` posing the +question instead of inventing an answer — `bd human respond <id>` turns the reply into a +comment. + +--- + ## 1. Start here — bind to a root Every session works under one **root bead**. Find it before writing code. @@ -45,10 +100,8 @@ Re-ask after a compaction rather than guessing. ## 2. Plan as a graph, not a list -**The plan lives in beads and nowhere else.** Do not track work in `TodoWrite`, `TaskCreate`, -or a markdown plan file: they are session-scoped, so nothing in one survives, so nothing in -one is memory. Your harness may prompt you to use them. Decline. Anything you weighed and -rejected while planning belongs in a bead **before you start executing**, not after. +The plan is built **with the operator**; what you weigh and reject while building it is +captured as you go, not once you start executing. Tasks are not a checklist. Wire the order between them so the graph itself says what can run in parallel. @@ -69,24 +122,21 @@ here, every "ready" bead was a decision and two were rejected alternatives. - **Wire the order in the same pass as `bd create`.** - **Re-planning is normal; record it.** `bd dep remove` deletes an edge with no trace in the graph, so a restructure erases the shape you started with. If you rewire because you found - a better path, that is a road not taken — write the decision bead (section 3). + a better path, that is a road not taken — write the decision bead. - **A task with no blocker asserts it can start immediately.** The absence of an edge is a claim, not an oversight — decide it deliberately for every task. - **A blocked task is released when its blocker closes**, so tasks must close as they finish. - **Link a decision to the work it caused** — `bd dep add <task> <decision> -t caused-by`. Without it there is no path from a task back to the reasoning that shaped it. -**Before executing, show the operator the plan and ask for approval.** Run the two scoped -commands above and present what they return: what starts now and in parallel, and what waits -on what. That pair *is* the plan — approving a set of titles is not approving a plan, because -the titles say nothing about order. - -If everything comes back ready, there is no order. You built a list and called it a plan; say -so rather than presenting it as one. +**Before proceeding to the next step, obtain human approval.** - Show the human a summary of +the beads graph for review. --- -## 3. While working — claim first, then capture as you go +## 3. While working — claim, then close + +Adjusting the plan mid-flight is normal — section 2 applies again when you do. **Before you touch code for a bead, claim it. Every time, no exceptions:** @@ -109,47 +159,6 @@ closes at merge (section 4). Status is not paperwork. It is both the handoff and the gate. -**Then watch for these five things. They are observable events, not judgment calls:** - -1. **The operator redirects you** — "no, do X instead", "we tried that", "that breaks - providers". Highest signal. Capture every time. -2. **What you built diverged from the JIRA / proposal / dev@ thread.** -3. **An approach was tried and abandoned.** -4. **You presented options** — a decision point exists by construction. -5. **A discovery contradicted an assumption.** - -**Then pick the instrument. The only test is whether a road was not taken:** - -| What happened | Do | -|---|---| -| A specific course was considered and **not taken** — a design, a scope item, a validation step, a target branch, a task you wrote and threw away | Decision bead **plus** its `rejected-alternative` sibling, now | -| Something is simply true, with no fork in it — evidence, a measurement, a discovery, a constraint | `bd comment <root> "..."` | - -**The rejected thing does not have to be a design.** "The operator declined X" is a road not -taken. So is "we were going to target master, we targeted 3.7-dev instead." If you can name -what was *not* done, it is a decision — write both beads. - -**Self-check before writing any comment: name what was *not* done.** If you can name it — a -course declined, a branch not targeted, an approach dropped — it is a decision bead, not a -comment. Wording like "the operator declined" or "X rather than Y" is the tell, but check -what it refers to: a choice about *the work* is a decision, while "the test frames HashMap -instead of OptionsStrategy" is just describing code and stays a comment. - -```bash -# Only when something was actually ruled out. No fork = implementation; the code documents that. -bd create --type=decision --parent=<root> --title="Chose X" --design="why, and what X rules out" -# The sibling is the road not taken — an approach you tried and abandoned counts, and is stronger -# evidence than a hypothetical, because someone already walked it. -bd create --type=decision --parent=<root> --title="Y" --labels="rejected-alternative" \ - --design="why Y was rejected" -bd dep add <decision> <alternative> -t related # never put either of these on a task bead -``` - -**Record what actually happened.** If you cannot point to the moment, do not write the bead. -When you sense a decision you were not party to, create a bead labelled `human` posing the -question instead of inventing an answer — `bd human respond <id>` turns the reply into a -comment. - --- ## 4. At merge — close the root, then pin
