chamba 0.7.0 → 0.8.0

package/templates/skills/dx-spec/references/stages.md

@@ -16,6 +16,28 @@ The tab is where the user reads and where the user answers.
 Name the artifact in a gate's `file`, and the tab opens it and puts the gate under it.
 Say nothing about how to read a file: the user is already looking at it.
 
+## The text of a round
+
+The text you compose for a round must agree with the options that round offers.
+An option that declines a step makes that step the user's choice.
+No text beside it may say that the step happens anyway.
+Compose the question from the options, and read the two together before you declare the round.
+
+## Asking again
+
+The "Needs you" list says what is genuinely open.
+Only your own care keeps that true.
+
+An ask the user answered leaves the list as they answer it.
+A gate they asked for changes on is thus gone before you revise anything: declare the next one and carry on.
+
+An ask you supersede is different, because nobody answered it.
+You replace it with a different question, or the answer reaches you in the terminal instead.
+The ask then stays on the list, and tells the user to answer something you know already.
+Take it off in the same act that supersedes it, with `specs withdraw` and the reason.
+`SKILL.md` carries the verb and its payload.
+A gate declared again on the same artifact is the one case the tool takes back on its own.
+
 ## Applying the user's annotations
 
 The user annotates any part of any artifact on the tab.
@@ -86,6 +108,7 @@ The file names the piece of work in `entry`, and holds one round per submit:
 How to read one comment:
 
 - `file` is relative to the spec directory.
+- An asset's `path` is relative to the `.specs/` directory the feedback file sits in, not to the spec directory.
 - `unit` is that path with the heading on the end, both slugified. It is the address of the exact place the annotation sits on.
 - `kind` is `comment` or `remove`. A `remove` asks you to take that thing out, and its `text` is often empty, because pointing is the whole request.
 - `quote` is the text the annotation was anchored on, when the user selected text. It is empty when they pointed at an image, a section or the file itself, which is what tells you the difference.
@@ -149,8 +172,18 @@ Check these categories for candidates, most important first:
 - terminology
 - how success is measured
 
-For user-facing work, always pin down theme support - dark, light, both, or one fixed theme - and the target devices - desktop only, responsive, or mobile-first.
-The user answers this once. Do not guess it.
+**Theme support and the target devices.**
+For every piece of user-facing work, pin down which themes the application draws in - dark, light, or both - and which devices it is laid out for - desktop only, responsive, or mobile-first.
+Ask both once, in a round, whichever stages the protocol holds.
+No form asks them, so this stage is where they are settled.
+
+Look at the code that answers it before you ask, and mark the answer the code already gives as recommended.
+Almost always that is the answer: the work is in an application that has a theme and a layout already, and matching them is what the work needs.
+So the round is usually the user confirming what is there, and it stays a round because a piece of work that changes either one is exactly the piece of work an agent must not guess about.
+Say in the option which one the code gives, in the code's own terms - "both, which is what every screen in this app draws today".
+
+Write both answers into the `Themes and devices` section of `SPEC.md`, which the UI-mocks stage reads by name, so the stage that draws reads them from the spec rather than from a form.
+`references/spec-guide.md` holds that section's shape.
 
 Whatever stays open becomes a labeled assumption in `SPEC.md`, or a `[NEEDS CLARIFICATION: ...]` marker when it clears the bar in `references/spec-guide.md`.
 The implementer has to know what was confirmed and what was assumed.
@@ -160,11 +193,23 @@ The stage ends at a gate: enough asked, or another round.
 ## Research
 
 Run this stage for work that needs knowledge beyond the codebase: a protocol, a library, an algorithm, a subject area.
-Size the research to the work.
-Ask the user for the type and the depth in a round - a quick focused check against a thorough survey, and which sources you have.
-Mark your pick recommended.
 
-Then research as agreed, and write `research/RESEARCH.md`: what you learned, the options you compared, a recommendation, and the sources with links.
+**Open with no round.**
+The scope was settled beside this stage on the confirmation form, and it is in `stageSettings.research`.
+Where the settings hold nothing, the steps were confirmed before the form asked: open with one round for the scope, and carry on from the answer.
+The scope is one of three:
+
+- `focused` - you decide what to research, sized to the work.
+- `named` - research what `subject` names, and nothing wider.
+- `broad` - deep research across the subjects this work touches. Use a deep-research capability where your environment offers one.
+
+Check the scope against the code, the way **Cross-check a stored answer against the code** in `SKILL.md` says.
+Where `broad` is plainly more than the work needs, say so in a message and offer to narrow it - the user chose it, so the choice to keep it is theirs.
+
+Ask about sources in a round where the sources genuinely decide something: a paywalled standard, an internal document, a version you cannot reach.
+This is a judgment call, and most research needs no such round.
+
+Then research as settled, and write `research/RESEARCH.md`: what you learned, the options you compared, a recommendation, and the sources with links.
 Write a finding that decides something as **Decision / Rationale / Alternatives**: what was chosen, why, and what was rejected with the reason.
 Compare the options in a table when the comparison has more than two axes.
 Keep the volume sized to the work. The format is the discipline, not the length.
