@ritualai/cli 0.3.2 → 0.4.0

package/skills/codex/ritual/SKILL.md

@@ -51,60 +51,161 @@ When **not** to use:
 - An exploration already exists with recommendations — fetch directly via `get_exploration` + `get_recommendations`
 - The user wants to *implement* a feature from existing recommendations — use `/ritual-builder-spec` (from `@ritual-ai/cli`)
 
-### Workflow — 7 phases
+### Workflow — 8 phases
 
 Each phase has explicit **[USER PAUSE]** points — never skip them.
 
 #### Phase 1 — Pick a workspace
 
-Call `mcp__ritual__list_workspaces`. Present as a numbered list (id, name).
+Resolution order:
 
-If the user only has one project workspace, confirm it directly: "I'll create this in *Acme Engineering*. Sound right?" — but still wait for **[USER PAUSE]**.
+1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Surface it to the user: "Using workspace **`{workspaceName}`** (bound to this repo). Sound right?" — wait for **[USER PAUSE]**.
+2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[USER PAUSE]** for selection.
+3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
 
-Store `workspace_id`.
+Store `workspace_id` for the rest of the flow.
+
+If you created a new workspace, suggest the user run `ritual init` to persist the binding into `.ritual/config.json` for next time (or write it yourself if the user is in a Claude Code session that can edit files).
+
+#### Phase 1.5 — Code reconnaissance
+
+**Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
+
+Before generating considerations, do a structured scan of the codebase so the sub-problems land specific to *this* code, not generic. The legacy system shipped considerations that read like a textbook table of contents because it skipped this step; the difference between "Conversion Timing, Trust Signals, Recovery Paths" (generic) and "Leverage `apps/checkout/session.py` anonymous-checkout path vs. adding a new step in `CheckoutSessionMixin`" (codebase-specific) is whether you did Phase 1.5.
+
+Steps:
+
+1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files (5–10 lines). Identify the language, framework, key directories.
+
+2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
+   - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
+   - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
+   - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
+   Cap at ~15 hits per pattern.
+
+3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate: "is the behavior we care about actually here, or does it call into somewhere else?"
+
+4. **Build a recon summary** — 5–10 lines, concrete file paths, key abstractions, observed constraints. Examples of GOOD summaries:
+
+   > Codebase recon (django-oscar, Django 5.0):
+   > - Booking flow lives in `apps/checkout/views.py` (`CheckoutSessionMixin` orchestrates the step chain)
+   > - Anonymous checkout already supported via `apps/checkout/session.py:CheckoutSessionData`
+   > - Account creation entry point: `apps/customer/forms.py:RegisterUserForm`
+   > - Strategy classes (`apps/partner/strategy.py`) are the conventional pluggability pattern
+   > - User-model split: `auth.User` is the Django auth user; `apps/customer/models.py:Customer` is the order-attached profile — they can be linked or anonymous
+
+5. **Surface to the user as a [USER PAUSE]**:
+
+   > Reading the codebase I see:
+   > <recon summary>
+   >
+   > Anything I'm missing about design intent or constraints I won't find by reading the code (e.g. business decisions, prod incidents, in-flight migrations)?
+
+   Wait for confirmation or additional context. The user's reply (if any) becomes part of the input to Phase 2.
+
+6. **Compose the augmented `raw_input` for Phase 2.** Concatenate:
+   - The user's original problem (verbatim, top)
+   - A `--- Codebase context ---` section with the recon summary
+   - The user's reply from step 5 if non-empty
+   - Phase 1.5 IS the difference between "generic considerations" and "considerations that name actual files and reference existing patterns". Don't skip the recon step. Don't compress the summary to one line.
+
+7. **Collect the `sources` array.** The file paths you read in step 3 — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, NOT `"./apps/checkout/views.py"` or absolute paths). This list is passed alongside `raw_input` to `generate_considerations` and `generate_problem_statement` so the API can auto-inject **prior knowledge-graph context** for overlapping files. Keep the list focused — only files you actually read and consider load-bearing for this problem. 5–10 is the sweet spot; >20 dilutes the KG signal.
+
+**[USER PAUSE]** confirmation of recon is required before proceeding.
 
 #### Phase 2 — Generate sub-problems
 
+##### 2.1 First draft
+
 Call `mcp__ritual__generate_considerations` with:
 - `workspace_id`
