docs: Replace Epic Planning with Ready Front model

The Ready Front model replaces temporal 'phase' thinking: - Ready Front = issues with all deps satisfied (unblocked) - Static: natural topology (sync points, bottlenecks) - Dynamic: current wavefront of in-progress work Key changes: - Add cognitive trap warning (temporal language inverts deps) - Graph Walk Pattern: walk backward from goal - Requirement language: 'X needs Y' not 'X before Y' - Validation with bd blocked - Ready Fronts visualization
2025-12-28 21:35:15 -08:00
parent 2213fc016d
commit d5a87e839a
2 changed files with 100 additions and 27 deletions
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -161,7 +161,6 @@
 {"id":"bd-7p5l","title":"Fix N+1 query pattern in swarm status blocked check","description":"In getSwarmStatus, when checking if an issue is blocked, we query each dependency individually with GetIssue. With 100 issues and 5 deps each, thats 500 extra queries. Fix: Build a status map upfront from the already-fetched childIssues slice. File: cmd/bd/swarm.go:706-710","status":"in_progress","priority":2,"issue_type":"bug","created_at":"2025-12-28T21:31:07.586335-08:00","created_by":"beads/crew/emma","updated_at":"2025-12-28T21:33:58.862269-08:00","dependencies":[{"issue_id":"bd-7p5l","depends_on_id":"bd-m6r3","type":"blocks","created_at":"2025-12-28T21:31:17.309538-08:00","created_by":"daemon"}]}
 {"id":"bd-7pwh","title":"HOP-compatible schema additions","description":"Add optional fields to Beads schema to enable future HOP integration.\nAll fields are backwards-compatible (optional, omitted if empty).\n\n## Reference\nSee ~/gt/docs/hop/BEADS-SCHEMA-CHANGES.md for full specification.\n\n## P1 Changes (Must Have Before Launch)\n\n### 1. EntityRef type\nStructured entity reference that can become HOP URI:\n```go\ntype EntityRef struct {\n    Name     string // \"polecat/Nux\"\n    Platform string // \"gastown\"\n    Org      string // \"steveyegge\"  \n    ID       string // \"polecat-nux\"\n}\n```\n\n### 2. creator field\nEvery issue tracks who created it (EntityRef).\n\n### 3. assignee_ref field\nStructured form alongside existing string assignee.\n\n### 4. validations array\nTrack who validated work completion:\n```go\ntype Validation struct {\n    Validator *EntityRef\n    Outcome   string    // accepted, rejected, revision_requested\n    Timestamp time.Time\n    Score     *float32  // Future\n}\n```\n\n## P2 Changes (Should Have)\n\n### 5. work_type field\n\"mutex\" (default) or \"open_competition\"\n\n### 6. crystallizes field\nBoolean - does this work compound (true) or evaporate (false)?\n\n### 7. cross_refs field\nArray of URIs to beads in other repos:\n- \"beads://github/anthropics/claude-code/bd-xyz\"\n\n## P3 Changes (Nice to Have)\n\n### 8. skill_vector placeholder\nReserved for future embeddings: []float32\n\n## Implementation Notes\n- All fields optional in JSONL serialization\n- Empty/null fields omit from output\n- No migration needed for existing data\n- CLI additions: --creator, --validated-by filters","notes":"Scope reduced after review. P1 only: EntityRef type, creator field, validations array. Deferred: assignee_ref, work_type, crystallizes, cross_refs, skill_vector (YAGNI - semantics unclear, can add later when needed).","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-22T02:42:39.267984-08:00","updated_at":"2025-12-22T20:09:09.211821-08:00","closed_at":"2025-12-22T20:09:09.211821-08:00","close_reason":"HOP P1 schema additions complete: EntityRef type, Creator field, Validations array. P2/P3 items deferred to bd-zt59."}
 {"id":"bd-7tuu","title":"Commit and push release","description":"git add -A \u0026\u0026 git commit \u0026\u0026 git push to trigger CI","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-19T22:56:02.053382-08:00","updated_at":"2025-12-20T01:23:52.484043-08:00","closed_at":"2025-12-20T01:23:52.484043-08:00","close_reason":"Superseded by 0.30.7 release - already committed and pushed","dependencies":[{"issue_id":"bd-7tuu","depends_on_id":"bd-6s61","type":"parent-child","created_at":"2025-12-19T22:56:15.021087-08:00","created_by":"daemon"},{"issue_id":"bd-7tuu","depends_on_id":"bd-hw3w","type":"blocks","created_at":"2025-12-19T22:56:23.291591-08:00","created_by":"daemon"}]}
