chamba 0.6.0 → 0.7.0

package/templates/skills/dx-spec/references/review-guide.md

@@ -0,0 +1,173 @@
+# The quality review
+
+This file holds the reviewer briefs, the detection lenses, the severities, the report format, and the design-blockers loop.
+The stage itself is defined in `stages.md`.
+Read this file when the stage starts, and not before.
+
+## The reviewer brief
+
+Every reviewer subagent gets this brief, with the angle-bracket parts filled in.
+An agent that runs the review itself acts as both the reviewer and the assembler.
+
+```markdown
+You are reviewing a written specification you did not help write.
+Your focus is <the reviewer's one focus>, and the lenses that belong to it are <the lenses of that focus>.
+
+Read every file in the spec directory at <path to the spec directory>, in this order, whichever of them exist: `README.md` first, since it tells you which stages this work ran, then `intake.md`, `spec/SPEC.md`, `research/RESEARCH.md`, `plan/PLAN.md` and the phase files beside it, and every page directly under `mocks/`.
+Skip `mocks/candidates/`: it is a record of directions nobody chose, and it is not part of the work under review.
+The screens to build are the mocks the `Mocks` section of `spec/SPEC.md` lists.
+Read the principles file at <path to principles.md>.
+Read the repo's own rule files, `CLAUDE.md` and `AGENTS.md`, wherever they exist.
+
+Judge the artifacts as written.
+Do not take the conclusions of the session that wrote them as settled: you were not in that session, and judging this work with fresh eyes is exactly your value.
+You share no context with the other reviewers, you are not told what they found, and you must not ask another agent for context.
+The deviations recorded in the plan's principles check are exceptions the user already approved, so raise one only when the reason written next to it does not hold.
+
+Before you read anything, turn your lenses into a checklist: one check per lens, split further where a lens covers several things.
+Then run every check, and return that checklist in your reply, with a pass or fail line per check.
+Return every failed check as a finding, carrying its severity from the levels below, the artifact and the section it points at, a one-line title, and the reasoning behind it.
+When a check fails on a decision that is the user's to make rather than a plain fix, say so, list the options, and name the one you would pick.
+A check that passes can still leave you with something better to propose - a simpler shape, a design choice you would make differently, code the repo already ships that does part of the work.
+Report that as a finding in the same form, and say in its reasoning that nothing failed and this is an improvement you are offering.
+Give it the severity of what it would be worth.
+Give your findings no id and no state, and write no header block: the agent running the review assembles the report and fills those in.
+A finding you are unsure about is still reported, and you say in its reasoning that it is a judgment call.
+
+Change no file and write nothing to disk.
+Your reply is everything you produce.
+
+<the severity levels of this file, copied into the brief>
+```
+
+## The detection lenses
+
+Each lens has one line, so a brief names the lenses that belong to its focus.
+
+- Inconsistency between artifacts - reads `spec/SPEC.md`, `research/RESEARCH.md`, `plan/PLAN.md` and the mocks against each other, for two statements that cannot both be true.
+- Coverage of the requirements - see the block below.
+- Missing detail and unhandled edge cases - reads the requirements and the flows for the empty, error and limit cases nobody wrote down.
+- Ambiguity and untestable requirements - reads `spec/SPEC.md` for an open `[NEEDS CLARIFICATION: ...]` marker, a requirement with no acceptance criterion, and a requirement nobody could call pass or fail.
+- Duplication and overlap - reads the artifacts for the same thing stated twice, in two places that can drift apart.
+- Terminology drift - reads every artifact for one idea under several names, or one name over several ideas.
+- Principles alignment - reads the artifacts against the principles file and the repo's own rule files.
+- Better ways to do this - reads the design against the codebase for a simpler shape, and for code the repo already ships that does part of the work.
+- Design blockers - reads the design for what would send the build wrong, and reports at HIGH and CRITICAL alone.
+
+The consistency-and-completeness reviewer takes every lens except principles alignment, better ways to do this, and design blockers, which go to the reviewers of those names.
+A focus outside this set takes the lenses that touch it.
+Every lens goes to exactly one reviewer on the confirmed panel, so a panel that drops a focus hands that focus's lenses to the reviewer nearest to it.
+
+## The coverage lens
+
+When the protocol includes the execution plan stage, the coverage lens runs two checks.
+It checks that every requirement ID in `spec/SPEC.md` appears in some phase's `Covers` line in `plan/PLAN.md`.
+It also checks that every ID named in a `Covers` line exists in `spec/SPEC.md`.
+A requirement with no plan coverage is a CRITICAL finding.
+The reviewer states which of two causes it looks like: a missing phase, or scope that belongs in the non-goals.
+When the protocol has no execution plan stage, the lens checks instead that every requirement carries its own acceptance criterion, and reads as a pass or a fail.
+
+## The severity levels
+
+- **CRITICAL** - a principles violation, a contradiction between artifacts, or a requirement with no plan coverage.
+- **HIGH** - a conflicting or untestable requirement, an ambiguous security or performance attribute.
+- **MEDIUM** - terminology drift, an edge case with missing detail.
+- **LOW** - style and wording.
+
+Fix a conflict with a principle by changing the work.
+Never resolve it by softening the principle.
+
+## The design-blockers loop
+
+One reviewer on every panel has the design-blockers focus.
+Its brief is the brief above, with two additions:
+
+- It reports HIGH and CRITICAL findings alone. Anything below that is not its business, and another reviewer has it.
+- It reads for what would send the build wrong: a design that cannot hold, a contract two artifacts read differently, a requirement whose shape makes it unbuildable as written.
+
+**The loop.**
+Run the blockers reviewer.
+Fix what it found.
+Then run it again, with fresh context, over the fixed artifacts.
+Repeat until a round returns nothing.
+A fresh run each time is the point: a reviewer that saw the last round would grade its own fixes.
+
+**The guardrail.**
+A scoped reviewer has no natural zero.
+Given fixed artifacts and a mandate to find HIGH findings, a reviewer finds HIGH findings, and the rounds degrade into ever smaller material dressed in a severity it does not carry.
+
+So judge every returned finding before you loop again, against one criterion:
+
+> A finding an executing agent would likely have resolved on its own is not a true design blocker, whatever severity the reviewer gave it.
+
+An executing agent reads the code, runs the tests, and makes the small calls the spec left open.
+That is its job.
+A finding that names one of those calls is execution's work, and the plan's own review checkpoints cover it.
+
+**The close.**
+A round whose findings all fail that test closes the loop.
+Record the judgment per finding in the report - what it was, and why it failed the test - and leave that material to execution.
+Only a finding that passes the test justifies another round.
+
+Convergence here is judged, never awaited.
+Do not run a further round in the hope of a zero.
+
+## The report format
+
+`review/REVIEW.md`:
+
+```markdown
+# Quality review - <title of the work>
+
+- Run: YYYY-MM-DD
+- Mode: fresh-context subagents | inline - the session that wrote the spec
+- Panel: <one focus per reviewer>
+- Blockers loop: <n> rounds, closed by <a zero round | judgment>
+- Findings: <total>, of which <n> applied, <n> dismissed, <n> waiting on you
+
+## <the first reviewer's focus>
+
+- [x] <a check this reviewer ran and passed>
+- [ ] <a check it ran and failed>
+
+### RV-01 - <the finding in one line>
+
+- Severity: HIGH
+- Points at: SPEC.md, the Requirements section, FR-04
+- State: FOR YOUR DECISION
+- Options: <first option> | <second option>
+- Reasoning: <why the reviewer raised it>
+- Note: <the fix applied, the reason it was dismissed, or what the reviewer recommends>
+
+### RV-02 - <the finding in one line>
+
+- Severity: MEDIUM
+- Points at: SPEC.md, the Data section
+- State: APPLIED
+- Reasoning: <why the reviewer raised it>
+- Note: <the fix that was applied>
+
+## Design blockers
+
+### Round 1
+
+<the findings of that round, in the form above>
+
+### Round 2 - closed by judgment
+
+<each finding, with the judgment against the criterion and where the material was left>
+```
+
+The running agent assembles this report from the reviewers' replies.
+It writes the header block, and puts each reviewer's checklist and findings under that reviewer's focus.
+It assigns the ids and the states.
+Finding ids run `RV-01`, `RV-02`, and so on, in writing order across the whole report.
+An id never changes, so a decision that names a finding still points at the same finding.
+
+`State:` holds `APPLIED`, `DISMISSED` or `FOR YOUR DECISION`.
+A finding that waits on the user carries an `Options:` line, recommended option first.
+Every other finding leaves that line out.
+The report keeps every finding, applied and dismissed included.
+A finding the user decides on keeps its id and gains the outcome in its `Note:` line.
+Applying that decision changes its `State:` line: `APPLIED` when the decision changed the artifacts, and `DISMISSED` when the user left them as they are.
+Either way, drop the `Options:` line and update the counts in the header.

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

