You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2026/08/07 23:47:46 UTC
(tinkerpop) 04/16: Plan tasks as a dependency graph, not a flat list
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 247caabd23338ef40c82264b65826ce808c2db01
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Aug 7 06:44:44 2026 -0400
Plan tasks as a dependency graph, not a flat list
Task order was never wired, so bd ready was useless and nothing could run in
parallel. PRIME.md now covers blocks edges, ready/blocked, and linking a
decision to the work it caused. Rules that qualify a command moved into that
command's comment.
Assisted-by: Claude Code:claude-opus-5
---
.beads/PRIME.md | 64 +++++++++++++++++++++++++++++++++++++++++----------------
1 file changed, 46 insertions(+), 18 deletions(-)
diff --git a/.beads/PRIME.md b/.beads/PRIME.md
index b02b458c5c..3ac6fe06bf 100644
--- a/.beads/PRIME.md
+++ b/.beads/PRIME.md
@@ -43,7 +43,32 @@ Re-ask after a compaction rather than guessing.
---
-## 2. While working — claim first, then capture as you go
+## 2. Plan as a graph, not a list
+
+Tasks are not a checklist. Wire the order between them so the graph itself says what can run
+in parallel — that is the whole reason the plan lives in beads instead of prose.
+
+```bash
+bd dep add <task> <blocker> # <task> waits for <blocker> — NOT "task blocks blocker"
+bd dep add --file - <<< '{"from":"tp-a","to":"tp-b"}' # wire a whole plan at once
+bd ready # only `blocks` gates this; parent-child and related never do
+bd blocked # what is waiting, and on what
+bd dep cycles # a plan with a cycle cannot execute
+```
+
+- **Wire the order in the same pass as `bd create`.** Retrofitting it after work starts is
+ how you end up with a flat star and no parallelism.
+- **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.
+- **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 you start executing, run `bd ready`. If it returns every task you created, you built
+a list and called it a plan.
+
+---
+
+## 3. While working — claim first, then capture as you go
**Before you touch code for a bead, claim it. Every time, no exceptions:**
@@ -51,7 +76,7 @@ Re-ask after a compaction rather than guessing.
bd update <id> --claim # sets assignee to you, status to in_progress
```
-It stays `in_progress` until the PR merges — see section 3. That window **is** the memory:
+It stays `in_progress` until the PR merges — see section 4. That window **is** the memory:
a later session runs `bd list --status=in_progress` and learns what was underway, who had
it, and where it stopped. A bead that jumps from `open` straight to `closed` records that
the work happened but never that it was yours, never where you were when context ran out.
@@ -86,21 +111,15 @@ what it refers to: a choice about *the work* is a decision, while "the test fram
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
+bd dep add <decision> <alternative> -t related # never put either of these on a task bead
```
-If nothing was rejected, it is not a decision — it is the implementation, and the code
-documents that. Don't inflate.
-
-An approach you tried and abandoned **is** a rejected alternative — one you have evidence
-for. Record it; a dead end someone already walked is worth more than a hypothetical.
-
-Never put a decision on a task bead. The decision belongs in its own bead so the rejected
-sibling has something to hang off; a task records what to build, not what was ruled out.
-
**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
@@ -108,7 +127,7 @@ comment.
---
-## 3. At merge — close, then pin
+## 4. At merge — close, then pin
When the PR lands on its target branch:
@@ -130,7 +149,7 @@ Push freely as a checkpoint; pinning is what marks the durable record.
---
-## 4. Never
+## 5. Never
- **Never `bd flatten`, `bd compact`, or `bd admin compact`.** They rewrite or discard
history irreversibly. `admin compact` destroys `--design` text specifically. `bd gc` only
@@ -143,7 +162,7 @@ Push freely as a checkpoint; pinning is what marks the durable record.
---
-## 5. Structure
+## 6. Structure
```
root (feature/epic/task)
@@ -151,9 +170,14 @@ root (feature/epic/task)
├─relates-to──▶ record [pr] apache/tinkerpop#2891
├─parent-child─▶ decision "chose X"
│ └─related─▶ decision "Y" [rejected-alternative]
- └─parent-child─▶ task "implement X"
+ ├─parent-child─▶ task A "implement X" ──caused-by──▶ decision "chose X"
+ ├─parent-child─▶ task B ──blocks──▶ task A (B waits for A)
+ └─parent-child─▶ task C (no blocker: starts with A)
```
+`parent-child` gives membership, `blocks` gives order. A subtree with no `blocks` edges is
+a list, and `bd ready` cannot tell you anything useful about it.
+
- `--parent` builds the tree; labels inherit downward, so set module/release labels
(`gremlin-core`, `3.8`) once on the root.
- **`record` beads** hold external artifacts — JIRA, PR, dev@ thread, proposal. Kind is a
@@ -173,11 +197,15 @@ root (feature/epic/task)
```bash
bd children <root> # the subtree, recursive
+bd ready # what can be started now (blocks-aware)
+bd blocked # what is waiting, and on what
bd show <id> # one bead with dependencies
bd query "status=open AND type=decision"
-bd comment <id> "..." # append rationale (never on a task bead)
+bd comment <id> "..." # a fact with no fork in it (never on a task bead)
bd create --type=... --parent=<root> --design=... --labels=...
-bd dep add <a> <b> -t related|discovered-from|supersedes
+bd dep add <task> <blocker> # default type is blocks: <task> waits for <blocker>
+bd dep add <a> <b> -t caused-by|related|discovered-from|supersedes
+bd dep cycles # a plan with a cycle cannot execute
bd update <id> --claim | -s pinned | --external-ref=TINKERPOP-NNNN
bd search <text>
```