-{"id":"bd-7xrg","title":"Refinery Patrol","description":"Merge queue processor patrol loop with verification gates.","status":"open","priority":2,"issue_type":"molecule","created_at":"2025-12-27T18:14:31.190713-08:00","created_by":"deacon","updated_at":"2025-12-27T18:14:31.190713-08:00"}
 {"id":"bd-7yg","title":"Git merge driver uses invalid placeholders (%L, %R instead of %A, %B)","description":"## Problem\n\nThe beads git merge driver is configured with invalid Git placeholders:\n\n```\ngit config merge.beads.driver \"bd merge %A %O %L %R\"\n```\n\nGit doesn't recognize `%L` or `%R` as valid merge driver placeholders. The valid placeholders are:\n- `%O` = base (common ancestor)\n- `%A` = current version (ours)\n- `%B` = other version (theirs)\n\n## Impact\n\n- Affects ALL users when they have `.beads/beads.jsonl` merge conflicts\n- Automatic JSONL merge fails with error: \"error reading left file: failed to open file: open 7: no such file or directory\"\n- Users must manually resolve conflicts instead of getting automatic merge\n\n## Root Cause\n\nThe `bd init` command (or wherever the merge driver is configured) is using non-standard placeholders. When Git encounters `%L` and `%R`, it either passes them literally or interprets them incorrectly.\n\n## Fix\n\nUpdate the merge driver configuration to:\n```\ngit config merge.beads.driver \"bd merge %A %O %A %B\"\n```\n\nWhere:\n- 1st `%A` = output file (current file, will be overwritten)\n- `%O` = base (common ancestor)\n- 2nd `%A` = left/current version\n- `%B` = right/other version\n\n## Action Items\n\n1. Fix `bd init` (or equivalent setup command) to use correct placeholders\n2. Add migration/warning for existing users with misconfigured merge driver\n3. Update documentation with correct merge driver setup\n4. Consider adding validation when `bd init` is run","status":"tombstone","priority":1,"issue_type":"bug","created_at":"2025-11-21T19:51:55.747608-05:00","updated_at":"2025-12-25T01:21:01.952723-08:00","deleted_at":"2025-12-25T01:21:01.952723-08:00","deleted_by":"batch delete","delete_reason":"batch delete","original_type":"bug"}
 {"id":"bd-7z4","title":"Add tests for delete operations","description":"Core delete functionality including deleteViaDaemon, createTombstone, and deleteIssue functions have 0% coverage. These are critical for data integrity and need comprehensive test coverage.","status":"closed","priority":1,"issue_type":"task","assignee":"beads/slit","created_at":"2025-12-18T07:00:34.867680882-07:00","updated_at":"2025-12-23T23:48:50.087306-08:00","closed_at":"2025-12-23T23:48:50.087306-08:00","close_reason":"Added comprehensive tests for deleteViaDaemon, createTombstone, and deleteIssue functions","dependencies":[{"issue_id":"bd-7z4","depends_on_id":"bd-6ss","type":"discovered-from","created_at":"2025-12-18T07:00:34.870254935-07:00","created_by":"matt"}]}
 {"id":"bd-7zka","title":"Implement formula features: repeat, for_each, branch, gate, compose.split","description":"Multiple formula features in internal/formula/types.go are marked as 'Not yet implemented':\n\n- Line 170: repeat field (run step multiple times)\n- Line 174: for_each field (iterate over collections)\n- Line 179: branch field (conditional step execution)\n- Line 186: gate field (waits_for dependency integration)\n- Line 210: compose.split field (split step into parallel sub-steps)\n\nThese are schema-defined for future use but not yet implemented in bd cook.\n\nFile: internal/formula/types.go:170,174,179,186,210","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-28T16:32:54.493002-08:00","created_by":"stevey","updated_at":"2025-12-28T16:32:54.493002-08:00"}
