enhancement(planner): replace time-based reasoning with context-cost sizing and add multi-source coverage audit (#2091) (#2092) (#2114)
Replace minutes-based task sizing with context-window percentage sizing. Add planner_authority_limits section prohibiting difficulty-based scope decisions. Expand decision coverage matrix to multi-source audit covering GOAL, REQ, RESEARCH, and CONTEXT artifacts. Add Source Audit gap handling to plan-phase orchestrator (step 9c). Update plan-checker to detect time/complexity language in scope reduction scans. Add 374 CI regression tests preventing prohibited language from leaking back into artifacts. Closes #2091 Closes #2092 Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
73
get-shit-done/references/planner-source-audit.md
Normal file
73
get-shit-done/references/planner-source-audit.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# Planner Source Audit & Authority Limits
|
||||
|
||||
Reference for `agents/gsd-planner.md` — extended rules for multi-source coverage audits and planner authority constraints.
|
||||
|
||||
## Multi-Source Coverage Audit Format
|
||||
|
||||
Before finalizing plans, produce a **source audit** covering ALL four artifact types:
|
||||
|
||||
```
|
||||
SOURCE | ID | Feature/Requirement | Plan | Status | Notes
|
||||
--------- | ------- | ---------------------------- | ----- | --------- | ------
|
||||
GOAL | — | {phase goal from ROADMAP.md} | 01-03 | COVERED |
|
||||
REQ | REQ-14 | OAuth login with Google + GH | 02 | COVERED |
|
||||
REQ | REQ-22 | Email verification flow | 03 | COVERED |
|
||||
RESEARCH | — | Rate limiting on auth routes | 01 | COVERED |
|
||||
RESEARCH | — | Refresh token rotation | NONE | ⚠ MISSING | No plan covers this
|
||||
CONTEXT | D-01 | Use jose library for JWT | 02 | COVERED |
|
||||
CONTEXT | D-04 | 15min access / 7day refresh | 02 | COVERED |
|
||||
```
|
||||
|
||||
### Four Source Types
|
||||
|
||||
1. **GOAL** — The `goal:` field from ROADMAP.md for this phase. The primary success condition.
|
||||
2. **REQ** — Every REQ-ID in `phase_req_ids`. Cross-reference REQUIREMENTS.md for descriptions.
|
||||
3. **RESEARCH** — Technical approaches, discovered constraints, and features identified in RESEARCH.md. Exclude items explicitly marked "out of scope" or "future work" by the researcher.
|
||||
4. **CONTEXT** — Every D-XX decision from CONTEXT.md `<decisions>` section.
|
||||
|
||||
### What is NOT a Gap
|
||||
|
||||
Do not flag these as MISSING:
|
||||
- Items in `## Deferred Ideas` in CONTEXT.md — developer chose to defer these
|
||||
- Items scoped to a different phase via `phase_req_ids` — not assigned to this phase
|
||||
- Items in RESEARCH.md explicitly marked "out of scope" or "future work" by the researcher
|
||||
|
||||
### Handling MISSING Items
|
||||
|
||||
If ANY row is `⚠ MISSING`, do NOT finalize the plan set silently. Return to the orchestrator:
|
||||
|
||||
```
|
||||
## ⚠ Source Audit: Unplanned Items Found
|
||||
|
||||
The following items from source artifacts have no corresponding plan:
|
||||
|
||||
1. **{SOURCE}: {item description}** (from {artifact file}, section "{section}")
|
||||
- {why this was identified as required}
|
||||
|
||||
Options:
|
||||
A) Add a plan to cover this item
|
||||
B) Split phase: move to a sub-phase
|
||||
C) Defer explicitly: add to backlog with developer confirmation
|
||||
|
||||
→ Awaiting developer decision before finalizing plan set.
|
||||
```
|
||||
|
||||
If ALL rows are COVERED → return `## PLANNING COMPLETE` as normal.
|
||||
|
||||
---
|
||||
|
||||
## Authority Limits — Constraint Examples
|
||||
|
||||
The planner's only legitimate reasons to split or flag a feature are **constraints**, not judgments about difficulty:
|
||||
|
||||
**Valid (constraints):**
|
||||
- ✓ "This task touches 9 files and would consume ~45% context — split into two tasks"
|
||||
- ✓ "No API key or endpoint is defined in any source artifact — need developer input"
|
||||
- ✓ "This feature depends on the auth system built in Phase 03, which is not yet complete"
|
||||
|
||||
**Invalid (difficulty judgments):**
|
||||
- ✗ "This is complex and would be difficult to implement correctly"
|
||||
- ✗ "Integrating with an external service could take a long time"
|
||||
- ✗ "This is a challenging feature that might be better left to a future phase"
|
||||
|
||||
If a feature has none of the three legitimate constraints (context cost, missing information, dependency conflict), it gets planned. Period.
|
||||
@@ -719,41 +719,70 @@ Task(
|
||||
## 9. Handle Planner Return
|
||||
|
||||
- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
|
||||
- **`## PHASE SPLIT RECOMMENDED`:** The planner determined the phase is too complex to implement all user decisions without simplifying them. Handle in step 9b.
|
||||
- **`## PHASE SPLIT RECOMMENDED`:** The planner determined the phase exceeds the context budget for full-fidelity implementation of all source items. Handle in step 9b.
|
||||
- **`## ⚠ Source Audit: Unplanned Items Found`:** The planner's multi-source coverage audit found items from REQUIREMENTS.md, RESEARCH.md, ROADMAP goal, or CONTEXT.md decisions that are not covered by any plan. Handle in step 9c.
|
||||
- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
|
||||
- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
|
||||
|
||||
## 9b. Handle Phase Split Recommendation
|
||||
|
||||
When the planner returns `## PHASE SPLIT RECOMMENDED`, it means the phase has too many decisions to implement at full fidelity within the plan budget. The planner proposes groupings.
|
||||
When the planner returns `## PHASE SPLIT RECOMMENDED`, it means the phase's source items exceed the context budget for full-fidelity implementation. The planner proposes groupings.
|
||||
|
||||
**Extract from planner return:**
|
||||
- Proposed sub-phases (e.g., "17a: processing core (D-01 to D-19)", "17b: billing + config UX (D-20 to D-27)")
|
||||
- Which D-XX decisions go in each sub-phase
|
||||
- Why the split is necessary (decision count, complexity estimate)
|
||||
- Which source items (REQ-IDs, D-XX decisions, RESEARCH items) go in each sub-phase
|
||||
- Why the split is necessary (context cost estimate, file count)
|
||||
|
||||
**Present to user:**
|
||||
```
|
||||
## Phase {X} is too complex for full-fidelity implementation
|
||||
## Phase {X} exceeds context budget for full-fidelity implementation
|
||||
|
||||
The planner found {N} decisions that cannot all be implemented without
|
||||
simplifying some. Instead of reducing your decisions, we recommend splitting:
|
||||
The planner found {N} source items that exceed the context budget when
|
||||
planned at full fidelity. Instead of reducing scope, we recommend splitting:
|
||||
|
||||
**Option 1: Split into sub-phases**
|
||||
- Phase {X}a: {name} — {D-XX to D-YY} ({N} decisions)
|
||||
- Phase {X}b: {name} — {D-XX to D-YY} ({M} decisions)
|
||||
- Phase {X}a: {name} — {items} ({N} source items, ~{P}% context)
|
||||
- Phase {X}b: {name} — {items} ({M} source items, ~{Q}% context)
|
||||
|
||||
**Option 2: Proceed anyway** (planner will attempt all, quality may degrade)
|
||||
**Option 2: Proceed anyway** (planner will attempt all, quality may degrade past 50% context)
|
||||
|
||||
**Option 3: Prioritize** — you choose which decisions to implement now,
|
||||
**Option 3: Prioritize** — you choose which items to implement now,
|
||||
rest become a follow-up phase
|
||||
```
|
||||
|
||||
Use AskUserQuestion with these 3 options.
|
||||
|
||||
**If "Split":** Use `/gsd-insert-phase` to create the sub-phases, then replan each.
|
||||
**If "Proceed":** Return to planner with instruction to attempt all decisions at full fidelity, accepting more plans/tasks.
|
||||
**If "Prioritize":** Use AskUserQuestion (multiSelect) to let user pick which D-XX are "now" vs "later". Create CONTEXT.md for each sub-phase with the selected decisions.
|
||||
**If "Proceed":** Return to planner with instruction to attempt all items at full fidelity, accepting more plans/tasks.
|
||||
**If "Prioritize":** Use AskUserQuestion (multiSelect) to let user pick which items are "now" vs "later". Create CONTEXT.md for each sub-phase with the selected items.
|
||||
|
||||
## 9c. Handle Source Audit Gaps
|
||||
|
||||
When the planner returns `## ⚠ Source Audit: Unplanned Items Found`, it means items from REQUIREMENTS.md, RESEARCH.md, ROADMAP goal, or CONTEXT.md decisions have no corresponding plan.
|
||||
|
||||
**Extract from planner return:**
|
||||
- Each unplanned item with its source artifact and section
|
||||
- The planner's suggested options (A: add plan, B: split phase, C: defer with confirmation)
|
||||
|
||||
**Present each gap to user.** For each unplanned item:
|
||||
|
||||
```
|
||||
## ⚠ Unplanned: {item description}
|
||||
|
||||
Source: {RESEARCH.md / REQUIREMENTS.md / ROADMAP goal / CONTEXT.md}
|
||||
Details: {why the planner flagged this}
|
||||
|
||||
Options:
|
||||
1. Add a plan to cover this item (recommended)
|
||||
2. Split phase — move to a sub-phase with related items
|
||||
3. Defer — add to backlog (developer confirms this is intentional)
|
||||
```
|
||||
|
||||
Use AskUserQuestion for each gap (or batch if multiple gaps).
|
||||
|
||||
**If "Add plan":** Return to planner (step 8) with instruction to add plans covering the missing items, preserving existing plans.
|
||||
**If "Split":** Use `/gsd-insert-phase` for overflow items, then replan.
|
||||
**If "Defer":** Record in CONTEXT.md `## Deferred Ideas` with developer's confirmation. Proceed to step 10.
|
||||
|
||||
## 10. Spawn gsd-plan-checker Agent
|
||||
|
||||
|
||||
Reference in New Issue
Block a user