requirement-convergence

# Requirement Convergence ## Purpose Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. ## Convergence Fields | Field | Pass condition | |-------|----------------| | `outcome` | One observable result. A requirement that does not serve it is excess. | | `requirements[]` | Every build-relevant item labeled `current-state` or `desired-future`. | | `nonGoals[]` | Authored by the user, or the user stated there are none. | | `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | `cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. Classify from the user's own retained wording, not from an analyzer's restatement of it: wording that asks for an evaluation, describes a speculative idea, or suggests a mechanism stays in active convergence context as a judgment-only candidate. `requirements[]` and durable documents receive a candidate only after explicit user confirmation. Each field carries a readiness label: `ready`, `weak`, or `weak-but-explicit` (weak, and the user agreed to leave it unresolved). Only the user sets `weak-but-explicit`. Requirements are converged when every applicable field is `ready` or `weak-but-explicit`. Judgment rules per field: [references/criteria.md](references/criteria.md). ## Hearing Protocol Run the hearing after scope analysis has produced the facts needed to judge the convergence fields. The workflow using this skill owns the interaction method and routing; this skill defines the hearing content and pass conditions. Register these steps before starting and record each step's evidence as it completes: | Step | Action | Completion evidence | |------|--------|---------------------| | 1 | Render the Scope Confirmation below, asking only about the fields below `ready` | Each fact cites the analysis output it came from, and **User decisions** holds one question per field below `ready` | | 2 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered | | 3 | Re-ask once when a recorded value still fails its pass condition, then mark the field `weak-but-explicit` when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop | | 4 | Hand the record to the step that judges the fields | An updated record returned from that step | Step 2's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put. ## Scope Confirmation Render this shape at every requirements confirmation stop, whether or not the hearing ran, using only what can change the user's requirement decision or the workflow route. | Section | Contents | |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | | **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. Only an explicit user answer moves an item from **User decisions** into **Confirmed scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. ## Storage Protocol | Carrier | Holds | Written by | |---------|-------|------------| | The convergence record in the judging step's output | Every field with its readiness label | The judging step | | PRD `Success Criteria` and `Future / Out of Scope` | `outcome`; user-authored `nonGoals` | The PRD production step | | Design Doc `Requirement Convergence` | The same when no PRD exists, and the fields left `weak-but-explicit` in every case | The Design Doc production step | A flow that produces neither document carries the record in its own context to the next step. ## Reference Protocol (For Downstream Consumers) 1. Read the convergence record from the prompt. 2. Treat `nonGoals` as excluded from the current change and `desired-future` requirements as buildable scope. Evaluation requests, speculative ideas, prescribed mechanisms, and agent-proposed capabilities that were not promoted create no downstream obligation; an accepted ADR may retain evaluated options as decision history. 3. Treat a `weak-but-explicit` field as a recorded open question rather than a settled decision. When work depends on it, return the missing decision and its effect to the owning workflow. ## Quality Checklist - [ ] Scope facts were presented before questions were asked - [ ] `nonGoals` came from the user, or the user stated there are none - [ ] Every applicable field is `ready`, or `weak-but-explicit` by the user's agreement ## References - [references/criteria.md](references/criteria.md) — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test