@@ -318,7 +317,6 @@
 {"id":"bd-fber","title":"Work on gt-8tmz.31: Formula validation specification. Wri...","description":"Work on gt-8tmz.31: Formula validation specification. Write docs/formula-validation.md specifying all validation rules for formulas. When done: 1) bd close gt-8tmz.31, 2) bd sync, 3) git push, 4) gt mq submit","status":"closed","priority":2,"issue_type":"task","assignee":"beads/slit","created_at":"2025-12-25T19:26:36.741916-08:00","updated_at":"2025-12-25T19:32:10.788141-08:00","closed_at":"2025-12-25T19:32:10.788141-08:00","close_reason":"Completed: wrote docs/formula-validation.md with full specification of parse-time, cook-time, and instantiation-time validation rules"}
 {"id":"bd-fbl9","title":"Test parent task","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-27T23:26:53.012747-08:00","created_by":"beads/crew/emma","updated_at":"2025-12-27T23:27:40.44858-08:00","closed_at":"2025-12-27T23:27:40.44858-08:00","close_reason":"Test issues, cleanup"}
 {"id":"bd-fcl1","title":"Merge: bd-au0.5","description":"branch: polecat/Searcher\ntarget: main\nsource_issue: bd-au0.5\nrig: beads","status":"closed","priority":1,"issue_type":"merge-request","created_at":"2025-12-23T13:39:11.946667-08:00","updated_at":"2025-12-23T19:12:08.346454-08:00","closed_at":"2025-12-23T19:12:08.346454-08:00","close_reason":"Stale merge-requests from orphaned polecat branches - refinery not processing"}
-{"id":"bd-fd0w","title":"Witness Patrol","description":"Per-rig worker monitor patrol loop with progressive nudging.","status":"open","priority":2,"issue_type":"molecule","created_at":"2025-12-27T18:14:26.008274-08:00","created_by":"deacon","updated_at":"2025-12-27T18:14:26.008274-08:00"}
 {"id":"bd-fedb","title":"Polecats should spawn with auto-accept mode enabled","description":"During swarm bd-784c, polecats (Toast, Nux) were spawned without --dangerously-skip-permissions or equivalent auto-accept mode.\n\n**Problem:**\nEvery edit, bash command, and tool use required manual confirmation via tmux send-keys. This defeats the purpose of autonomous polecat operation.\n\n**Expected:**\nPolecats in a swarm should run with permissions bypassed so they can work autonomously.\n\n**Workaround used:**\n- Manually sent Enter keys via tmux to accept prompts\n- Eventually polecats entered 'bypass permissions on' mode after restart\n\n**Suggestion:**\n- gt sling should pass --dangerously-skip-permissions by default for polecats\n- Or polecats should have a .claude/settings.local.json pre-configured for auto-accept","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-28T16:17:47.061327-08:00","created_by":"beads/crew/dave","updated_at":"2025-12-28T16:17:47.061327-08:00"}
 {"id":"bd-fej5","title":"bd hook: detect agent from cwd instead of defaulting to $USER","description":"**Problem:**\n`bd hook` without `--agent` defaults to `$USER` (e.g., \"stevey\") instead of detecting the agent identity from the current working directory.\n\n**Expected behavior:**\nWhen running from `/Users/stevey/gt/beads/crew/dave`, the agent should be detected as `beads/crew/dave`.\n\n**Current behavior:**\n```bash\n$ pwd\n/Users/stevey/gt/beads/crew/dave\n$ bd hook\nHook: stevey\n  (empty)\n\n$ bd hook --agent beads/crew/dave\nHook: beads/crew/dave\n  📌 bd-hobo (mol) - open\n```\n\n**Fix:**\nbd hook should use the same cwd-based agent detection that other commands use (similar to how `gt mail` determines identity from cwd).","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-24T20:01:27.613892-08:00","updated_at":"2025-12-25T12:41:10.65257-08:00","closed_at":"2025-12-25T12:41:10.65257-08:00","close_reason":"Obsolete: fix belongs in gastown - gt should set BD_ACTOR env var when spawning agents. bd already checks BD_ACTOR."}
 {"id":"bd-ffjt","title":"Unify template.go and mol.go under bd mol","description":"Consolidate the two DAG-template systems into one under the mol command. mol.go (on rictus branch) has the right UX (catalog/show/bond), template.go has the mechanics. Merge them, deprecate bd template commands.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-20T23:52:13.208972-08:00","updated_at":"2025-12-21T00:01:59.283765-08:00","closed_at":"2025-12-21T00:01:59.283765-08:00","close_reason":"Implemented mol commands with deprecation for template commands"}
