@ritualai/cli 0.36.35 → 0.36.36

package/skills/vscode/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 3cfb8c30115f21ac -->
+<!-- source-sha: d34e2df8a4177dbe -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -233,7 +233,7 @@ If the user types `always audit for this build` mid-flow at the Step 9.6 prompt,
 Persist `auditMode` to `Exploration.metadata.auditMode` at `create_exploration` time (additive JSONB key — no schema migration) so `/ritual resume <exploration-id>` picks up the same mode the original build started with, and `/ritual lineage <exploration-id>` can render which gates ran + their outcomes.
 
 
-<!-- skill-options:no-gate-change: 2b (clarifying question) + 2c (generic terminal) are loud-fallback COPY variants of the same gate; options are unchanged (proceed | name-the-job) -->
+<!-- skill-options:no-gate-change: 2b (low-confidence clarifying question — server sets clarifyingQuestion only when confidence <20% or it defaulted) + 2c (confident generic — accept and proceed) are COPY variants of the same gate; options are unchanged (proceed | name-the-job; 2b adds answer-the-question, which is a name-the-job correction) -->
 #### Step 0.7 — The Job gate: classify the job to be done
 
 **The FIRST tool call of a fresh build.** The server — not you — classifies the user's raw ask into
@@ -253,14 +253,18 @@ When this gate runs:
 
 1. **Call `mcp__ritual__classify_work_item`** with `raw_input` = the user's ask, verbatim. Do NOT
    classify yourself, do NOT pre-filter to development jobs. It returns
-   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, clarifyingQuestion?, personaCoverage }`.
    `isGenericFallback` (and `confidence`) are the typed-uncertainty signal: when it's `true`, the
    result is the catch-all (`build-feature` / `produce-deliverable`) or the classifier wasn't sure —
-   it is NOT a confident match, and which render variant you use in step 2 depends on it.
+   it is NOT a confident match, and which render variant you use in step 2 depends on it. On that
+   generic path the response also carries `clarifyingQuestion` — a plain-language question generated
+   from the user's ask, which step 2b renders verbatim to disambiguate toward a specific job.
 
 2. **Render the validation prompt** (rail stage `Job`). This gate is a plain-language VALIDATION of
    what you're about to build: restate the ask + the matched job in the user's words, then let them
-   confirm or correct. Which variant you render depends on `isGenericFallback`.
+   confirm or correct. Route to a variant by the response: a **`clarifyingQuestion`** present → **2b**
+   (we're genuinely unsure — ask, but let them proceed); else `isGenericFallback` true → **2c** (a
+   confident generic build — accept and proceed); else → **2a** (a confident specific match).
 
    **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
@@ -273,14 +277,17 @@ When this gate runs:
    Reply `proceed` if that's right, or tell me what to adjust.
    ```
 
-   **2b — No specific job matched, FIRST time** (`isGenericFallback` is `true` — the result is the
-   catch-all `build-feature` / `produce-deliverable`, or `confidence` is `low` — AND you have not yet
-   asked the clarifying question this gate): do NOT present the catch-all as a verdict. This case
-   should be RARE. Instead ask ONE clarifying question that elicits the missing signal — what KIND of
-   work this is — grounded in their ask, with concrete examples that lead the reply. The examples
-   span the catalog's functions so the user can self-identify; tailor the wording to their ask. This
-   is the fallback step that lets us classify properly instead of defaulting blind (see
-   `loud-fallback-escalation.md`).
+   **2b — Genuinely unsure: ask, but let them proceed** (the response carries a **`clarifyingQuestion`**
+   — the server sets it ONLY when it was essentially guessing: numeric confidence below 20, or it
+   failed to classify and defaulted). A generic result alone does NOT land here — only a *low-confidence*
+   one does; a confident generic build goes to **2c**. The clarifying question is a single plain-language
+   question the server generated FROM the user's specific ask. **Render it verbatim** — it is grounded in
+   their words and leak-free. Do not rephrase it, do not append a menu, do not mention classification /
+   jobs / categories / confidence. The user has TWO ways out: answer to focus it, OR reply `proceed` to
+   continue with the deliverable. **Leak rule (load-bearing):** the rendered copy must NEVER say
+   "generic", "I couldn't classify", "fallback", "catch-all", or otherwise reveal that classification was
+   uncertain — that is internal state. Present it as a normal question about their ask. (See
+   `loud-fallback-escalation.md`.)
 
    ```text
    Ritual build
@@ -288,34 +295,35 @@ When this gate runs:
 
    You're looking to: {restate the ask in one short clause}
 
-   I couldn't pin this to a specific job — your ask reads as an outcome, and the flow scopes much
-   better when I know what KIND of work it is. Which is closest (or say it in your own words)?
-     • A coding-agent / MCP / skill capability — tooling the agent itself uses
-     • A backend service or API
-     • A frontend / UI feature
-     • A refactor, migration, or infra / platform change
-     • Something else — tell me in a sentence
+   {clarifyingQuestion — verbatim}
 
-   Reply with the closest fit (or your own words) and I'll lock the job.
+   Answer in a sentence — or reply `proceed` and I'll continue with a {Deliverable}.
    ```
 
