diff --git a/formulas/run-planner.toml b/formulas/run-planner.toml index 2620841..3848fce 100644 --- a/formulas/run-planner.toml +++ b/formulas/run-planner.toml @@ -151,10 +151,13 @@ From the updated tree + graph bottlenecks, identify the top 5 constraints. A constraint is an unresolved prerequisite blocking the most downstream objectives. Graph bottlenecks (high betweenness centrality) and thin objectives inform ranking. -HUMAN_BLOCKED handling (needs human decision or external resource): - - File a vault procurement item instead of skipping. First check for duplicates - across ALL vault directories (pending/, approved/, fired/) — if a file with the - same slug already exists in any of them, do NOT create a new one. +Stuck issue handling: + - BOUNCED/LABEL_CHURN: do NOT re-promote. Dispatch groom-backlog formula instead: + tea_file_issue "chore: break down # — bounced x" "" "action" + - HUMAN_BLOCKED (needs human decision or external resource): file a vault + procurement item instead of skipping. First check for duplicates across ALL + vault directories (pending/, approved/, fired/) — if a file with the same + slug already exists in any of them, do NOT create a new one. Naming: $OPS_REPO_ROOT/vault/pending/-.md (e.g. disinto-github-org.md). Write with this template: @@ -182,37 +185,10 @@ HUMAN_BLOCKED handling (needs human decision or external resource): Then mark the prerequisite in the tree as "blocked-on-vault ($OPS_REPO_ROOT/vault/pending/.md)". Do NOT skip or mark as "awaiting human decision" — the vault owns the human interface. -Template-or-vision filing gate (for non-stuck constraints): - 1. Read issue templates from .codeberg/ISSUE_TEMPLATE/*.yaml: - - bug.yaml: for broken/incorrect behavior (error in logs, failing test) - - feature.yaml: for new capabilities (prerequisite doesn't exist) - - refactor.yaml: for restructuring without behavior change - - 2. Attempt to fill template fields: - - affected_files: list 3 or fewer specific files - - acceptance_criteria: write concrete, checkable criteria (max 5) - - proposed_solution/approach: is there one clear approach, or design forks? - - 3. Complexity test: - - If work touches ONE subsystem (3 or fewer files) AND no design forks - (only one reasonable approach) AND template fields fill confidently: - → File as `backlog` using matching template format - - Otherwise → Label `vision` with short body: - - Problem statement - - Why it's vision-sized - - Which objectives it blocks - - Include "## Why vision" section explaining complexity - - 4. Template selection heuristic: - - Bug template: planner identifies something broken (error in logs, - incorrect behavior, failing test) - - Feature template: new capability needed (prerequisite doesn't exist) - - Refactor template: existing code needs restructuring without behavior change - - 5. Filing steps: - - Check if issue already exists (match by #number in tree or title search) - - If no issue, create with tea_file_issue using template format - - If issue exists and is open, skip — no duplicates +Filing gate (for non-stuck constraints): + 1. Check if issue already exists (match by #number in tree or title search) + 2. If no issue, create one with tea_file_issue using the template above + 3. If issue exists and is open, skip — no duplicates Priority label sync: - Add priority to current top-5 constraint issues (if missing): @@ -263,7 +239,7 @@ Format: 1. — blocks N objectives — #NNN (existing|filed) ## Stuck issues detected - - #NNN: vision-labeled (complexity test failed) — blocked on #NNN + - #NNN: BOUNCED (Nx) — dispatched groom-backlog as #MMM (or "No stuck issues detected") ## Vault items filed diff --git a/planner/AGENTS.md b/planner/AGENTS.md index 84b511b..4f53f9f 100644 --- a/planner/AGENTS.md +++ b/planner/AGENTS.md @@ -22,13 +22,12 @@ to detect issues ping-ponging between backlog and underspecified. Issues that need human decisions or external resources are filed as vault procurement items (`$OPS_REPO_ROOT/vault/pending/*.md`) instead of being escalated. Phase 3 (file-at-constraints): identify the top 3 unresolved prerequisites that block -the most downstream objectives — file issues using a **template-or-vision gate**: -read issue templates from `.codeberg/ISSUE_TEMPLATE/*.yaml`, attempt to fill -template fields (affected_files ≤3, acceptance_criteria ≤5, single clear approach), -then apply complexity test: if work touches one subsystem with no design forks, -file as `backlog` using matching template (bug/feature/refactor); otherwise -label `vision` with problem statement and why it's vision-sized. **Human-blocked -issues are routed through the vault** — the planner files an actionable procurement +the most downstream objectives — file issues as either `backlog` (code changes, +dev-agent) or `action` (run existing formula, dispatcher). **Stuck issues +(detected BOUNCED/LABEL_CHURN) are dispatched to the `groom-backlog` formula +in breakdown mode instead of being re-promoted** — this breaks the ping-pong +loop by splitting them into dev-agent-sized sub-issues. **Human-blocked issues +are routed through the vault** — the planner files an actionable procurement item (`$OPS_REPO_ROOT/vault/pending/-.md` with What/Why/Human action/Factory will then sections) and marks the prerequisite as blocked-on-vault in the tree. Deduplication: checks pending/ + approved/ + fired/ before creating. @@ -57,9 +56,9 @@ component, not work. prediction-triage, update-prerequisite-tree, file-at-constraints, journal-and-memory, commit-and-pr) with `needs` dependencies. Claude executes all steps in a single interactive session with tool access -- `formulas/groom-backlog.toml` — Grooming formula for backlog triage and - grooming. (Note: the planner no longer dispatches breakdown mode — complex - issues are labeled `vision` instead.) +- `formulas/groom-backlog.toml` — Dual-mode formula: grooming (default) or + breakdown (dispatched by planner for bounced/stuck issues — splits the issue + into dev-agent-sized sub-issues, removes `underspecified` label) - `$OPS_REPO_ROOT/prerequisites.md` — Prerequisite tree: versioned constraint map linking VISION.md objectives to their prerequisites. Planner owns the tree, humans steer by editing VISION.md. Tree grows organically as the