Refine taskitem workflow guidance and sprint intake shaping
This commit is contained in:
Bill
@@ -0,0 +1,192 @@
|
||||
# Agent Playbook: Whetstone-First Sprint Execution
|
||||
|
||||
This document is for agents working across Whetstone and target projects such as
|
||||
`whimpwm`.
|
||||
|
||||
It captures the working method that produced better results on 2026-03-20 when
|
||||
executing structured sprint work through the Whetstone MCP/taskitem pipeline.
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Two failure modes show up repeatedly:
|
||||
|
||||
1. Agents bypass Whetstone too early and manually code around a weak planning
|
||||
pipeline.
|
||||
2. Agents trust generated taskitems too easily even when they are broad,
|
||||
duplicated, off-project, or not executable by smaller workers.
|
||||
|
||||
The intended method is a middle path:
|
||||
|
||||
- use Whetstone first
|
||||
- inspect the output critically
|
||||
- correct taskitems manually when needed
|
||||
- record the generator miss
|
||||
- only then hand execution to constrained workers or continue with senior review
|
||||
|
||||
## Core Principle
|
||||
|
||||
Whetstone should remain the planning and task-shaping source of truth as early as
|
||||
possible.
|
||||
|
||||
That does not mean raw markdown specs are ignored.
|
||||
|
||||
The phase model is:
|
||||
|
||||
1. Spec markdown is the source of truth before code exists.
|
||||
2. Parsed planning artifacts are the source of truth after intake.
|
||||
3. AST is the source of truth once code structure exists.
|
||||
|
||||
Agents should push work toward that progression, not collapse back to ad hoc
|
||||
manual execution.
|
||||
|
||||
## Default Workflow
|
||||
|
||||
For a sprint execution request:
|
||||
|
||||
1. Find the active sprint spec or execution spec.
|
||||
2. Run the Whetstone sprint taskitem pipeline.
|
||||
3. Inspect generated taskitems before writing code.
|
||||
4. Decide whether taskitems are:
|
||||
- ready to execute
|
||||
- salvageable with manual correction
|
||||
- unusable and requiring a recorded gap
|
||||
5. If taskitems are good, use them as the execution substrate.
|
||||
6. If taskitems need correction, edit the taskitems manually and preserve the
|
||||
corrected artifact in the run directory.
|
||||
7. If taskitems are unusable, record the generator/validator failure in the gap
|
||||
registry and do not pretend the pipeline succeeded.
|
||||
8. Preserve run artifacts for LoRA and smaller-model training data.
|
||||
9. After code generation or worker execution, perform a stronger model review and
|
||||
tighten the result.
|
||||
|
||||
## The Important Distinction
|
||||
|
||||
Manual correction of taskitems is allowed when the generator is close but not yet
|
||||
reliable enough.
|
||||
|
||||
Manual bypass of the taskitem layer is not the default.
|
||||
|
||||
That means:
|
||||
|
||||
- acceptable:
|
||||
- rewrite titles
|
||||
- narrow target files
|
||||
- fix acceptance commands
|
||||
- split one broad task into several bounded tasks
|
||||
- add missing execution-contract fields
|
||||
- not acceptable:
|
||||
- ignore obviously bad taskitems and jump straight to handwritten code as if
|
||||
the planning layer were fine
|
||||
- treat a failed taskitem run as a success without recording what was wrong
|
||||
|
||||
## Taskitem Quality Bar
|
||||
|
||||
Generated taskitems are not execution-ready just because validation returned
|
||||
`score=100`.
|
||||
|
||||
Before handing them to smaller agents, check:
|
||||
|
||||
- Does each task have a bounded objective?
|
||||
- Do `targetFiles` point to the actual project and the likely ownership slice?
|
||||
- Are acceptance commands valid for the project language?
|
||||
- Are test files real?
|
||||
- Is the title specific enough that a constrained worker could act on it?
|
||||
- Is the task a concrete implementation slice rather than a broad planning
|
||||
bucket?
|
||||
|
||||
Red flags include:
|
||||
|
||||
- blanket file sets repeated across every task
|
||||
- wrong-project paths
|
||||
- fabricated tests
|
||||
- mixed-language commands such as `go test ./...` in a Rust repo
|
||||
- titles like `Architect Review`, `Define verification surface`, or generic
|
||||
`Plan ...` tasks with wide ownership
|
||||
|
||||
## When To Use Smaller Workers
|
||||
|
||||
Use smaller agents or AST-first codegen only after the taskitem is narrow enough
|
||||
that a constrained worker can succeed without inventing scope.
|
||||
|
||||
Good worker task shape:
|
||||
|
||||
- one main objective
|
||||
- a small, real file set
|
||||
- valid verification commands
|
||||
- explicit acceptance evidence
|
||||
|
||||
If the taskitem still requires a senior model to infer the real work, reshape it
|
||||
first.
|
||||
|
||||
## Review Role Of The Stronger Model
|
||||
|
||||
The stronger model should own:
|
||||
|
||||
- sprint interpretation
|
||||
- taskitem quality review
|
||||
- manual taskitem correction
|
||||
- gap diagnosis and registry updates
|
||||
- final code review and hardening
|
||||
|
||||
The stronger model should not waste tokens doing narrow mechanical generation if
|
||||
the taskitem is already well-shaped for a smaller worker.
|
||||
|
||||
## Gap Recording Rule
|
||||
|
||||
If the generator or validator fails in a meaningful way, record it.
|
||||
|
||||
Typical examples:
|
||||
|
||||
- generated taskitems are project-grounded but still not executable
|
||||
- validator over-scores clearly weak tasks
|
||||
- subsection/work-item structure is ignored
|
||||
- self-targeting Whetstone sprints collapse into blanket internal tasks
|
||||
|
||||
Record the miss in the relevant Whetstone gap or registry path instead of
|
||||
silently compensating for it.
|
||||
|
||||
## Data Capture Rule
|
||||
|
||||
Every meaningful run should leave artifacts useful for later LoRA or SLM work.
|
||||
|
||||
Preserve:
|
||||
|
||||
- raw pipeline run directory
|
||||
- corrected taskitem artifact when manual fixes were required
|
||||
- gap note or registry update when generation was wrong
|
||||
|
||||
The long-term goal is to make smaller models reliable on constrained workitems,
|
||||
so the correction path itself is training data.
|
||||
|
||||
## Recommended Prompting Stance For Other Agents
|
||||
|
||||
When another agent is asked to execute a sprint:
|
||||
|
||||
- tell it Whetstone is the first stop, not optional scaffolding
|
||||
- tell it to inspect generated taskitems critically
|
||||
- tell it manual taskitem correction is permitted
|
||||
- tell it manual code bypass is not the default when the planning layer failed
|
||||
- tell it to record generator misses in the gap registry
|
||||
- tell it to preserve corrected artifacts for training data
|
||||
|
||||
One short instruction that often helps:
|
||||
|
||||
`Use Whetstone first. If taskitems are weak, fix the taskitems and record the generator miss. Do not skip directly to handwritten code unless the user explicitly tells you to bypass the planning layer.`
|
||||
|
||||
## Suggested Use
|
||||
|
||||
Point other agents at this file before asking them to:
|
||||
|
||||
- execute a sprint
|
||||
- generate taskitems for another repo
|
||||
- prepare bounded work for smaller workers
|
||||
- review whether a Whetstone run is actually handoff-ready
|
||||
|
||||
## Current Practical Naming
|
||||
|
||||
If "bootstrapping" feels ambiguous, use:
|
||||
|
||||
`Whetstone-first sprint execution playbook`
|
||||
|
||||
That name is explicit about what the document is for and how agents should use
|
||||
it.
|
||||
@@ -8,6 +8,14 @@ and how run data must be captured for later LoRA curation.
|
||||
- Applies to sprint plan execution (for example: `sprint46_plan.md` through `sprint100_plan.md`)
|
||||
- Applies to all future agents working in this repository
|
||||
|
||||
## Related Guidance
|
||||
|
||||
For the practical agent workflow on when to trust generated taskitems, when to
|
||||
manually correct them, and when to record generator misses instead of bypassing
|
||||
the planning layer, also see:
|
||||
|
||||
`docs/AGENT_PLAYBOOK_WHESTONE_FIRST_SPRINT_EXECUTION_2026-03-20.md`
|
||||
|
||||
## Required MCP Pipeline
|
||||
|
||||
For each sprint plan, agents must run:
|
||||
|
||||
61
docs/sprint278_plan.md
Normal file
61
docs/sprint278_plan.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Sprint 278: Structured Planning Artifact As Post-Intake Source Of Truth
|
||||
|
||||
## Goal
|
||||
Make Whetstone treat markdown specs as pre-code truth, but treat a structured
|
||||
planning artifact as the source of truth for task decomposition after intake.
|
||||
|
||||
This sprint exists to close the remaining architectural gap behind GR-035:
|
||||
`architect_intake` and `RequirementsParser` do produce useful structure, but
|
||||
`generate_taskitems` still depends too heavily on raw markdown-shaped heuristics.
|
||||
The result is that explicit work items like `W1`/`W2`/`W3` are partially
|
||||
recognized but still get merged back into broad plan tasks.
|
||||
|
||||
The target architecture is:
|
||||
|
||||
1. Markdown spec is the source of truth before code exists.
|
||||
2. Intake produces a structured planning artifact that becomes the planning
|
||||
source of truth.
|
||||
3. Task decomposition and queue shaping consume that artifact rather than
|
||||
re-inferring everything from raw prose.
|
||||
4. Once code exists, AST remains the source of truth for code structure/editing.
|
||||
|
||||
## Steps
|
||||
|
||||
| Step | File | What |
|
||||
|------|------|------|
|
||||
| 1990 | `RequirementsParser.h` | Preserve subsection/work-item context in parsed requirements so `### W1...` blocks survive intake as structured planning inputs. |
|
||||
| 1991 | `ArchitectIntakeProcessor.h` | Emit explicit planning-artifact structure for bounded work items and subsection-scoped requirement groups instead of only a flat normalized requirement list. |
|
||||
| 1992 | `ScopeMilestoneDecomposer.h` | Prefer structured work-item groups as decomposition roots; broad project/context goals must not dominate explicit `W1`/`W2`/`W3` slices. |
|
||||
| 1993 | `TaskitemGeneratorV2.h` / `RegisterArchitectIntakeTools.h` | Generate taskitems from the structured planning artifact with file/language/verification hints attached to each work item, not reconstructed from global prose. |
|
||||
| 1994 | Sprint 278 integration | Run the `whimpwm` Sprint 002 recomposition spec through the pipeline and verify that generated taskitems align to bounded work items, scoped file ownership, and Rust-only verification. |
|
||||
|
||||
## Dependencies
|
||||
- Builds on: `RequirementsParser.h`, `ArchitectIntakeProcessor.h`,
|
||||
`ScopeMilestoneDecomposer.h`, `TaskitemGeneratorV2.h`,
|
||||
`RegisterArchitectIntakeTools.h`
|
||||
- Regression target: GR-035 in
|
||||
`docs/generator_readiness_gap_registry_2026-02-26.md`
|
||||
- Validation artifact: `whimpwm` sprint spec at
|
||||
`/home/bill/Documents/whimpwm/docs/sprints/sprint_002_policy_driven_recomposition_execution_spec.md`
|
||||
|
||||
## Constraints
|
||||
- Do not treat raw markdown text as the long-lived planning source of truth
|
||||
after intake has already structured it.
|
||||
- Do not weaken AST-first execution principles; this sprint is about the
|
||||
pre-code planning layer, not replacing AST as code truth.
|
||||
- Do not regress the existing Rust-only contract improvements for GR-035:
|
||||
no `go test ./...`, no malformed file paths, no Whetstone-workspace fallback
|
||||
leakage into external project taskitems.
|
||||
- Keep any new planning artifact deterministic and serializable so it can be
|
||||
used for LoRA/SLM training data capture later.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Intake preserves bounded work-item structure from markdown specs in a
|
||||
structured planning artifact.
|
||||
- Decomposition consumes that structure directly and splits `W1`/`W2`/`W3`
|
||||
style work items into distinct task roots.
|
||||
- `generate_taskitems` for the `whimpwm` Sprint 002 spec produces bounded,
|
||||
work-item-shaped tasks rather than broad plan bundles.
|
||||
- Generated taskitems retain Rust-only verification and real `whimpwm`
|
||||
file/test grounding.
|
||||
- Regression tests pass for parser, decomposition, and taskitem generation.
|
||||
Reference in New Issue
Block a user