@@ -505,7 +503,7 @@
 {"id":"bd-njrm","title":"Work on gt-8tmz.34: Expansion var overrides not implement...","description":"Work on gt-8tmz.34: Expansion var overrides not implemented. The ExpandRule.Vars field exists in internal/formula/types.go but is ignored during expansion in internal/formula/expand.go. Implement: 1) Pass rule.Vars to expandStep in ApplyExpansions, 2) Merge vars with formula defaults (rule.Vars wins), 3) Substitute vars in template placeholders, 4) Add test in expand_test.go. When done, commit and push to main.","status":"closed","priority":2,"issue_type":"task","assignee":"beads/nux","created_at":"2025-12-25T20:01:13.586558-08:00","updated_at":"2025-12-25T20:06:11.099142-08:00","closed_at":"2025-12-25T20:06:11.099142-08:00","close_reason":"Implemented expansion var overrides in internal/formula/expand.go"}
 {"id":"bd-nkqx","title":"bd swarm validate command","description":"Add bd swarm validate to check epic structure for swarming.\n\n## Context\nBefore running a swarm, we need to validate the epic structure:\n- Are dependencies correct (not inverted)?\n- Are there orphaned issues?\n- Is the DAG well-formed?\n\nThe Ready Front model (not phases!) means dependencies define execution order.\nCommon mistake: 'Phase 1 before Phase 2' → inverted deps.\nCorrect thinking: 'Phase 2 needs Phase 1' → bd dep add phase2 phase1\n\n## Implementation\n1. New command: bd swarm validate \u003cepic-id\u003e\n2. Walk the dependency DAG from epic children\n3. Detect issues:\n   - Root issues with no dependents (orphans?)\n   - Leaf issues depending on nothing (missing deps?)\n   - Cycles (impossible)\n   - Disconnected subgraphs\n4. Report:\n   - Ready fronts (waves of parallel work)\n   - Estimated worker-sessions\n   - Max parallelism\n   - Warnings for potential issues\n\n## Reference\n~/gt/docs/swarm-architecture.md - 'The Ready Front Model' section\n\n## Acceptance\n- bd swarm validate \u003cepic\u003e runs\n- Reports ready fronts accurately\n- Warns about structural issues\n- Returns success/failure exit code","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-28T19:11:08.788203-08:00","created_by":"mayor","updated_at":"2025-12-28T19:34:57.218009-08:00","closed_at":"2025-12-28T19:34:57.218009-08:00","close_reason":"Implemented bd swarm validate command with ready front analysis, structural issue detection, and swarmability check"}
 {"id":"bd-nl2","title":"No logging/debugging for tombstone resurrection events","description":"Per the design document bd-zvg Open Question 1: Should resurrection log a warning? Recommendation was Yes. Currently, when an expired tombstone loses to a live issue (resurrection), there is no logging or debugging output. This makes it hard to understand why an issue reappeared. Recommendation: Add optional debug logging when resurrection occurs, e.g., Issue bd-abc resurrected (tombstone expired). Files: internal/merge/merge.go:359-366, 371-378, 400-405, 410-415","status":"open","priority":4,"issue_type":"feature","created_at":"2025-12-05T16:36:52.27525-08:00","updated_at":"2025-12-05T16:36:52.27525-08:00"}