@@ -179,7 +224,16 @@ Map the parts of the code the work touches: entry points, data shapes, the conve
 Use the `Explore` agent for a broad search where you have one.
 Write the findings into `spec/SPEC.md` with `path:line` references.
 
+Read the project's own documents while you map the code: the README, the guides, and each document that sits beside the code the work touches.
+Find the ones the planned work makes not correct, and write them into the `Documentation impact` section of `spec/SPEC.md`, as `references/spec-guide.md` describes it.
+Name each document, and say which part of it the work makes not correct.
+Where the work leaves every document correct, write that, so the stages after this one know the question was asked.
+
+This stage is where the code is read as a whole, so it is where **Cross-check a stored answer against the code** in `SKILL.md` runs.
+Read every answer the user has given against what the code says, and raise what disagrees: the stage settings the protocol form carries, and what a round settled earlier, the interview's own answers included.
+
 This stage has no gate. It feeds the stages after it.
+So it does not end your turn: write its findings, and start the next stage in the same turn.
 A contradiction it finds becomes an interview question, a labeled assumption, or a `[NEEDS CLARIFICATION: ...]` marker.
 
 ## Technical specs
@@ -212,8 +266,13 @@ That round is the one exception to "ask nothing first".
 Each mock is a complete standalone HTML document at `mocks/<mock-id>.html`, where `<mock-id>` is a kebab-case name for the screen.
 Use inline styles, no external resources, and images as data URLs.
 A standalone page lets the agent who builds the work open the mock on its own.
-Style both `[data-theme="dark"]` and `[data-theme="light"]` on the root element when both themes are in scope, and one theme when the user chose one.
-Lay the screen out so it reads well at the target device widths.
+
+**The theme and the devices come from the `Themes and devices` section of `SPEC.md`.**
+The interview settled both and wrote them there.
+Read them from the spec, and ask in one round only where the spec does not say - work that reached this stage with no interview.
+Style both `[data-theme="dark"]` and `[data-theme="light"]` on the root element for both themes, and one of them for one.
+Lay the screen out for the devices: one desktop width for desktop only, every width from a phone up for responsive, and the phone first for mobile-first.
+Where the code says something else than the spec does, raise it the way **Cross-check a stored answer against the code** in `SKILL.md` says before you draw.
 
 List each mock in the `Mocks` section of `SPEC.md` as soon as the first one exists.
 
@@ -226,26 +285,13 @@ The loop:
 
 ## Execution plan
 
-Ask about the commits first, unless the principles file already answers it.
-Two more questions shape the run - the pauses and the review checkpoints - and they come later in this stage, because their options name concrete phases.
+**Ask nothing about how the run is shaped.**
+The commits, the branch, where the run stops and who reviews it are settled on the execute form, in one act, when the user starts the run.
+This stage recommends them as data, and writes none of them into `PLAN.md`.
 
-The settings read at bootstrap may answer the commit questions in advance:
-
-- `commit_mode: current-branch`, `new-branch` or `no-commits` answers the commits question. `prompt` keeps it.
-- `commit_grouping: per phase` or `single` answers the grouping question. `prompt` keeps it. With `no-commits` there is no grouping, so it is skipped either way.
-- With `new-branch`, `branch_naming` names the branch, with `<slug>` replaced by this spec's slug. The name question is then skipped.
-
-A saved answer skips its question, and says nothing.
-The plan gate still shows the whole setup, so the user can make an exception for this one spec there.
-
-Ask the commit questions in one round: whether the run commits as it goes, on the current branch or on a new one, and how the commits are grouped.
-Ask for the branch name in the same round when a new branch is a live option.
-
-Record the answers as `Commits: none | single | per phase` and `Branch: current | <name>` lines in `PLAN.md`.
-
-Then break the work into phases.
+Break the work into phases.
 **Each phase fits one session, and leaves the repo in a working state.**
-Write `plan/PLAN.md`: the goal, how the run behaves, and the phase list with checkboxes.
+Write `plan/PLAN.md`: the goal, the principles check, and the phase list with checkboxes.
 Give each phase its goal and its definition of done.
 Decide the phase boundaries, the goals and the definitions of done now, for every phase. They are cheap to get right in advance.
 