-   When the user answers, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
-   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a
-   specific job, otherwise **2c**.
+   (Rare degraded case — you reached 2b but `clarifyingQuestion` is missing: ask which KIND of work it
+   is, with the same `proceed` option — • a coding-agent / MCP / skill capability • a backend service
+   or API • a frontend / UI feature • a refactor, migration, or infra change • something else, in your
+   own words.)
 
-   **2c — Still generic after the clarifying question** (`isGenericFallback` is STILL `true` after the
-   user answered 2b): do NOT ask again. Proceed as a generic build with the function-agnostic
-   `Feature Brief` deliverable, and note the job can be renamed later. The job name stays generic —
-   never show a function-specific deliverable (e.g. "Frontend Web") for an unclassified build.
+   If the user ANSWERS, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
+   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a specific
+   job, otherwise **2c**. If the user replies `proceed`, go straight to **2c** (accept the generic).
+
+   **2c — Accept and proceed** (`isGenericFallback` is `true` with NO `clarifyingQuestion` — a
+   confident-enough generic build — OR the user chose to proceed from 2b, OR a re-classification is still
+   generic): do NOT interrogate. Present the deliverable as a normal accept-and-proceed — **same clean
+   shape as 2a**. Internally the job stays generic and is renamable later, but **the rendered copy must
+   NEVER say "generic", "couldn't classify", "fallback", or otherwise reveal that** — that is internal
+   state. Just name what Ritual will produce for their ask. (Never show a function-specific deliverable
+   like "Frontend Web" for an unclassified build — only the function-agnostic `Feature Brief`.)
 
    ```text
    Ritual build
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
 
-   You're looking to: {restate the ask in one short clause}
-   I'll treat this as a generic build — deliverable: Feature Brief. You can rename the job later.
+   Ritual will produce a {Deliverable} for {restate the ask in one short clause}.
 
-   Reply `proceed` to frame the problem.
+   Reply `proceed` if that's right, or tell me what to focus on.
    ```
 
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
@@ -2262,7 +2270,7 @@ The Build Brief is the markdown document the engineer reads RIGHT BEFORE writing
 Call `mcp__ritual__generate_build_brief` with:
 
 - `exploration_id`
-- `icp` (optional — defaults to the exploration template's primary ICP, then PM; pass `TECH_PM` for engineering-flavored explorations)
+- `icp` — **omit this.** The brief sources from the requirement set the flow already generated (on accept), whose ICP the server resolves from the exploration's persona/template. Passing a different ICP here forces a redundant requirement regeneration and a slow cold start. The engineering flavor is already baked into the server-resolved template — you do not need to (and should not) pass `TECH_PM` or any other ICP.
 - `recon_context` — the Step 3 `codebase_context_packet` plus any explicit phase/later candidates from discovery. Do not pass raw recon notes. This grounds "Codebase Anchors" in real file paths while keeping agent hypotheses auditable and non-authoritative.
 - `sources` — the **same** file-path array passed to `generate_considerations` and `generate_problem_statement` in Steps 4–5. Critical for KG consistency: the brief's "Previously Deferred" section only populates when overlapping prior implementations exist on these files.