-{"id":"bd-nlzv","title":"bd show --short flag for compact output","description":"## Request\nAdd a `--short` flag to `bd show` for compact, one-line output per issue.\n\n## Use Case\nWhen checking multiple issues quickly:\n```bash\nbd show bd-nkqx --short \u0026\u0026 bd show bd-oxgi --short\n```\n\nCurrently fails with \"unknown flag: --short\"\n\n## Expected Output\nSomething like:\n```\nbd-nkqx [closed] P1 task: Validate swarm schema design\nbd-oxgi [closed] P1 task: Add mol_type schema field to beads\n```\n\n## Format Suggestion\n`\u003cid\u003e [\u003cstatus\u003e] \u003cpriority\u003e \u003ctype\u003e: \u003ctitle\u003e`\n\nOptional: include blocker count if any, e.g. `(blocked by 2)`","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-28T21:26:18.955592-08:00","created_by":"mayor","updated_at":"2025-12-28T21:26:18.955592-08:00"}
+{"id":"bd-nlzv","title":"bd show --short flag for compact output","description":"## Request\nAdd a `--short` flag to `bd show` for compact, one-line output per issue.\n\n## Use Case\nWhen checking multiple issues quickly:\n```bash\nbd show bd-nkqx --short \u0026\u0026 bd show bd-oxgi --short\n```\n\nCurrently fails with \"unknown flag: --short\"\n\n## Expected Output\nSomething like:\n```\nbd-nkqx [closed] P1 task: Validate swarm schema design\nbd-oxgi [closed] P1 task: Add mol_type schema field to beads\n```\n\n## Format Suggestion\n`\u003cid\u003e [\u003cstatus\u003e] \u003cpriority\u003e \u003ctype\u003e: \u003ctitle\u003e`\n\nOptional: include blocker count if any, e.g. `(blocked by 2)`","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-28T21:26:18.955592-08:00","created_by":"mayor","updated_at":"2025-12-28T21:35:06.006865-08:00","closed_at":"2025-12-28T21:35:06.006865-08:00","close_reason":"Implemented --short flag in commit e18cc4dc"}
 {"id":"bd-nmch","title":"Add EntityRef type for structured entity references","description":"Create EntityRef struct with Name, Platform, Org, ID fields. This is the foundation for HOP entity tracking. Can render as entity://hop/\u003cplatform\u003e/\u003corg\u003e/\u003cid\u003e when needed. Add to internal/types/types.go.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-22T17:53:25.104328-08:00","updated_at":"2025-12-22T17:58:00.014103-08:00","closed_at":"2025-12-22T17:58:00.014103-08:00","close_reason":"Implemented EntityRef type with Name, Platform, Org, ID fields. Added URI(), IsEmpty(), String() methods and ParseEntityURI() function. Full test coverage.","dependencies":[{"issue_id":"bd-nmch","depends_on_id":"bd-7pwh","type":"parent-child","created_at":"2025-12-22T17:53:43.325405-08:00","created_by":"daemon"}]}
 {"id":"bd-nppb","title":"Refinery Patrol","description":"Merge queue processor patrol loop with verification gates.","status":"tombstone","priority":2,"issue_type":"molecule","created_at":"2025-12-26T13:08:21.308272-08:00","updated_at":"2025-12-27T00:10:54.177947-08:00","deleted_at":"2025-12-27T00:10:54.177947-08:00","deleted_by":"daemon","delete_reason":"delete","original_type":"molecule"}
 {"id":"bd-nqyp","title":"mol-beads-release","description":"Release checklist for beads version {{version}}.\n\nThis molecule ensures all release steps are completed properly.\nVariable: {{version}} - target version (e.g., 0.35.0)\n\n## Step: update-release-notes\nUpdate cmd/bd/info.go with release notes for {{version}}.\n\nAdd a new VersionChange entry at the top of versionChanges slice:\n```go\n{\n    Version: \"{{version}}\",\n    Date:    \"YYYY-MM-DD\",\n    Changes: []string{\n        \"NEW: Feature description\",\n        \"FIX: Bug fix description\",\n        \"IMPROVED: Enhancement description\",\n    },\n},\n```\n\nRun `git log --oneline v\u003cprevious\u003e..HEAD` to see what changed.\n\n## Step: update-changelog\nUpdate CHANGELOG.md with detailed release notes.\n\nAdd a new section after [Unreleased]:\n```markdown\n## [{{version}}] - YYYY-MM-DD\n\n### Added\n- **Feature name** (issue-id) - Description\n\n### Changed\n- **Change description** (issue-id)\n\n### Fixed\n- **Bug fix** (issue-id) - Description\n```\n\nSort by importance, not chronologically.\nNeeds: update-release-notes\n\n## Step: bump-version\nRun the version bump script.\n\n```bash\n./scripts/bump-version.sh {{version}}\n```\n\nThis updates version in all files:\n- cmd/bd/version.go\n- .claude-plugin/*.json\n- integrations/beads-mcp/pyproject.toml\n- npm-package/package.json\n- Hook templates\n\nNeeds: update-changelog\n\n## Step: run-tests\nRun tests and verify lint passes.\n\n```bash\ngo test -short ./...\n```\n\nCI will run full lint, but fix any obvious issues first.\nNeeds: bump-version\n\n## Step: commit-release\nCommit the release changes.\n\n```bash\ngit add -A\ngit commit -m \"chore: bump version to v{{version}}\"\n```\n\nNeeds: run-tests\n\n## Step: push-and-tag\nPush commit and create release tag.\n\n```bash\ngit push origin main\ngit tag v{{version}}\ngit push origin v{{version}}\n```\n\nThis triggers GitHub Actions release workflow.\nNeeds: commit-release\n\n## Step: wait-for-ci\nWait for GitHub Actions to complete.\n\nMonitor: https://github.com/steveyegge/beads/actions\n\nCI will:\n- Build binaries via GoReleaser\n- Create GitHub Release with assets\n- Publish to npm (@beads/bd)\n- Publish to PyPI (beads-mcp)\n- Update Homebrew tap\n\nWait until all jobs succeed (~5-10 min).\nNeeds: push-and-tag\n\n## Step: verify-release\nVerify the release is complete.\n\n```bash\n# Check GitHub release\ngh release view v{{version}}\n\n# Check Homebrew\nbrew update \u0026\u0026 brew info steveyegge/beads/bd\n\n# Check npm\nnpm view @beads/bd version\n\n# Check PyPI\npip index versions beads-mcp\n```\n\nNeeds: wait-for-ci\n\n## Step: update-local\nUpdate local installations with proper codesigning (macOS).\n\n```bash\n# Build from source in mayor/rig (canonical build location)\ncd ~/gt/beads/mayor/rig\ngit pull\ngo build -o bd ./cmd/bd\n\n# Sign and install (macOS requires codesigning to avoid \"Killed: 9\")\n# Uses fix-gt script which handles both gt and bd binaries\nfix-gt\n\n# Or manually sign if fix-gt not available:\n# xattr -cr bd \u0026\u0026 codesign -f -s - bd\n# cp bd ~/go/bin/bd \u0026\u0026 codesign -f -s - ~/go/bin/bd\n# cp bd ~/.local/bin/bd \u0026\u0026 codesign -f -s - ~/.local/bin/bd\n\n# Install MCP locally\npip install -e integrations/beads-mcp\n\n# Restart daemons\npkill -f \"bd daemon\" || true\n```\n\nVerify: `bd --version` shows {{version}}\nNeeds: verify-release\n\n## Step: manual-publish\n(Optional) Manual publish if CI failed.\n\n```bash\n# npm (requires npm login)\n./scripts/bump-version.sh {{version}} --publish-npm\n\n# PyPI (requires TWINE credentials)\n./scripts/bump-version.sh {{version}} --publish-pypi\n\n# Or both\n./scripts/bump-version.sh {{version}} --publish-all\n```\n\nOnly needed if CI publishing failed.\nNeeds: wait-for-ci","status":"tombstone","priority":2,"issue_type":"molecule","created_at":"2025-12-23T11:29:39.087936-08:00","updated_at":"2025-12-28T01:26:51.06645-08:00","labels":["template"],"deleted_at":"2025-12-28T01:26:51.06645-08:00","deleted_by":"daemon","delete_reason":"delete","original_type":"molecule"}
