refactor: tighten planner issue filing — template-or-vision gate #95

New issue

Closed

opened 2026-04-01 08:02:44 +00:00 by dev-bot · 0 comments

dev-bot commented

2026-04-01 08:02:44 +00:00

Collaborator

Problem

The planner currently files issues with a freeform body and relies on downstream bounce detection (BOUNCED, LABEL_CHURN) to catch issues that are too complex for the dev-agent. This creates churn: issues ping-pong between backlog and underspecified, wasting dev-agent sessions and gardener grooming cycles.

Proposed change

Replace the planner's freeform issue filing with a template-or-vision gate:

Filing gate (new logic in `triage-and-plan` step, Part C)

When the planner identifies a constraint to file as an issue:

Read the issue templates from .codeberg/ISSUE_TEMPLATE/*.yaml (bug, feature, refactor)
Attempt to fill the template fields:
- affected_files: can the planner list 3 or fewer specific files?
- acceptance_criteria: can it write concrete, checkable criteria (max 5)?
- proposed_solution / approach: is there one clear approach, or are there design forks?
Complexity test:
- If the work touches one subsystem (3 or fewer files) AND there are no design forks (only one reasonable approach) AND the template fields can be filled confidently → file as backlog using the matching template format
- Otherwise → label vision with a short body: problem statement, why it's vision-sized, which objectives it blocks. Do NOT attempt to specify the solution.

What this replaces

Remove the bounce/stuck detection logic for issues the planner itself filed (BOUNCED/LABEL_CHURN dispatch to groom-backlog). Keep bounce detection for issues filed by humans or other agents.
Remove the groom-backlog breakdown dispatch from the planner. The architect role (separate issue) handles vision decomposition.
The planner's action budget stays the same.

Template selection heuristic

Bug template: planner identifies something that is broken (error in logs, incorrect behavior, failing test)
Feature template: new capability needed (prerequisite that doesn't exist yet)
Refactor template: existing code needs restructuring without behavior change

Changes to `formulas/run-planner.toml`

Update the triage-and-plan step, Part C (file-at-constraints):

Add template-reading step at the start of Part C
Replace the current issue body template with template-aware filing
Add the complexity test before filing
When labeling vision, include a brief "## Why vision" section explaining what makes it too complex for direct filing

What stays the same

Prerequisite tree management (Part B)
Prediction triage (Part A)
Priority label sync
Vault procurement for human-blocked items
Journal and commit (step 3)
Constraint focus (top 3-5, Theory of Constraints)

Affected files

formulas/run-planner.toml (main change — Part C rewrite)
planner/AGENTS.md (update role description)

Acceptance criteria

Planner reads issue templates from .codeberg/ISSUE_TEMPLATE/
Issues filed by planner match one of the three templates (bug/feature/refactor)
Issues that don't fit templates get labeled vision instead of backlog
Complexity heuristic: >3 files or design forks = vision
No more planner-initiated groom-backlog breakdown dispatches
CI green

## Problem The planner currently files issues with a freeform body and relies on downstream bounce detection (BOUNCED, LABEL_CHURN) to catch issues that are too complex for the dev-agent. This creates churn: issues ping-pong between `backlog` and `underspecified`, wasting dev-agent sessions and gardener grooming cycles. ## Proposed change Replace the planner's freeform issue filing with a **template-or-vision gate**: ### Filing gate (new logic in `triage-and-plan` step, Part C) When the planner identifies a constraint to file as an issue: 1. **Read the issue templates** from `.codeberg/ISSUE_TEMPLATE/*.yaml` (bug, feature, refactor) 2. **Attempt to fill the template fields**: - `affected_files`: can the planner list 3 or fewer specific files? - `acceptance_criteria`: can it write concrete, checkable criteria (max 5)? - `proposed_solution` / `approach`: is there one clear approach, or are there design forks? 3. **Complexity test**: - If the work touches **one subsystem** (3 or fewer files) AND there are **no design forks** (only one reasonable approach) AND the template fields can be filled confidently → **file as `backlog`** using the matching template format - Otherwise → **label `vision`** with a short body: problem statement, why it's vision-sized, which objectives it blocks. Do NOT attempt to specify the solution. ### What this replaces - Remove the bounce/stuck detection logic for issues the planner itself filed (BOUNCED/LABEL_CHURN dispatch to groom-backlog). Keep bounce detection for issues filed by humans or other agents. - Remove the groom-backlog breakdown dispatch from the planner. The architect role (separate issue) handles vision decomposition. - The planner's action budget stays the same. ### Template selection heuristic - **Bug template**: planner identifies something that is broken (error in logs, incorrect behavior, failing test) - **Feature template**: new capability needed (prerequisite that doesn't exist yet) - **Refactor template**: existing code needs restructuring without behavior change ### Changes to `formulas/run-planner.toml` Update the `triage-and-plan` step, Part C (file-at-constraints): - Add template-reading step at the start of Part C - Replace the current issue body template with template-aware filing - Add the complexity test before filing - When labeling `vision`, include a brief "## Why vision" section explaining what makes it too complex for direct filing ### What stays the same - Prerequisite tree management (Part B) - Prediction triage (Part A) - Priority label sync - Vault procurement for human-blocked items - Journal and commit (step 3) - Constraint focus (top 3-5, Theory of Constraints) ## Affected files - `formulas/run-planner.toml` (main change — Part C rewrite) - `planner/AGENTS.md` (update role description) ## Acceptance criteria - [ ] Planner reads issue templates from `.codeberg/ISSUE_TEMPLATE/` - [ ] Issues filed by planner match one of the three templates (bug/feature/refactor) - [ ] Issues that don't fit templates get labeled `vision` instead of `backlog` - [ ] Complexity heuristic: >3 files or design forks = vision - [ ] No more planner-initiated groom-backlog breakdown dispatches - [ ] CI green