@@ -266,32 +312,71 @@ Every ID appears in one phase's `Covers` line at least, and a requirement may sp
 An ID no phase covers means a missing phase, or scope that belongs in the non-goals.
 Add the phase, or move the requirement, before the gate. Ask the user when the call is not yours.
 
-**Have `plan/PLAN.md` on disk, with its goal and its whole phase list, before the next round.**
-Both questions in it name concrete phases, and this file is what the user reads to answer them.
+**A phase covers each document the spec's `Documentation impact` section names.**
+Name the document in the definition of done of the phase that changes what it describes, so the run makes the document correct as it changes the code.
+Do not collect the documents into a phase of their own at the end.
+
+**Post the phases as soon as `PLAN.md` is on disk:**
+
+```
+echo '{"kind":"plan","phases":[{"phase":"phase-01-the-state","title":"The state"},{"phase":"phase-02-the-routes","title":"The routes"}]}' | specs post <spec>
+```
+
+One call, holding the whole list, in plan order.
+A phase's id is the name of the file it will be written into, without the extension, which is what the executing agent writes and ticks.
+The execute form names phases from this list: without it the user cannot place a pause or a checkpoint at all.
+
+Post the whole list again after each revision of the plan.
+The list the post carries becomes the list: a phase that is gone from the plan goes from the state with it, and a phase that survives keeps the status it had.
+This is the only write that drops a phase, so a plan the user changed at the gate leaves nothing behind for the execute form to offer.
+
+**Then recommend how the run is shaped**, with `specs recommend`.
+`SKILL.md` carries the payload.
+The user decides it on the execute form; this is your reading of the work, and it binds nobody.
+
+**The commits.**
+Recommend `per-phase` for a plan of several phases, because a phase that is committed is a phase a later session finds finished.
+Recommend `single` for small work that reads as one change.
+Recommend `none` where the user is likely to want to read the whole thing before any of it lands.
+Recommend a new branch for work of any size that touches shared code, and the current branch for a small change on a branch that is already the work's own.
+Name the branch `spec/<slug>`, with this spec's own slug, unless a principle in the principles file names another shape.
 
 **The pauses.**
-Ask where the run stops for the user: nowhere, after one named phase, or after every phase.
-A stop lets the user see a result before later phases build on it.
-Recommend no stops for a small, low-risk plan.
-Recommend a named phase when one phase is risky, user-visible, or a natural point for feedback.
-Recommend every phase when the user wants to steer the work all the way through.
-Record the answer as a `Pauses:` line: `none`, `after phase 2, after phase 4`, or `every phase`.
+A pause is where the run stops and waits for the user.
+The modes are `none`, `chosen` with the phases named, and `every`.
+
+Recommend a pause only where skipping it has a real downside: a later phase builds on something the user must see or decide first.
+Recommend `none` for every other plan, which is most of them.
+A phase that is only visible, or only complicated, earns no pause.
+A pause with no such downside costs the user a stop for nothing.
+
+A pause is not a mid-run review checkpoint.
+A checkpoint stops nobody: fresh reviewers judge the work, and the run goes on.
+A pause needs the user, and the run waits until the user answers.
+A phase that needs another reader gets a checkpoint.
+A phase that needs the user's own judgment gets a pause.
+
+Never recommend `every` yourself.
+That mode is the user's to pick on the form, and a recommendation of it carries no reason.
+
+**The pause reasons.**
+Give every pause you recommend one line in `pauseReasons`, keyed by the phase it sits after.
+Say what the later phases build on, and what goes wrong where the user does not see it first.
+Where you recommend `none`, give `noPauseReason` one line saying why nothing needs the user before the run ends.
+Write both to the user, in plain words.
+The execute form shows them under the Pauses field, and they are how the user judges the stops you proposed.
 
 **The review checkpoints.**
 A review checkpoint is a point in the run where fresh reviewers, who did not do the work, judge what is built so far.
-Propose concrete checkpoints. For each one, say how many reviewers and give each a short focus.
+Propose concrete checkpoints, each with a panel of one focus per reviewer.
 Correctness against the spec, security, performance, repo rules and docs consistency are examples, not a menu.
 
 Where they go:
 
-- **Every proposal includes the final checkpoint, after the last phase.** It judges the finished work as a whole.
+- **Every recommendation carries the final checkpoint**, after the last phase. It judges the finished work as a whole, and the user may still untick it.
 - Recommend a mid-run checkpoint only under the **dependency-risk rule**: the one risk that justifies stopping for reviewers mid-run is a phase whose wrong implementation sends later phases wrong. Review a complicated phase with no effect on later phases at the end instead. A five-phase plan with no such risk gets the final checkpoint alone.