--- a/skills/beads/references/WORKFLOWS.md
+++ b/skills/beads/references/WORKFLOWS.md
@@ -144,42 +144,117 @@ Issue Lifecycle:

 ## Epic Planning {#epic-planning}

-**For complex multi-step features:**
+**For complex multi-step features, think in Ready Fronts, not phases.**
+
+### The Ready Front Model
+
+A **Ready Front** is the set of issues with all dependencies satisfied - what can be worked on *right now*. As issues close, the front advances. The dependency DAG IS the execution plan.

 ```
-Epic Planning Workflow:
+Ready Front = Issues where all dependencies are closed
+              (no blockers remaining)
+
+Static view:  Natural topology in the DAG (sync points, bottlenecks)
+Dynamic view: Current wavefront of in-progress work
+```
+
+**Why Ready Fronts, not Phases?**
+
+"Phases" trigger temporal reasoning that inverts dependencies:
+
+```
+⚠️ COGNITIVE TRAP:
+"Phase 1 before Phase 2" → brain thinks "Phase 1 blocks Phase 2"
+                         → WRONG: bd dep add phase1 phase2
+
+Correct: "Phase 2 needs Phase 1" → bd dep add phase2 phase1
+```
+
+**The fix**: Name issues by what they ARE, think about what they NEED.
+
+### Epic Planning Workflow
+
+```
+Epic Planning with Ready Fronts:
 - [ ] Create epic issue for high-level goal
- [ ] Break down into child task issues
- [ ] Create each child task
- [ ] Add parent-child dependencies from epic to each child
- [ ] Add blocks dependencies between children if needed
- [ ] Use bd ready to work through tasks in dependency order
+- [ ] Walk backward from goal: "What does the end state need?"
+- [ ] Create child issues named by WHAT, not WHEN
+- [ ] Add deps using requirement language: "X needs Y" → bd dep add X Y
+- [ ] Verify with bd blocked (tasks blocked BY prerequisites, not dependents)
+- [ ] Use bd ready to work through in dependency order
 ```