-- `raw_input` (the problem from the slash-command argument or chat)
+- `raw_input` (the user's problem + the Phase 1.5 codebase recon, concatenated as described above)
 - `template_id` (omit unless the user specified one)
+- `sources` (the file path list from Phase 1.5 step 7 — file-path strings only, e.g. `["apps/checkout/views.py", ...]`)
 
-LLM call, ~5-10s. Returns 5-6 sub-problems — different framing axes the agent should investigate.
+LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the agent should investigate. Track each one as `{ text, version: 1 }` in your working memory.
+
+**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
+
+> Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
+>  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
+>  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
+>  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
+>
+> I factored those into the sub-problems below.
+
+If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
 
 **[USER PAUSE]** Present as a numbered list and ask which to include:
 
-> Sub-problems the system identified:
+> Sub-problems the system identified (v1):
 >
 > 1. {sub-problem 1}
 > 2. {sub-problem 2}
 > ...
 >
-> Which should we factor into the scope? Pick any subset, or "all".
+> Which should we factor into the scope? Pick any subset, "all", or ask for a different framing (e.g. "make them more technical", "drop the measurement angle", "focus on enterprise").
+
+##### 2.2 Iteration loop
+
+If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
+
+Call `mcp__ritual__refine_considerations` with:
+- `workspace_id`, `raw_input`, `template_id`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
+- `change_prompt`: the user's request verbatim
+- `selected`: items from prior versions the user kept (track `{ text, from_version }`, send just `text`)
+- `dismissed`: items the user explicitly rejected
+- `session_id`: omitted on the first refinement; pass the `session_id` from the previous refine response on subsequent ones to chain context
+
+Track the new items as `{ text, version: N+1 }`. Present **alongside** the prior versions, not replacing them — the user can mix selections across versions.
+
+Loop until the user says "these are good" or picks a subset.
 
-Store the picked sub-problems (text strings — they'll go into `considerations[]` next call).
+**Critical**: never re-call `generate_considerations` for a refinement. That endpoint is stateless and re-rolls a fresh seed; you'll lose what the user just told you. The whole point of `refine_*` is the LLM sees the iteration context.
+
+Store the final picked sub-problems for Phase 3 — they go into `considerations[]`.
 
 #### Phase 3 — Generate scope
 
+##### 3.1 First draft
+
 Call `mcp__ritual__generate_problem_statement` with:
 - `workspace_id`
-- `raw_input`
-- `considerations` (the picks from Phase 2 — these are the sub-problems we just discussed)
+- `raw_input` (same augmented version from Phase 2)
+- `considerations` (the picks from Phase 2)
 - `template_id` (same as Phase 2 if used)
+- `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
+
+Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores. Treat this as **v1** of the problem statement.
+
+If the response includes `kg_context_used` with `implementationCount > 0`, prepend a note to the scope presentation:
 
-Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores.
+> *(Grounded in {N} prior implementation{s}: {top match name}, …)*
 
 **[USER PAUSE]** Present and ask:
 
-> Here's the scope:
+> Here's the scope (v1):
 >
 > > **{generated scope}**
 >
-> Looks good? Want to tighten / broaden / change the audience? Or "ship it" to lock it in.
+> Looks good? Want to tighten / broaden / change the audience / focus on a specific tier? Or "ship it" to lock it in.
+
+##### 3.2 Iteration loop
+
+If the user asks for a refinement:
+
+Call `mcp__ritual__refine_problem_statement` with:
+- `workspace_id`, `raw_input`, `considerations`, `template_id`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
+- `previous_problem_statement`: the FULL TEXT of the current best draft (the v1 you just showed)
+- `change_prompt`: the user's request verbatim ("tighten and drop the audience clause")
+- `version`: optional label like `"v2"` — purely for telemetry
+- `session_id`: omitted on the first refinement; chain on subsequent ones
+
+The returned text becomes `v2`. Show it. The user can iterate v2 → v3 → ... by calling refine again with `previous_problem_statement` set to the latest draft.
 
-If refinement requested: regenerate with the refinement appended to `raw_input`. Iterate until accepted.
+**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original v1. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements ("tighter, AND drop the audience clause, AND make it past-tense").
 
-Store the final scope as `problem_statement` for the next call.
+When the user accepts ("ship it" / "looks good"), store the final text as `problem_statement` for Phase 4.
 
 #### Phase 4 — Create the exploration
 

package/skills/cursor/ritual/SKILL.md

@@ -51,60 +51,161 @@ When **not** to use:
 - An exploration already exists with recommendations — fetch directly via `get_exploration` + `get_recommendations`
 - The user wants to *implement* a feature from existing recommendations — use `/ritual-builder-spec` (from `@ritual-ai/cli`)
 
-### Workflow — 7 phases
+### Workflow — 8 phases
 
 Each phase has explicit **[USER PAUSE]** points — never skip them.
 
 #### Phase 1 — Pick a workspace
 
-Call `mcp__ritual__list_workspaces`. Present as a numbered list (id, name).
+Resolution order:
 
-If the user only has one project workspace, confirm it directly: "I'll create this in *Acme Engineering*. Sound right?" — but still wait for **[USER PAUSE]**.
+1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Surface it to the user: "Using workspace **`{workspaceName}`** (bound to this repo). Sound right?" — wait for **[USER PAUSE]**.
+2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[USER PAUSE]** for selection.
+3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
 
-Store `workspace_id`.
+Store `workspace_id` for the rest of the flow.
+
+If you created a new workspace, suggest the user run `ritual init` to persist the binding into `.ritual/config.json` for next time (or write it yourself if the user is in a Claude Code session that can edit files).
+
+#### Phase 1.5 — Code reconnaissance
+
+**Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
+
+Before generating considerations, do a structured scan of the codebase so the sub-problems land specific to *this* code, not generic. The legacy system shipped considerations that read like a textbook table of contents because it skipped this step; the difference between "Conversion Timing, Trust Signals, Recovery Paths" (generic) and "Leverage `apps/checkout/session.py` anonymous-checkout path vs. adding a new step in `CheckoutSessionMixin`" (codebase-specific) is whether you did Phase 1.5.
+
+Steps:
+
+1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files (5–10 lines). Identify the language, framework, key directories.
+
+2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
+   - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
+   - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
+   - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
+   Cap at ~15 hits per pattern.
+
+3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate: "is the behavior we care about actually here, or does it call into somewhere else?"
+
+4. **Build a recon summary** — 5–10 lines, concrete file paths, key abstractions, observed constraints. Examples of GOOD summaries:
+
+   > Codebase recon (django-oscar, Django 5.0):
+   > - Booking flow lives in `apps/checkout/views.py` (`CheckoutSessionMixin` orchestrates the step chain)
+   > - Anonymous checkout already supported via `apps/checkout/session.py:CheckoutSessionData`
+   > - Account creation entry point: `apps/customer/forms.py:RegisterUserForm`
+   > - Strategy classes (`apps/partner/strategy.py`) are the conventional pluggability pattern
+   > - User-model split: `auth.User` is the Django auth user; `apps/customer/models.py:Customer` is the order-attached profile — they can be linked or anonymous
+
+5. **Surface to the user as a [USER PAUSE]**:
+
+   > Reading the codebase I see:
+   > <recon summary>
+   >
+   > Anything I'm missing about design intent or constraints I won't find by reading the code (e.g. business decisions, prod incidents, in-flight migrations)?
+
+   Wait for confirmation or additional context. The user's reply (if any) becomes part of the input to Phase 2.
+
+6. **Compose the augmented `raw_input` for Phase 2.** Concatenate:
+   - The user's original problem (verbatim, top)
+   - A `--- Codebase context ---` section with the recon summary
+   - The user's reply from step 5 if non-empty
+   - Phase 1.5 IS the difference between "generic considerations" and "considerations that name actual files and reference existing patterns". Don't skip the recon step. Don't compress the summary to one line.
+
+7. **Collect the `sources` array.** The file paths you read in step 3 — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, NOT `"./apps/checkout/views.py"` or absolute paths). This list is passed alongside `raw_input` to `generate_considerations` and `generate_problem_statement` so the API can auto-inject **prior knowledge-graph context** for overlapping files. Keep the list focused — only files you actually read and consider load-bearing for this problem. 5–10 is the sweet spot; >20 dilutes the KG signal.
+
+**[USER PAUSE]** confirmation of recon is required before proceeding.
 
 #### Phase 2 — Generate sub-problems
 
+##### 2.1 First draft
+
 Call `mcp__ritual__generate_considerations` with:
 - `workspace_id`
-- `raw_input` (the problem from the slash-command argument or chat)
+- `raw_input` (the user's problem + the Phase 1.5 codebase recon, concatenated as described above)
 - `template_id` (omit unless the user specified one)
+- `sources` (the file path list from Phase 1.5 step 7 — file-path strings only, e.g. `["apps/checkout/views.py", ...]`)
 
-LLM call, ~5-10s. Returns 5-6 sub-problems — different framing axes the agent should investigate.
+LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the agent should investigate. Track each one as `{ text, version: 1 }` in your working memory.
+
+**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
+
+> Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
+>  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
+>  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
+>  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
+>
+> I factored those into the sub-problems below.
+
+If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
 
 **[USER PAUSE]** Present as a numbered list and ask which to include:
 
-> Sub-problems the system identified:
+> Sub-problems the system identified (v1):
 >
 > 1. {sub-problem 1}
 > 2. {sub-problem 2}
 > ...
 >
-> Which should we factor into the scope? Pick any subset, or "all".
+> Which should we factor into the scope? Pick any subset, "all", or ask for a different framing (e.g. "make them more technical", "drop the measurement angle", "focus on enterprise").
+
+##### 2.2 Iteration loop
+
+If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
+
+Call `mcp__ritual__refine_considerations` with:
+- `workspace_id`, `raw_input`, `template_id`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
+- `change_prompt`: the user's request verbatim
+- `selected`: items from prior versions the user kept (track `{ text, from_version }`, send just `text`)
+- `dismissed`: items the user explicitly rejected
+- `session_id`: omitted on the first refinement; pass the `session_id` from the previous refine response on subsequent ones to chain context
+
+Track the new items as `{ text, version: N+1 }`. Present **alongside** the prior versions, not replacing them — the user can mix selections across versions.
+
+Loop until the user says "these are good" or picks a subset.
 
-Store the picked sub-problems (text strings — they'll go into `considerations[]` next call).
+**Critical**: never re-call `generate_considerations` for a refinement. That endpoint is stateless and re-rolls a fresh seed; you'll lose what the user just told you. The whole point of `refine_*` is the LLM sees the iteration context.
+
+Store the final picked sub-problems for Phase 3 — they go into `considerations[]`.
 
 #### Phase 3 — Generate scope
 
+##### 3.1 First draft
+
 Call `mcp__ritual__generate_problem_statement` with:
 - `workspace_id`
-- `raw_input`
-- `considerations` (the picks from Phase 2 — these are the sub-problems we just discussed)
+- `raw_input` (same augmented version from Phase 2)
+- `considerations` (the picks from Phase 2)
 - `template_id` (same as Phase 2 if used)
+- `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
+
+Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores. Treat this as **v1** of the problem statement.
+
+If the response includes `kg_context_used` with `implementationCount > 0`, prepend a note to the scope presentation:
 
-Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores.
+> *(Grounded in {N} prior implementation{s}: {top match name}, …)*
 
 **[USER PAUSE]** Present and ask:
 
-> Here's the scope:
+> Here's the scope (v1):
 >
 > > **{generated scope}**
 >
-> Looks good? Want to tighten / broaden / change the audience? Or "ship it" to lock it in.
+> Looks good? Want to tighten / broaden / change the audience / focus on a specific tier? Or "ship it" to lock it in.
+
+##### 3.2 Iteration loop
+
+If the user asks for a refinement:
+
+Call `mcp__ritual__refine_problem_statement` with:
+- `workspace_id`, `raw_input`, `considerations`, `template_id`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
+- `previous_problem_statement`: the FULL TEXT of the current best draft (the v1 you just showed)
+- `change_prompt`: the user's request verbatim ("tighten and drop the audience clause")
+- `version`: optional label like `"v2"` — purely for telemetry
+- `session_id`: omitted on the first refinement; chain on subsequent ones
+
+The returned text becomes `v2`. Show it. The user can iterate v2 → v3 → ... by calling refine again with `previous_problem_statement` set to the latest draft.
 
-If refinement requested: regenerate with the refinement appended to `raw_input`. Iterate until accepted.
+**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original v1. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements ("tighter, AND drop the audience clause, AND make it past-tense").
 
-Store the final scope as `problem_statement` for the next call.
+When the user accepts ("ship it" / "looks good"), store the final text as `problem_statement` for Phase 4.
 
 #### Phase 4 — Create the exploration
 

package/skills/gemini/ritual/SKILL.md

@@ -51,60 +51,161 @@ When **not** to use:
 - An exploration already exists with recommendations — fetch directly via `get_exploration` + `get_recommendations`
 - The user wants to *implement* a feature from existing recommendations — use `/ritual-builder-spec` (from `@ritual-ai/cli`)
 
-### Workflow — 7 phases
+### Workflow — 8 phases
 
 Each phase has explicit **[USER PAUSE]** points — never skip them.
 
 #### Phase 1 — Pick a workspace
 
-Call `mcp__ritual__list_workspaces`. Present as a numbered list (id, name).
+Resolution order:
 
-If the user only has one project workspace, confirm it directly: "I'll create this in *Acme Engineering*. Sound right?" — but still wait for **[USER PAUSE]**.
+1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Surface it to the user: "Using workspace **`{workspaceName}`** (bound to this repo). Sound right?" — wait for **[USER PAUSE]**.
+2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[USER PAUSE]** for selection.
+3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
 
-Store `workspace_id`.
+Store `workspace_id` for the rest of the flow.
+
+If you created a new workspace, suggest the user run `ritual init` to persist the binding into `.ritual/config.json` for next time (or write it yourself if the user is in a Claude Code session that can edit files).
+
+#### Phase 1.5 — Code reconnaissance
+
+**Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
+
+Before generating considerations, do a structured scan of the codebase so the sub-problems land specific to *this* code, not generic. The legacy system shipped considerations that read like a textbook table of contents because it skipped this step; the difference between "Conversion Timing, Trust Signals, Recovery Paths" (generic) and "Leverage `apps/checkout/session.py` anonymous-checkout path vs. adding a new step in `CheckoutSessionMixin`" (codebase-specific) is whether you did Phase 1.5.
+
+Steps:
+
+1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files (5–10 lines). Identify the language, framework, key directories.
+
+2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
+   - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
+   - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
+   - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
+   Cap at ~15 hits per pattern.
+
+3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate: "is the behavior we care about actually here, or does it call into somewhere else?"
+
+4. **Build a recon summary** — 5–10 lines, concrete file paths, key abstractions, observed constraints. Examples of GOOD summaries:
+
+   > Codebase recon (django-oscar, Django 5.0):
+   > - Booking flow lives in `apps/checkout/views.py` (`CheckoutSessionMixin` orchestrates the step chain)
+   > - Anonymous checkout already supported via `apps/checkout/session.py:CheckoutSessionData`
+   > - Account creation entry point: `apps/customer/forms.py:RegisterUserForm`
+   > - Strategy classes (`apps/partner/strategy.py`) are the conventional pluggability pattern
+   > - User-model split: `auth.User` is the Django auth user; `apps/customer/models.py:Customer` is the order-attached profile — they can be linked or anonymous
+
+5. **Surface to the user as a [USER PAUSE]**:
+
+   > Reading the codebase I see:
+   > <recon summary>
+   >
+   > Anything I'm missing about design intent or constraints I won't find by reading the code (e.g. business decisions, prod incidents, in-flight migrations)?
+
+   Wait for confirmation or additional context. The user's reply (if any) becomes part of the input to Phase 2.
+
+6. **Compose the augmented `raw_input` for Phase 2.** Concatenate:
+   - The user's original problem (verbatim, top)
+   - A `--- Codebase context ---` section with the recon summary
+   - The user's reply from step 5 if non-empty
+   - Phase 1.5 IS the difference between "generic considerations" and "considerations that name actual files and reference existing patterns". Don't skip the recon step. Don't compress the summary to one line.
+
+7. **Collect the `sources` array.** The file paths you read in step 3 — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, NOT `"./apps/checkout/views.py"` or absolute paths). This list is passed alongside `raw_input` to `generate_considerations` and `generate_problem_statement` so the API can auto-inject **prior knowledge-graph context** for overlapping files. Keep the list focused — only files you actually read and consider load-bearing for this problem. 5–10 is the sweet spot; >20 dilutes the KG signal.
+
+**[USER PAUSE]** confirmation of recon is required before proceeding.
 
 #### Phase 2 — Generate sub-problems
 
+##### 2.1 First draft
+
 Call `mcp__ritual__generate_considerations` with:
 - `workspace_id`
-- `raw_input` (the problem from the slash-command argument or chat)
+- `raw_input` (the user's problem + the Phase 1.5 codebase recon, concatenated as described above)
 - `template_id` (omit unless the user specified one)
+- `sources` (the file path list from Phase 1.5 step 7 — file-path strings only, e.g. `["apps/checkout/views.py", ...]`)
 
-LLM call, ~5-10s. Returns 5-6 sub-problems — different framing axes the agent should investigate.
+LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the agent should investigate. Track each one as `{ text, version: 1 }` in your working memory.
+
+**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
+
+> Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
+>  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
+>  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
+>  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
+>
+> I factored those into the sub-problems below.
+
+If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
 
 **[USER PAUSE]** Present as a numbered list and ask which to include:
 
-> Sub-problems the system identified:
+> Sub-problems the system identified (v1):
 >
 > 1. {sub-problem 1}
 > 2. {sub-problem 2}
 > ...
 >
-> Which should we factor into the scope? Pick any subset, or "all".
+> Which should we factor into the scope? Pick any subset, "all", or ask for a different framing (e.g. "make them more technical", "drop the measurement angle", "focus on enterprise").
+
+##### 2.2 Iteration loop
+
+If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
+
+Call `mcp__ritual__refine_considerations` with:
+- `workspace_id`, `raw_input`, `template_id`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
+- `change_prompt`: the user's request verbatim
+- `selected`: items from prior versions the user kept (track `{ text, from_version }`, send just `text`)
+- `dismissed`: items the user explicitly rejected
+- `session_id`: omitted on the first refinement; pass the `session_id` from the previous refine response on subsequent ones to chain context
+
+Track the new items as `{ text, version: N+1 }`. Present **alongside** the prior versions, not replacing them — the user can mix selections across versions.
+
+Loop until the user says "these are good" or picks a subset.
 
-Store the picked sub-problems (text strings — they'll go into `considerations[]` next call).
+**Critical**: never re-call `generate_considerations` for a refinement. That endpoint is stateless and re-rolls a fresh seed; you'll lose what the user just told you. The whole point of `refine_*` is the LLM sees the iteration context.
+
+Store the final picked sub-problems for Phase 3 — they go into `considerations[]`.
 
 #### Phase 3 — Generate scope
 
+##### 3.1 First draft
+
 Call `mcp__ritual__generate_problem_statement` with:
 - `workspace_id`
-- `raw_input`
-- `considerations` (the picks from Phase 2 — these are the sub-problems we just discussed)
+- `raw_input` (same augmented version from Phase 2)
+- `considerations` (the picks from Phase 2)
 - `template_id` (same as Phase 2 if used)
+- `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
+
+Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores. Treat this as **v1** of the problem statement.
+
+If the response includes `kg_context_used` with `implementationCount > 0`, prepend a note to the scope presentation:
 
-Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores.
+> *(Grounded in {N} prior implementation{s}: {top match name}, …)*
 
 **[USER PAUSE]** Present and ask:
 
-> Here's the scope:
+> Here's the scope (v1):
 >
 > > **{generated scope}**
 >
-> Looks good? Want to tighten / broaden / change the audience? Or "ship it" to lock it in.
+> Looks good? Want to tighten / broaden / change the audience / focus on a specific tier? Or "ship it" to lock it in.
+
+##### 3.2 Iteration loop
+
+If the user asks for a refinement:
+
+Call `mcp__ritual__refine_problem_statement` with:
+- `workspace_id`, `raw_input`, `considerations`, `template_id`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
+- `previous_problem_statement`: the FULL TEXT of the current best draft (the v1 you just showed)
+- `change_prompt`: the user's request verbatim ("tighten and drop the audience clause")
+- `version`: optional label like `"v2"` — purely for telemetry
+- `session_id`: omitted on the first refinement; chain on subsequent ones
+
+The returned text becomes `v2`. Show it. The user can iterate v2 → v3 → ... by calling refine again with `previous_problem_statement` set to the latest draft.
 
-If refinement requested: regenerate with the refinement appended to `raw_input`. Iterate until accepted.
+**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original v1. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements ("tighter, AND drop the audience clause, AND make it past-tense").
 
-Store the final scope as `problem_statement` for the next call.
+When the user accepts ("ship it" / "looks good"), store the final text as `problem_statement` for Phase 4.
 
 #### Phase 4 — Create the exploration