-- Say why each checkpoint sits where it does, and name the phases.
-
-Ask the pauses and the checkpoints in one round.
-The user's pick is final, so a user who declines every checkpoint gets none.
-Record the answer as a `Review checkpoints:` bullet with one sub-bullet per checkpoint: where it sits, how many reviewers, their focuses, and why it is there.
-With no review at all, the line is `Review checkpoints: none`.
+- Give each checkpoint a `why` of one line, saying why it sits where it does. The form shows it on a line under the checkpoint.
+- **Include a "better ways to do this" reviewer in the final panel.**
 
 **Write no phase file now.**
 Each `plan/phase-NN-<slug>.md` holds a `Status:` line, tasks as checkboxes, and a **Verify** section stating how to prove the phase done.
@@ -309,13 +394,7 @@ Include the deviation table only when the plan breaks a principle, and the `Cove
 
 > **For the executing agent - read this first.** Read `spec/SPEC.md` before any phase.
 > This plan was written before the work started; check each phase against the actual code before building, and raise anything that looks off instead of pushing through.
-
-- Commits: none | single | per phase
-- Branch: current | <branch name>
-- Pauses: none | after phase 2, after phase 4 | every phase
-- Review checkpoints:
-  - after phase 3: 2 reviewers - correctness against the spec, and docs consistency. Later phases build on this one.
-  - final: 3 reviewers - correctness against the spec, docs consistency, and simpler shapes.
+> How this run is shaped - the commits, the branch, the pauses and the review checkpoints - is in the state, decided on the execute form.
 
 ## Goal
 
@@ -340,24 +419,26 @@ Include the deviation table only when the plan breaks a principle, and the `Cove
 ```
 
 Consider a visual beside the plan.
-Then gate on `plan/PLAN.md`, saying the phases in a line each, how the run behaves, how the plan honors the principles, and any deviation with its reason.
-On changes: revise, and gate again. Loop until the user approves it.
+Then gate on `plan/PLAN.md`, saying the phases in a line each, how the plan honors the principles, and any deviation with its reason.
+Say in one line what you recommended for the run, and that the user settles it when they press Execute.
+On changes: revise the plan, post the phases again where they moved, recommend the run again where the change made the recommendation wrong, and gate again.
+Loop until the user approves it.
+The rule over that last part is **Keep what derives from a change true**, in `SKILL.md`.
 
 ## Quality review
 
 This is the last stage before the coherence rewrite and finalize.
 It reviews everything the spec produced - `spec/SPEC.md`, the research, the plan, and the mocks the spec lists - and whether those documents agree with each other.
 Read `references/review-guide.md` when the stage starts.
-It holds the reviewer briefs, the lenses, the severities, the report format, and the design-blockers loop.
+It holds the reviewer briefs, the lenses, the severities, and the report format.
 
 **The panel.**
 Ask who reviews the work, in a round.
 Propose a panel sized to the work and its risk, one reviewer per focus, and mark your proposal recommended.
 Give a short line saying what each reviewer looks at.
-The default proposal has four reviewers: consistency and completeness, principles alignment, better ways to do this, and design blockers.
-**Include the "better ways to do this" reviewer and the design-blockers reviewer in every proposal.**
-The design-blockers reviewer runs the loop `references/review-guide.md` defines.
-Bigger or riskier work may add a focus of its own - security, performance, the work's own subject - and small work may run with two reviewers and the blockers loop.
+The default proposal has three reviewers: consistency and completeness, principles alignment, and better ways to do this.
+**Include the "better ways to do this" reviewer in every proposal.**
+Bigger or riskier work may add a focus of its own - security, performance, the work's own subject - and small work may run with two reviewers.
 Always offer an option that turns the review off.
 Say in its description that nothing gets checked independently, and that the spec goes straight to the rewrite and finalize.
 
@@ -391,9 +472,13 @@ Resolve a conflict with a principle by changing the work, never the principle.
 Write `review/REVIEW.md` in the format `references/review-guide.md` defines.
 Consider a visual beside it: where the findings fall across the artifacts is the kind of thing a figure shows faster than a list.
 
-Declare one decision card per finding that waits on the user, each carrying the evidence and the trade-off.
+Declare one decision card per finding that waits on the user.
+Each card names the passage precisely: the artifact in `file`, and the `##` section in `heading`.
+Write what was found and what each way costs into the question's own `ask`.
+Say the proposed change as one option, in the exact words it would be done in, and the alternative as another option.
+Mark one of them recommended.
+The card's own box is where the user's words go, and it is already there, so write no `invite` on a card: the form draws one box for the card and gives it its own words.
 Then gate on `review/REVIEW.md`.
 Read the answers back, record what the user decided in the report, and apply it.
 Then gate again.
 A comment the user sent on a finding's section is input to that finding.
-A user who asks for another round gets one. There is no automatic re-review loop.