-**Example**: OAuth Integration Epic
+### The Graph Walk Pattern
+
+Walk **backward** from the goal to get correct dependencies:
+
+```
+Start: "What's the final deliverable?"
+       ↓
+       "Integration tests passing" → gt-integration
+       ↓
+"What does that need?"
+       ↓
+       "Streaming support" → gt-streaming
+       "Header display" → gt-header
+       ↓
+"What do those need?"
+       ↓
+       "Message rendering" → gt-messages
+       ↓
+"What does that need?"
+       ↓
+       "Buffer layout" → gt-buffer (foundation, no deps)
+```
+
+This produces correct deps because you're asking "X needs Y", not "X before Y".
+
+### Ready Fronts Visualized
+
+```
+Ready Front 1:  gt-buffer (foundation)
+Ready Front 2:  gt-messages (needs buffer)
+Ready Front 3:  gt-streaming, gt-header (parallel, need messages)
+Ready Front 4:  gt-integration (needs streaming, header)
+```
+
+At any moment, `bd ready` shows the current front. As issues close, blocked work becomes ready.
+
+### Example: OAuth Integration

 ```bash
-1. Create epic:
-   bd create "Implement OAuth integration" -t epic -d "OAuth with Google and GitHub"
-     design: "Support Google and GitHub providers"
+# Create epic (the goal)
+bd create "OAuth integration" -t epic

-2. Create child tasks:
-   bd create "Set up OAuth client credentials" -t task
-   bd create "Implement authorization code flow" -t task
-   bd create "Add token storage and refresh" -t task
-   bd create "Create login/logout endpoints" -t task
+# Walk backward: What does OAuth need?
+bd create "Login/logout endpoints" -t task        # needs token storage
+bd create "Token storage and refresh" -t task     # needs auth flow
+bd create "Authorization code flow" -t task       # needs credentials
+bd create "OAuth client credentials" -t task      # foundation

-3. Link children to parent:
-   bd dep add oauth-epic oauth-setup --type parent-child
-   bd dep add oauth-epic oauth-flow --type parent-child
-   bd dep add oauth-epic oauth-storage --type parent-child
-   bd dep add oauth-epic oauth-endpoints --type parent-child
+# Add deps using requirement language: "X needs Y"
+bd dep add endpoints storage      # endpoints need storage
+bd dep add storage flow           # storage needs flow
+bd dep add flow credentials       # flow needs credentials
+# credentials has no deps - it's Ready Front 1

-4. Add blocks between children:
-   bd dep add oauth-setup oauth-flow
-   # Setup blocks flow implementation
+# Verify: bd blocked should show sensible blocking
+bd blocked
+# endpoints blocked by storage ✓
+# storage blocked by flow ✓
+# flow blocked by credentials ✓
+# credentials ready ✓
 ```

+### Validation
+
+After adding deps, verify with `bd blocked`:
+- Tasks should be blocked BY their prerequisites
+- NOT blocked by their dependents
+
+If `gt-integration` is blocked by `gt-setup` → correct
+If `gt-setup` is blocked by `gt-integration` → deps are inverted, fix them
+
 ---

 ## Side Quest Handling {#side-quests}