johba/disinto
1
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

fix: refactor: tighten planner issue filing — template-or-vision gate (#95)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details

Browse source
This commit is contained in:
Agent 2026-04-01 08:57:14 +00:00
parent 56d1c4bae9
commit 2d72e0e565
2 changed files with 46 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

48
formulas/run-planner.toml
View file

@ -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. A constraint is an unresolved prerequisite blocking the most downstream objectives.
Graph bottlenecks (high betweenness centrality) and thin objectives inform ranking. Graph bottlenecks (high betweenness centrality) and thin objectives inform ranking.
Stuck issue handling: HUMAN_BLOCKED handling (needs human decision or external resource):
- BOUNCED/LABEL_CHURN: do NOT re-promote. Dispatch groom-backlog formula instead: - File a vault procurement item instead of skipping. First check for duplicates
tea_file_issue "chore: break down #<N> — bounced <count>x" "<body>" "action" across ALL vault directories (pending/, approved/, fired/) — if a file with the
- HUMAN_BLOCKED (needs human decision or external resource): file a vault same slug already exists in any of them, do NOT create a new one.
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/<project>-<slug>.md (e.g. disinto-github-org.md). Naming: $OPS_REPO_ROOT/vault/pending/<project>-<slug>.md (e.g. disinto-github-org.md).
Write with this template: 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/<id>.md)". Then mark the prerequisite in the tree as "blocked-on-vault ($OPS_REPO_ROOT/vault/pending/<id>.md)".
Do NOT skip or mark as "awaiting human decision" — the vault owns the human interface. Do NOT skip or mark as "awaiting human decision" — the vault owns the human interface.
Filing gate (for non-stuck constraints): Template-or-vision filing gate (for non-stuck constraints):
1. Check if issue already exists (match by #number in tree or title search) 1. Read issue templates from .codeberg/ISSUE_TEMPLATE/*.yaml:
2. If no issue, create one with tea_file_issue using the template above - bug.yaml: for broken/incorrect behavior (error in logs, failing test)
3. If issue exists and is open, skip — no duplicates - 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: Priority label sync:
- Add priority to current top-5 constraint issues (if missing): - Add priority to current top-5 constraint issues (if missing):
@ -239,7 +263,7 @@ Format:
1. <prerequisite> — blocks N objectives — #NNN (existing|filed) 1. <prerequisite> — blocks N objectives — #NNN (existing|filed)
## Stuck issues detected ## 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") (or "No stuck issues detected")
## Vault items filed ## Vault items filed

19
planner/AGENTS.md
View file

@ -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 need human decisions or external resources are filed as vault procurement items
(`$OPS_REPO_ROOT/vault/pending/*.md`) instead of being escalated. Phase 3 (`$OPS_REPO_ROOT/vault/pending/*.md`) instead of being escalated. Phase 3
(file-at-constraints): identify the top 3 unresolved prerequisites that block (file-at-constraints): identify the top 3 unresolved prerequisites that block
the most downstream objectives — file issues as either `backlog` (code changes, the most downstream objectives — file issues using a **template-or-vision gate**:
dev-agent) or `action` (run existing formula, dispatcher). **Stuck issues read issue templates from `.codeberg/ISSUE_TEMPLATE/*.yaml`, attempt to fill
(detected BOUNCED/LABEL_CHURN) are dispatched to the `groom-backlog` formula template fields (affected_files ≤3, acceptance_criteria ≤5, single clear approach),
in breakdown mode instead of being re-promoted** — this breaks the ping-pong then apply complexity test: if work touches one subsystem with no design forks,
loop by splitting them into dev-agent-sized sub-issues. **Human-blocked issues file as `backlog` using matching template (bug/feature/refactor); otherwise
are routed through the vault** — the planner files an actionable procurement 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/<project>-<slug>.md` with What/Why/Human action/Factory item (`$OPS_REPO_ROOT/vault/pending/<project>-<slug>.md` with What/Why/Human action/Factory
will then sections) and marks the prerequisite as blocked-on-vault in the tree. will then sections) and marks the prerequisite as blocked-on-vault in the tree.
Deduplication: checks pending/ + approved/ + fired/ before creating. Deduplication: checks pending/ + approved/ + fired/ before creating.
@ -56,9 +57,9 @@ component, not work.
prediction-triage, update-prerequisite-tree, file-at-constraints, prediction-triage, update-prerequisite-tree, file-at-constraints,
journal-and-memory, commit-and-pr) with `needs` dependencies. Claude journal-and-memory, commit-and-pr) with `needs` dependencies. Claude
executes all steps in a single interactive session with tool access executes all steps in a single interactive session with tool access
- `formulas/groom-backlog.toml` — Dual-mode formula: grooming (default) or - `formulas/groom-backlog.toml` — Grooming formula for backlog triage and
breakdown (dispatched by planner for bounced/stuck issues — splits the issue grooming. (Note: the planner no longer dispatches breakdown mode — complex
into dev-agent-sized sub-issues, removes `underspecified` label) issues are labeled `vision` instead.)
- `$OPS_REPO_ROOT/prerequisites.md` — Prerequisite tree: versioned constraint - `$OPS_REPO_ROOT/prerequisites.md` — Prerequisite tree: versioned constraint
map linking VISION.md objectives to their prerequisites. Planner owns the map linking VISION.md objectives to their prerequisites. Planner owns the
tree, humans steer by editing VISION.md. Tree grows organically as the tree, humans steer by editing VISION.md. Tree grows organically as the