@@ -0,0 +1,125 @@
+# What goes in SPEC.md
+
+The technical specs stage of `/dx-spec` uses this guide, and so does every other stage that writes into `SPEC.md`.
+
+**No fixed template.**
+Write the sections the work needs, and name and order them to fit the work.
+A small chore may need a few lines. A large feature may need many sections.
+Common sections are: goal, context, scope and **non-goals**, requirements or behavior, edge cases and errors, data and contracts, constraints, and acceptance criteria.
+For the constraints, follow the repo's own rules in `CLAUDE.md` or `AGENTS.md`.
+Drop every section that does not apply.
+Label anything left open as an **assumption** or an **open question**.
+Write each date as an absolute date.
+Reference code as `path:line`.
+
+**Mark each ambiguity that is worth the user's time.**
+Write the mark where the ambiguity sits: `[NEEDS CLARIFICATION: <the specific question>]`.
+Add a mark when a choice changes the scope or the behavior by a large amount, when more than one reading is reasonable, or when no reasonable default exists.
+For an ambiguity below that bar, write a labeled assumption stating the guess, so no choice stays silent.
+
+**At most 3 markers stay open at one time.**
+When more candidates clear the bar, keep the markers in this priority order: scope first, then security and privacy, then the user's experience, then technical detail.
+Turn the rest into labeled assumptions.
+To clear a marker, ask the user. The answer replaces the marker in `SPEC.md`, in the same round the user answered.
+A doubt anywhere outside these stages does not wait: ask it in the next round.
+The finalize gate does not pass while a marker stays open.
+
+**Requirements carry IDs and acceptance criteria** when the protocol includes the execution plan stage or the quality review stage.
+With neither stage, write the requirements in plain language instead.
+Number each ID in writing order, as `FR-01`, `FR-02`, and so on.
+Never renumber an ID after you write it, so a phase or a finding that names one still points at the same requirement.
+Give each ID exactly one requirement.
+Phrase each requirement so a reviewer can call it a pass or a fail.
+Write its acceptance criterion under it, on its own line, as `AC: <how to tell it holds>`.
+
+The spec also states its success criteria: the measures that show the work is done.
+Write each one so it can be measured, and without naming a technology where the work allows that.
+Success criteria carry no IDs.
+
+```markdown
+- **FR-01**: the cart banner shows the discount total on every page of the checkout flow.
+  AC: a cart with a discount shows that total on cart, address, and payment.
+- **FR-02**: an expired discount code is rejected with a message naming its expiry date.
+  AC: submitting an expired code leaves the total unchanged and shows that date.
+```
+
+**Add a `Decisions` section** to any work that picks a stack, a package, or an algorithm.
+Write one entry per choice: the choice, the reason for it, and the alternatives the work rejected with the reason for each.
+The research stage produces the comparison behind a decision, and the spec records its outcome.
+
+**Add a `Mocks` section** when the UI mocks stage runs.
+Write one line per screen: its id, its title, and the path to its page relative to `SPEC.md`.
+After the user approves the mocks, add a line `Approved: YYYY-MM-DD`.
+
+```markdown
+## Mocks
+
+- `cart-banner` - Cart banner - ../mocks/cart-banner.html
+- `discount-field` - Discount field - ../mocks/discount-field.html
+
+Approved: 2026-08-14
+```
+
+**Add a `North star` section** when the run ran in imagination mode, and under no other condition.
+The section holds the ideal the run reached for, beside what the work chose.
+Write it in three parts:
+
+- The ideal, in a few lines: what the best possible version of this work does for the user.
+- What the work chose, and what that choice gives up against the ideal.
+- A short note on what shaped the candidates: the prior art and the patterns the creative pass found.
+
+The executing agent steers its small decisions by this section, so write the ideal in terms of what the user gets, not in terms of files.
+
+**Add a visual to a section only where it earns its place.**
+Put it in the markdown itself: inline SVG for a flow or an architecture, or an HTML table or figure where markdown cannot show the same thing.
+The agent that reads `SPEC.md` and the user reading it on the tab then see the same content.
+The same rule holds for `PLAN.md` and `RESEARCH.md`.
+A visual that stands on its own goes beside the document instead, as `stages.md` says under **Visuals**.
+Either way, keep it self-contained: no external image, and no script.
+
+**Every spec carries these two notes.**
+
+1. At the top of the spec, close to as written:
+
+> **For the implementing agent - read this first.** This spec was written during planning with limited knowledge of the code.
+> Before building anything, review it carefully against the actual codebase and **plan first** (in plan mode, where your environment has one).
+> Treat nothing here as settled: if the spec turns out misaligned with the code, or you see a better path, **push back and raise it** rather than building something you can tell is off.
+
+2. Inside a solution sketch, where the spec has one, close to as written:
+
+> **This solution sketch is non-binding.** It is a suggested direction formed with limited knowledge during spec-writing, not a fixed instruction.
+> The implementing agent is free - and expected - to find the better design while building, and must flag any noticeable departure so the user stays informed.
+
+## The coherence rewrite
+
+A spec grows by rounds: the user says something at a gate, a reviewer finds something, a decision changes an artifact.
+Each of those leaves a scar - a paragraph patched in, a section that answers a question nobody reading it can see, a note about what changed.
+The artifacts then read as a history of the work rather than as a description of it, and the agent that builds from them pays for that.
+
+**Rewrite the touched artifacts right before the finalize gate, so they read as if written with everything known from the start.**
+The rewrite carries no review metadata, no revision note, and no trace of the round that caused a change.
+
+**When it runs.** When anything after the first writing changed the artifacts: the user's feedback, a review fix, a decision.
+**When it is skipped.** When nothing changed them. A spec that went through its stages once and was approved as written needs no rewrite.
+
+Keep a copy of each artifact before you touch it.
+Put the copies in `.rewrite/` inside the spec directory, under the same names.
+The review below reads them, and it is the only reader they have: without them a fresh reviewer can only read the new text, and the completeness check has nothing to check against.
+Delete `.rewrite/` when the review is done, before the finalize gate.
+
+Rewrite from meaning, not by patching.
+Read the whole artifact first and understand what it now says.
+Then write it again.
+Do not scan for the scars and repair only those spots: that leaves a stitched document, which is the thing this step exists to remove.
+Keep every fact, every requirement ID, every acceptance criterion, and every labeled assumption.
+An ID never changes, because a phase and a finding point at it.
+
+**One round of review follows every rewrite.**
+Run one fresh reviewer, once, scoped to the rewrite alone:
+
+- Completeness against the copies in `.rewrite/`, so no meaning was lost. Give the reviewer both paths and let it read them itself. Never summarize the old text for it: a summary of yours is what it is there to check.
+- The repo's own writing rules.
+
+Fix what it finds.
+That ends the step.
+There is no second round: a rewrite review that loops would be the scar-making round it exists to remove.