diff --git a/formulas/run-planner.toml b/formulas/run-planner.toml index 3848fce..2620841 100644 --- a/formulas/run-planner.toml +++ b/formulas/run-planner.toml @@ -151,13 +151,10 @@ 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. -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. +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. Naming: $OPS_REPO_ROOT/vault/pending/-.md (e.g. disinto-github-org.md). Write with this template: @@ -185,10 +182,37 @@ Stuck issue handling: 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. -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 +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 Priority label sync: - Add priority to current top-5 constraint issues (if missing): @@ -239,7 +263,7 @@ Format: 1. — blocks N objectives — #NNN (existing|filed) ## Stuck issues detected - - #NNN: BOUNCED (Nx) — dispatched groom-backlog as #MMM + - #NNN: vision-labeled (complexity test failed) — blocked on #NNN (or "No stuck issues detected") ## Vault items filed diff --git a/planner/AGENTS.md b/planner/AGENTS.md index 4f53f9f..84b511b 100644 --- a/planner/AGENTS.md +++ b/planner/AGENTS.md @@ -22,12 +22,13 @@ 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 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 +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 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. @@ -56,9 +57,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` — 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) +- `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.) - `$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