@ritualai/cli 0.11.0 → 0.25.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/doctor.js +59 -23
- package/dist/commands/doctor.js.map +1 -1
- package/dist/commands/init.js +35 -0
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/uninstall.js +114 -0
- package/dist/commands/uninstall.js.map +1 -0
- package/dist/index.js +10 -0
- package/dist/index.js.map +1 -1
- package/dist/lib/agents/providers.js +44 -4
- package/dist/lib/agents/providers.js.map +1 -1
- package/dist/lib/memory-update.js +158 -0
- package/dist/lib/memory-update.js.map +1 -0
- package/dist/lib/uninstall-plan.js +102 -0
- package/dist/lib/uninstall-plan.js.map +1 -0
- package/package.json +1 -1
- package/skills/claude-code/ritual/.ritual-bundle.json +2 -2
- package/skills/claude-code/ritual/SKILL.md +14 -11
- package/skills/claude-code/ritual/manifest.json +0 -5
- package/skills/claude-code/ritual/references/async-polling.md +5 -5
- package/skills/claude-code/ritual/references/brief-verification-checklist.md +12 -6
- package/skills/claude-code/ritual/references/build-flow.md +569 -581
- package/skills/claude-code/ritual/references/change-preflight.md +81 -0
- package/skills/claude-code/ritual/references/cli-output-contract.md +44 -28
- package/skills/claude-code/ritual/references/context-pulse-flow.md +0 -1
- package/skills/claude-code/ritual/references/lite-flow.md +2750 -0
- package/skills/claude-code/ritual/references/resume-flow.md +1 -1
- package/skills/claude-code/ritual/references/scoring-fallback.md +1 -1
- package/skills/codex/ritual/.ritual-bundle.json +2 -2
- package/skills/codex/ritual/SKILL.md +14 -11
- package/skills/codex/ritual/manifest.json +0 -5
- package/skills/codex/ritual/references/async-polling.md +5 -5
- package/skills/codex/ritual/references/brief-verification-checklist.md +12 -6
- package/skills/codex/ritual/references/build-flow.md +569 -581
- package/skills/codex/ritual/references/change-preflight.md +81 -0
- package/skills/codex/ritual/references/cli-output-contract.md +44 -28
- package/skills/codex/ritual/references/context-pulse-flow.md +0 -1
- package/skills/codex/ritual/references/lite-flow.md +2750 -0
- package/skills/codex/ritual/references/resume-flow.md +1 -1
- package/skills/codex/ritual/references/scoring-fallback.md +1 -1
- package/skills/cursor/ritual/.ritual-bundle.json +2 -2
- package/skills/cursor/ritual/SKILL.md +14 -11
- package/skills/cursor/ritual/manifest.json +0 -5
- package/skills/cursor/ritual/references/async-polling.md +5 -5
- package/skills/cursor/ritual/references/brief-verification-checklist.md +12 -6
- package/skills/cursor/ritual/references/build-flow.md +569 -581
- package/skills/cursor/ritual/references/change-preflight.md +81 -0
- package/skills/cursor/ritual/references/cli-output-contract.md +44 -28
- package/skills/cursor/ritual/references/context-pulse-flow.md +0 -1
- package/skills/cursor/ritual/references/lite-flow.md +2750 -0
- package/skills/cursor/ritual/references/resume-flow.md +1 -1
- package/skills/cursor/ritual/references/scoring-fallback.md +1 -1
- package/skills/gemini/ritual/.ritual-bundle.json +2 -2
- package/skills/gemini/ritual/SKILL.md +14 -11
- package/skills/gemini/ritual/manifest.json +0 -5
- package/skills/gemini/ritual/references/async-polling.md +5 -5
- package/skills/gemini/ritual/references/brief-verification-checklist.md +12 -6
- package/skills/gemini/ritual/references/build-flow.md +569 -581
- package/skills/gemini/ritual/references/change-preflight.md +81 -0
- package/skills/gemini/ritual/references/cli-output-contract.md +44 -28
- package/skills/gemini/ritual/references/context-pulse-flow.md +0 -1
- package/skills/gemini/ritual/references/lite-flow.md +2750 -0
- package/skills/gemini/ritual/references/resume-flow.md +1 -1
- package/skills/gemini/ritual/references/scoring-fallback.md +1 -1
- package/skills/kiro/ritual/.ritual-bundle.json +2 -2
- package/skills/kiro/ritual/SKILL.md +14 -11
- package/skills/kiro/ritual/manifest.json +0 -5
- package/skills/kiro/ritual/references/async-polling.md +5 -5
- package/skills/kiro/ritual/references/brief-verification-checklist.md +12 -6
- package/skills/kiro/ritual/references/build-flow.md +569 -581
- package/skills/kiro/ritual/references/change-preflight.md +81 -0
- package/skills/kiro/ritual/references/cli-output-contract.md +44 -28
- package/skills/kiro/ritual/references/context-pulse-flow.md +0 -1
- package/skills/kiro/ritual/references/lite-flow.md +2750 -0
- package/skills/kiro/ritual/references/resume-flow.md +1 -1
- package/skills/kiro/ritual/references/scoring-fallback.md +1 -1
- package/skills/vscode/ritual/.ritual-bundle.json +2 -2
- package/skills/vscode/ritual/SKILL.md +14 -11
- package/skills/vscode/ritual/manifest.json +0 -5
- package/skills/vscode/ritual/references/async-polling.md +5 -5
- package/skills/vscode/ritual/references/brief-verification-checklist.md +12 -6
- package/skills/vscode/ritual/references/build-flow.md +569 -581
- package/skills/vscode/ritual/references/change-preflight.md +81 -0
- package/skills/vscode/ritual/references/cli-output-contract.md +44 -28
- package/skills/vscode/ritual/references/context-pulse-flow.md +0 -1
- package/skills/vscode/ritual/references/lite-flow.md +2750 -0
- package/skills/vscode/ritual/references/resume-flow.md +1 -1
- package/skills/vscode/ritual/references/scoring-fallback.md +1 -1
- package/skills/claude-code/ritual/references/discovery-classification.md +0 -175
- package/skills/codex/ritual/references/discovery-classification.md +0 -175
- package/skills/cursor/ritual/references/discovery-classification.md +0 -175
- package/skills/gemini/ritual/references/discovery-classification.md +0 -175
- package/skills/kiro/ritual/references/discovery-classification.md +0 -175
- package/skills/vscode/ritual/references/discovery-classification.md +0 -175
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
# Discovery classification reference
|
|
2
|
-
|
|
3
|
-
Loaded only when `/ritual build` question picking triggers scope classification.
|
|
4
|
-
|
|
5
|
-
##### 7.4.5 — Scope Classification Check (conditional)
|
|
6
|
-
|
|
7
|
-
When the user picks discovery questions, the gap between **what the problem statement asks about** and **what the user actually chose to investigate** is the agent's first concrete read on whether the scope is genuinely narrow, deliberately sequenced, or under-engaged. This step makes that gap visible — but ONLY when the signal warrants it.
|
|
8
|
-
|
|
9
|
-
**Design principle (locked):** *Don't make the user optimize the score. Let the score explain what just happened.* The menu asks a plain product question; the pulse confirms the consequence afterward. Never preview deltas inside the choice menu.
|
|
10
|
-
|
|
11
|
-
###### Per-question typed status
|
|
12
|
-
|
|
13
|
-
Once Step 7.4 lands, the agent tracks an in-session status for every surfaced question. Statuses are ephemeral (not persisted to the DB yet — that's a follow-up); they carry through this `/ritual build` session only:
|
|
14
|
-
|
|
15
|
-
| Status | Meaning |
|
|
16
|
-
|---|---|
|
|
17
|
-
| **`picked`** | User selected for active investigation (passed to `start_agentic_run`) |
|
|
18
|
-
| **`deferred`** | Deliberate phase-2 candidate; surfaces in build brief's "Phase Candidates" section. NOT context debt. |
|
|
19
|
-
| **`dropped`** | Removed from scope; problem statement gets narrowed to exclude this concern. |
|
|
20
|
-
| **`unreviewed`** | Default state for every surfaced question until the user classifies it. Counts toward debt if the user proceeds to Step 8 without resolving. |
|
|
21
|
-
|
|
22
|
-
`picked` is set automatically by the per-matter accept calls in 7.4. The other three are set by the Step 7.4.5 branches below.
|
|
23
|
-
|
|
24
|
-
###### Conditional trigger
|
|
25
|
-
|
|
26
|
-
Step 7.4.5 fires **only** when at least one of these holds — otherwise proceed silently to 7.5:
|
|
27
|
-
|
|
28
|
-
- **Pick-rate < 40%** (picked / total_surfaced)
|
|
29
|
-
- **Matter coverage ≤ 50%** (matters with ≥ 1 pick / total matters)
|
|
30
|
-
- **Pick-rate = 100%** (no-discrimination signal — see "no-discrimination case" below)
|
|
31
|
-
- **Concentration heuristic**: a single matter holds ≥ 60% of the picks while the problem statement spans multiple distinct concerns
|
|
32
|
-
|
|
33
|
-
If none hold, the user's scope intent is already obvious; don't add a check. Continue to Step 7.5.
|
|
34
|
-
|
|
35
|
-
###### Signal mapping
|
|
36
|
-
|
|
37
|
-
Before surfacing the prompt, the agent maps which problem-statement concerns are covered by the picks. Concerns are derived from the problem statement's noun-phrases (loose keyword-match against matter names is sufficient for MVP; LLM-rated mapping is a follow-up). For each unpicked matter, identify which problem-statement concern(s) it represents.
|
|
38
|
-
|
|
39
|
-
Output the analysis in plain language — three paragraphs (data → qualitative pattern → gap statement). Em-dash separating stats reads better than parenthetical. Example with real numbers (from the django-oscar GDPR exploration testing):
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
You picked 8 of 73 questions across 4 of 8 matters — an 11% pick-rate
|
|
43
|
-
with 50% matter coverage.
|
|
44
|
-
|
|
45
|
-
Your picks concentrate on the structural foundation: what the data is,
|
|
46
|
-
where it lives, immutability, and retention categories.
|
|
47
|
-
|
|
48
|
-
Your problem statement also mentions erasure mechanics, scheduled cleanup
|
|
49
|
-
jobs, DSAR APIs, and audit observability. Those areas are currently
|
|
50
|
-
unpicked.
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
The **dominant theme phrase** ("structural foundation: what the data is, where it lives, immutability, and retention categories" in the example) is computed once here and reused in Option 1's prompt below — that keeps the user's decision concrete instead of abstract.
|
|
54
|
-
|
|
55
|
-
###### The 4-option prompt (plain language only — no score previews)
|
|
56
|
-
|
|
57
|
-
Reuse the dominant-theme phrase from the analysis paragraph in Option 1 so the user reads the *narrowed scope* in product terms before deciding, not after.
|
|
58
|
-
|
|
59
|
-
```
|
|
60
|
-
How should I treat the unpicked areas?
|
|
61
|
-
|
|
62
|
-
1. Out of scope — tighten the problem statement around {dominant theme
|
|
63
|
-
from analysis paragraph: e.g. "data structure, storage, immutability,
|
|
64
|
-
and retention categories"}.
|
|
65
|
-
Unpicked concerns are dropped from the current HMW.
|
|
66
|
-
|
|
67
|
-
2. Later phase — keep the broad scope, but mark unpicked matters as
|
|
68
|
-
phase-2 candidates surfaced in the build brief.
|
|
69
|
-
Use this when the unpicked work depends on the picked foundation
|
|
70
|
-
being settled first.
|
|
71
|
-
|
|
72
|
-
3. Open questions — keep the broad scope and treat unpicked areas as
|
|
73
|
-
context debt to revisit.
|
|
74
|
-
|
|
75
|
-
4. Pick more — return to Step 7.3 and add picks before continuing.
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**Copy notes:**
|
|
79
|
-
- "the current HMW" (not "the HMW") — Branch 1 is present-cycle, not permanent. Reduces commitment-anxiety.
|
|
80
|
-
- "treat unpicked areas as context debt" (not "Unpicked counts as context debt") — grammatical, less terse.
|
|
81
|
-
- Option 2's "Use this when..." stays as a separate declarative sentence — less leading than a parenthetical, but still teaches the right sequencing intuition.
|
|
82
|
-
- Option 4 uses "return to" not "loop back to" — cleaner agent voice.
|
|
83
|
-
|
|
84
|
-
###### Per-branch handlers
|
|
85
|
-
|
|
86
|
-
**Branch 1 — Out of scope (tighten):**
|
|
87
|
-
1. Mark all unpicked questions across all matters as `dropped`.
|
|
88
|
-
2. Call `mcp__ritual__refine_problem_statement` with `change_prompt`: *"Narrow the scope to focus only on {comma-joined matter names of picked matters}. Drop concerns related to {comma-joined names of dropped matters}."*
|
|
89
|
-
3. Emit post-choice pulse — **reuse the same dominant-theme phrase** that appeared in the analysis paragraph + Option 1's prompt, so the user sees their choice acknowledged in the exact words they read:
|
|
90
|
-
```
|
|
91
|
-
✓ Tightened the problem statement around {dominant theme — same phrase as analysis paragraph + Option 1 prompt}.
|
|
92
|
-
Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +{delta}% (feature clarity ↑ from narrower scope)
|
|
93
|
-
```
|
|
94
|
-
Concrete example matching the django-oscar GDPR exploration: *"✓ Tightened the problem statement around data structure, storage, immutability, and retention categories."* — names what survived, not abstract *"the structural picks"*.
|
|
95
|
-
|
|
96
|
-
**Branch 2 — Later phase (defer):**
|
|
97
|
-
1. Mark all unpicked questions across all matters as `deferred`.
|
|
98
|
-
2. No problem statement change (broad scope preserved).
|
|
99
|
-
3. Emit post-choice pulse — **note the second-field label is `deferred`, not `debt`**:
|
|
100
|
-
```
|
|
101
|
-
✓ {N} unpicked questions marked as phase-2 candidates.
|
|
102
|
-
Pulse: Reasoning Readiness {readiness}% · Phase-later {deferred}% · +{delta}% (decision resolution ↑ from deliberate deferral)
|
|
103
|
-
```
|
|
104
|
-
The `deferred` label (instead of `debt`) is load-bearing — deliberate sequencing is NOT a liability, and the pulse line should reflect that. Same number, different character.
|
|
105
|
-
4. At Step 10c (build brief generation), the deferred matters MUST appear in the brief's *"Phase Candidates / Deferrable Items"* section. The agent appends the `deferred[]` set to the `generate_build_brief` `recon_context` payload as supplementary "explicit phase-2 candidates set by the user during discovery." The main `recon_context` payload remains the `codebase_context_packet`.
|
|
106
|
-
|
|
107
|
-
**Branch 3 — Open questions (debt):**
|
|
108
|
-
1. Mark all unpicked questions as `unreviewed` (their default state — no change).
|
|
109
|
-
2. No problem statement change.
|
|
110
|
-
3. Emit post-choice pulse — uses the `debt` label:
|
|
111
|
-
```
|
|
112
|
-
✓ {N} unpicked questions marked as context debt.
|
|
113
|
-
Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +0% (open questions remain unresolved)
|
|
114
|
-
```
|
|
115
|
-
Avoid words like *"status quo"* — phrase it as a state, not a non-event.
|
|
116
|
-
4. The next `/ritual context-pulse` will surface the unresolved questions as top debt sources.
|
|
117
|
-
|
|
118
|
-
**Branch 4 — Pick more (loop):**
|
|
119
|
-
1. No status change.
|
|
120
|
-
2. No pulse.
|
|
121
|
-
3. Surface the unpicked matters in a numbered list grouped by matter:
|
|
122
|
-
```
|
|
123
|
-
Returning to question picking. Unpicked matters and questions:
|
|
124
|
-
|
|
125
|
-
M5 — Erasure Anonymization Contract (10 questions)
|
|
126
|
-
M6 — Scheduled Cleanup Idempotency (8 questions)
|
|
127
|
-
M7 — DSAR Attribution Interfaces (9 questions)
|
|
128
|
-
M8 — Compliance Audit Observability (8 questions)
|
|
129
|
-
|
|
130
|
-
Pick any subset. Same per-matter accept flow as Step 7.4.
|
|
131
|
-
```
|
|
132
|
-
4. After new picks land, re-evaluate the trigger conditions. If still met, fire 7.4.5 again. Otherwise proceed to 7.5.
|
|
133
|
-
|
|
134
|
-
###### The no-discrimination case (100% pick-rate)
|
|
135
|
-
|
|
136
|
-
If trigger fired because pick-rate = 100% (user picked every question), the prompt shape is gentler — there's no "unpicked areas" to classify. Instead:
|
|
137
|
-
|
|
138
|
-
```
|
|
139
|
-
You picked everything (73/73 questions).
|
|
140
|
-
|
|
141
|
-
That may mean every question is genuinely relevant — the breadth is real.
|
|
142
|
-
Or it may mean we haven't narrowed the investigation yet. Pick one:
|
|
143
|
-
|
|
144
|
-
1. Proceed broadly — run all questions through the agentic pipeline. The
|
|
145
|
-
build brief will be wide; recommendations cover everything.
|
|
146
|
-
|
|
147
|
-
2. Sharper first pass — let me suggest 5-10 highest-leverage questions
|
|
148
|
-
that would give you the most signal per LLM call. The rest become
|
|
149
|
-
phase-2 candidates.
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
If user picks (1): proceed silently to Step 7.5. No pulse change.
|
|
153
|
-
If user picks (2): agent ranks the 73 questions by leverage (LLM call OR heuristic: questions earlier in each matter tend to be foundational), surfaces the top 5-10, user re-confirms picks, others become `deferred`. Fall back to Branch 2's behavior.
|
|
154
|
-
|
|
155
|
-
###### Two-score model in the pulse (CP3 update)
|
|
156
|
-
|
|
157
|
-
Once Step 7.4.5 has run, the `/ritual context-pulse` Step CP3 formula reads from the typed-status counts:
|
|
158
|
-
|
|
159
|
-
- **Decision Resolution (current scope):** `picked / (picked + unreviewed)`. Excludes `deferred` + `dropped`. Reaches near-100% if the user classified everything (picked, deferred, or dropped) — judgment rewarded.
|
|
160
|
-
- **Total-problem Coverage:** `(picked + deferred + dropped) / total`. Shows how much of the original surfaced space has been *classified at all*, regardless of how. Surfaces in the full pulse as an annotation; `unreviewed` count is the implicit debt.
|
|
161
|
-
|
|
162
|
-
Compact pulse continues to lead with the single readiness · {debt|deferred} · delta line per the per-branch templates above. Full pulse adds the breakdown:
|
|
163
|
-
|
|
164
|
-
```
|
|
165
|
-
Reasoning readiness: 72%
|
|
166
|
-
Context debt: 12% (4 questions unreviewed)
|
|
167
|
-
Context deferred: 16% (12 questions phase-2 candidates)
|
|
168
|
-
Context surface: Recommendation-ready
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
When `Context deferred` is zero, omit that line (CLI Tenet #6 — silence on no-data).
|
|
172
|
-
|
|
173
|
-
###### After Step 7.4.5 completes
|
|
174
|
-
|
|
175
|
-
Continue to Step 7.5 (anti-goals capture) per the existing flow.
|
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
# Discovery classification reference
|
|
2
|
-
|
|
3
|
-
Loaded only when `/ritual build` question picking triggers scope classification.
|
|
4
|
-
|
|
5
|
-
##### 7.4.5 — Scope Classification Check (conditional)
|
|
6
|
-
|
|
7
|
-
When the user picks discovery questions, the gap between **what the problem statement asks about** and **what the user actually chose to investigate** is the agent's first concrete read on whether the scope is genuinely narrow, deliberately sequenced, or under-engaged. This step makes that gap visible — but ONLY when the signal warrants it.
|
|
8
|
-
|
|
9
|
-
**Design principle (locked):** *Don't make the user optimize the score. Let the score explain what just happened.* The menu asks a plain product question; the pulse confirms the consequence afterward. Never preview deltas inside the choice menu.
|
|
10
|
-
|
|
11
|
-
###### Per-question typed status
|
|
12
|
-
|
|
13
|
-
Once Step 7.4 lands, the agent tracks an in-session status for every surfaced question. Statuses are ephemeral (not persisted to the DB yet — that's a follow-up); they carry through this `/ritual build` session only:
|
|
14
|
-
|
|
15
|
-
| Status | Meaning |
|
|
16
|
-
|---|---|
|
|
17
|
-
| **`picked`** | User selected for active investigation (passed to `start_agentic_run`) |
|
|
18
|
-
| **`deferred`** | Deliberate phase-2 candidate; surfaces in build brief's "Phase Candidates" section. NOT context debt. |
|
|
19
|
-
| **`dropped`** | Removed from scope; problem statement gets narrowed to exclude this concern. |
|
|
20
|
-
| **`unreviewed`** | Default state for every surfaced question until the user classifies it. Counts toward debt if the user proceeds to Step 8 without resolving. |
|
|
21
|
-
|
|
22
|
-
`picked` is set automatically by the per-matter accept calls in 7.4. The other three are set by the Step 7.4.5 branches below.
|
|
23
|
-
|
|
24
|
-
###### Conditional trigger
|
|
25
|
-
|
|
26
|
-
Step 7.4.5 fires **only** when at least one of these holds — otherwise proceed silently to 7.5:
|
|
27
|
-
|
|
28
|
-
- **Pick-rate < 40%** (picked / total_surfaced)
|
|
29
|
-
- **Matter coverage ≤ 50%** (matters with ≥ 1 pick / total matters)
|
|
30
|
-
- **Pick-rate = 100%** (no-discrimination signal — see "no-discrimination case" below)
|
|
31
|
-
- **Concentration heuristic**: a single matter holds ≥ 60% of the picks while the problem statement spans multiple distinct concerns
|
|
32
|
-
|
|
33
|
-
If none hold, the user's scope intent is already obvious; don't add a check. Continue to Step 7.5.
|
|
34
|
-
|
|
35
|
-
###### Signal mapping
|
|
36
|
-
|
|
37
|
-
Before surfacing the prompt, the agent maps which problem-statement concerns are covered by the picks. Concerns are derived from the problem statement's noun-phrases (loose keyword-match against matter names is sufficient for MVP; LLM-rated mapping is a follow-up). For each unpicked matter, identify which problem-statement concern(s) it represents.
|
|
38
|
-
|
|
39
|
-
Output the analysis in plain language — three paragraphs (data → qualitative pattern → gap statement). Em-dash separating stats reads better than parenthetical. Example with real numbers (from the django-oscar GDPR exploration testing):
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
You picked 8 of 73 questions across 4 of 8 matters — an 11% pick-rate
|
|
43
|
-
with 50% matter coverage.
|
|
44
|
-
|
|
45
|
-
Your picks concentrate on the structural foundation: what the data is,
|
|
46
|
-
where it lives, immutability, and retention categories.
|
|
47
|
-
|
|
48
|
-
Your problem statement also mentions erasure mechanics, scheduled cleanup
|
|
49
|
-
jobs, DSAR APIs, and audit observability. Those areas are currently
|
|
50
|
-
unpicked.
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
The **dominant theme phrase** ("structural foundation: what the data is, where it lives, immutability, and retention categories" in the example) is computed once here and reused in Option 1's prompt below — that keeps the user's decision concrete instead of abstract.
|
|
54
|
-
|
|
55
|
-
###### The 4-option prompt (plain language only — no score previews)
|
|
56
|
-
|
|
57
|
-
Reuse the dominant-theme phrase from the analysis paragraph in Option 1 so the user reads the *narrowed scope* in product terms before deciding, not after.
|
|
58
|
-
|
|
59
|
-
```
|
|
60
|
-
How should I treat the unpicked areas?
|
|
61
|
-
|
|
62
|
-
1. Out of scope — tighten the problem statement around {dominant theme
|
|
63
|
-
from analysis paragraph: e.g. "data structure, storage, immutability,
|
|
64
|
-
and retention categories"}.
|
|
65
|
-
Unpicked concerns are dropped from the current HMW.
|
|
66
|
-
|
|
67
|
-
2. Later phase — keep the broad scope, but mark unpicked matters as
|
|
68
|
-
phase-2 candidates surfaced in the build brief.
|
|
69
|
-
Use this when the unpicked work depends on the picked foundation
|
|
70
|
-
being settled first.
|
|
71
|
-
|
|
72
|
-
3. Open questions — keep the broad scope and treat unpicked areas as
|
|
73
|
-
context debt to revisit.
|
|
74
|
-
|
|
75
|
-
4. Pick more — return to Step 7.3 and add picks before continuing.
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**Copy notes:**
|
|
79
|
-
- "the current HMW" (not "the HMW") — Branch 1 is present-cycle, not permanent. Reduces commitment-anxiety.
|
|
80
|
-
- "treat unpicked areas as context debt" (not "Unpicked counts as context debt") — grammatical, less terse.
|
|
81
|
-
- Option 2's "Use this when..." stays as a separate declarative sentence — less leading than a parenthetical, but still teaches the right sequencing intuition.
|
|
82
|
-
- Option 4 uses "return to" not "loop back to" — cleaner agent voice.
|
|
83
|
-
|
|
84
|
-
###### Per-branch handlers
|
|
85
|
-
|
|
86
|
-
**Branch 1 — Out of scope (tighten):**
|
|
87
|
-
1. Mark all unpicked questions across all matters as `dropped`.
|
|
88
|
-
2. Call `mcp__ritual__refine_problem_statement` with `change_prompt`: *"Narrow the scope to focus only on {comma-joined matter names of picked matters}. Drop concerns related to {comma-joined names of dropped matters}."*
|
|
89
|
-
3. Emit post-choice pulse — **reuse the same dominant-theme phrase** that appeared in the analysis paragraph + Option 1's prompt, so the user sees their choice acknowledged in the exact words they read:
|
|
90
|
-
```
|
|
91
|
-
✓ Tightened the problem statement around {dominant theme — same phrase as analysis paragraph + Option 1 prompt}.
|
|
92
|
-
Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +{delta}% (feature clarity ↑ from narrower scope)
|
|
93
|
-
```
|
|
94
|
-
Concrete example matching the django-oscar GDPR exploration: *"✓ Tightened the problem statement around data structure, storage, immutability, and retention categories."* — names what survived, not abstract *"the structural picks"*.
|
|
95
|
-
|
|
96
|
-
**Branch 2 — Later phase (defer):**
|
|
97
|
-
1. Mark all unpicked questions across all matters as `deferred`.
|
|
98
|
-
2. No problem statement change (broad scope preserved).
|
|
99
|
-
3. Emit post-choice pulse — **note the second-field label is `deferred`, not `debt`**:
|
|
100
|
-
```
|
|
101
|
-
✓ {N} unpicked questions marked as phase-2 candidates.
|
|
102
|
-
Pulse: Reasoning Readiness {readiness}% · Phase-later {deferred}% · +{delta}% (decision resolution ↑ from deliberate deferral)
|
|
103
|
-
```
|
|
104
|
-
The `deferred` label (instead of `debt`) is load-bearing — deliberate sequencing is NOT a liability, and the pulse line should reflect that. Same number, different character.
|
|
105
|
-
4. At Step 10c (build brief generation), the deferred matters MUST appear in the brief's *"Phase Candidates / Deferrable Items"* section. The agent appends the `deferred[]` set to the `generate_build_brief` `recon_context` payload as supplementary "explicit phase-2 candidates set by the user during discovery." The main `recon_context` payload remains the `codebase_context_packet`.
|
|
106
|
-
|
|
107
|
-
**Branch 3 — Open questions (debt):**
|
|
108
|
-
1. Mark all unpicked questions as `unreviewed` (their default state — no change).
|
|
109
|
-
2. No problem statement change.
|
|
110
|
-
3. Emit post-choice pulse — uses the `debt` label:
|
|
111
|
-
```
|
|
112
|
-
✓ {N} unpicked questions marked as context debt.
|
|
113
|
-
Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +0% (open questions remain unresolved)
|
|
114
|
-
```
|
|
115
|
-
Avoid words like *"status quo"* — phrase it as a state, not a non-event.
|
|
116
|
-
4. The next `/ritual context-pulse` will surface the unresolved questions as top debt sources.
|
|
117
|
-
|
|
118
|
-
**Branch 4 — Pick more (loop):**
|
|
119
|
-
1. No status change.
|
|
120
|
-
2. No pulse.
|
|
121
|
-
3. Surface the unpicked matters in a numbered list grouped by matter:
|
|
122
|
-
```
|
|
123
|
-
Returning to question picking. Unpicked matters and questions:
|
|
124
|
-
|
|
125
|
-
M5 — Erasure Anonymization Contract (10 questions)
|
|
126
|
-
M6 — Scheduled Cleanup Idempotency (8 questions)
|
|
127
|
-
M7 — DSAR Attribution Interfaces (9 questions)
|
|
128
|
-
M8 — Compliance Audit Observability (8 questions)
|
|
129
|
-
|
|
130
|
-
Pick any subset. Same per-matter accept flow as Step 7.4.
|
|
131
|
-
```
|
|
132
|
-
4. After new picks land, re-evaluate the trigger conditions. If still met, fire 7.4.5 again. Otherwise proceed to 7.5.
|
|
133
|
-
|
|
134
|
-
###### The no-discrimination case (100% pick-rate)
|
|
135
|
-
|
|
136
|
-
If trigger fired because pick-rate = 100% (user picked every question), the prompt shape is gentler — there's no "unpicked areas" to classify. Instead:
|
|
137
|
-
|
|
138
|
-
```
|
|
139
|
-
You picked everything (73/73 questions).
|
|
140
|
-
|
|
141
|
-
That may mean every question is genuinely relevant — the breadth is real.
|
|
142
|
-
Or it may mean we haven't narrowed the investigation yet. Pick one:
|
|
143
|
-
|
|
144
|
-
1. Proceed broadly — run all questions through the agentic pipeline. The
|
|
145
|
-
build brief will be wide; recommendations cover everything.
|
|
146
|
-
|
|
147
|
-
2. Sharper first pass — let me suggest 5-10 highest-leverage questions
|
|
148
|
-
that would give you the most signal per LLM call. The rest become
|
|
149
|
-
phase-2 candidates.
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
If user picks (1): proceed silently to Step 7.5. No pulse change.
|
|
153
|
-
If user picks (2): agent ranks the 73 questions by leverage (LLM call OR heuristic: questions earlier in each matter tend to be foundational), surfaces the top 5-10, user re-confirms picks, others become `deferred`. Fall back to Branch 2's behavior.
|
|
154
|
-
|
|
155
|
-
###### Two-score model in the pulse (CP3 update)
|
|
156
|
-
|
|
157
|
-
Once Step 7.4.5 has run, the `/ritual context-pulse` Step CP3 formula reads from the typed-status counts:
|
|
158
|
-
|
|
159
|
-
- **Decision Resolution (current scope):** `picked / (picked + unreviewed)`. Excludes `deferred` + `dropped`. Reaches near-100% if the user classified everything (picked, deferred, or dropped) — judgment rewarded.
|
|
160
|
-
- **Total-problem Coverage:** `(picked + deferred + dropped) / total`. Shows how much of the original surfaced space has been *classified at all*, regardless of how. Surfaces in the full pulse as an annotation; `unreviewed` count is the implicit debt.
|
|
161
|
-
|
|
162
|
-
Compact pulse continues to lead with the single readiness · {debt|deferred} · delta line per the per-branch templates above. Full pulse adds the breakdown:
|
|
163
|
-
|
|
164
|
-
```
|
|
165
|
-
Reasoning readiness: 72%
|
|
166
|
-
Context debt: 12% (4 questions unreviewed)
|
|
167
|
-
Context deferred: 16% (12 questions phase-2 candidates)
|
|
168
|
-
Context surface: Recommendation-ready
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
When `Context deferred` is zero, omit that line (CLI Tenet #6 — silence on no-data).
|
|
172
|
-
|
|
173
|
-
###### After Step 7.4.5 completes
|
|
174
|
-
|
|
175
|
-
Continue to Step 7.5 (anti-goals capture) per the existing flow.
|
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
# Discovery classification reference
|
|
2
|
-
|
|
3
|
-
Loaded only when `/ritual build` question picking triggers scope classification.
|
|
4
|
-
|
|
5
|
-
##### 7.4.5 — Scope Classification Check (conditional)
|
|
6
|
-
|
|
7
|
-
When the user picks discovery questions, the gap between **what the problem statement asks about** and **what the user actually chose to investigate** is the agent's first concrete read on whether the scope is genuinely narrow, deliberately sequenced, or under-engaged. This step makes that gap visible — but ONLY when the signal warrants it.
|
|
8
|
-
|
|
9
|
-
**Design principle (locked):** *Don't make the user optimize the score. Let the score explain what just happened.* The menu asks a plain product question; the pulse confirms the consequence afterward. Never preview deltas inside the choice menu.
|
|
10
|
-
|
|
11
|
-
###### Per-question typed status
|
|
12
|
-
|
|
13
|
-
Once Step 7.4 lands, the agent tracks an in-session status for every surfaced question. Statuses are ephemeral (not persisted to the DB yet — that's a follow-up); they carry through this `/ritual build` session only:
|
|
14
|
-
|
|
15
|
-
| Status | Meaning |
|
|
16
|
-
|---|---|
|
|
17
|
-
| **`picked`** | User selected for active investigation (passed to `start_agentic_run`) |
|
|
18
|
-
| **`deferred`** | Deliberate phase-2 candidate; surfaces in build brief's "Phase Candidates" section. NOT context debt. |
|
|
19
|
-
| **`dropped`** | Removed from scope; problem statement gets narrowed to exclude this concern. |
|
|
20
|
-
| **`unreviewed`** | Default state for every surfaced question until the user classifies it. Counts toward debt if the user proceeds to Step 8 without resolving. |
|
|
21
|
-
|
|
22
|
-
`picked` is set automatically by the per-matter accept calls in 7.4. The other three are set by the Step 7.4.5 branches below.
|
|
23
|
-
|
|
24
|
-
###### Conditional trigger
|
|
25
|
-
|
|
26
|
-
Step 7.4.5 fires **only** when at least one of these holds — otherwise proceed silently to 7.5:
|
|
27
|
-
|
|
28
|
-
- **Pick-rate < 40%** (picked / total_surfaced)
|
|
29
|
-
- **Matter coverage ≤ 50%** (matters with ≥ 1 pick / total matters)
|
|
30
|
-
- **Pick-rate = 100%** (no-discrimination signal — see "no-discrimination case" below)
|
|
31
|
-
- **Concentration heuristic**: a single matter holds ≥ 60% of the picks while the problem statement spans multiple distinct concerns
|
|
32
|
-
|
|
33
|
-
If none hold, the user's scope intent is already obvious; don't add a check. Continue to Step 7.5.
|
|
34
|
-
|
|
35
|
-
###### Signal mapping
|
|
36
|
-
|
|
37
|
-
Before surfacing the prompt, the agent maps which problem-statement concerns are covered by the picks. Concerns are derived from the problem statement's noun-phrases (loose keyword-match against matter names is sufficient for MVP; LLM-rated mapping is a follow-up). For each unpicked matter, identify which problem-statement concern(s) it represents.
|
|
38
|
-
|
|
39
|
-
Output the analysis in plain language — three paragraphs (data → qualitative pattern → gap statement). Em-dash separating stats reads better than parenthetical. Example with real numbers (from the django-oscar GDPR exploration testing):
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
You picked 8 of 73 questions across 4 of 8 matters — an 11% pick-rate
|
|
43
|
-
with 50% matter coverage.
|
|
44
|
-
|
|
45
|
-
Your picks concentrate on the structural foundation: what the data is,
|
|
46
|
-
where it lives, immutability, and retention categories.
|
|
47
|
-
|
|
48
|
-
Your problem statement also mentions erasure mechanics, scheduled cleanup
|
|
49
|
-
jobs, DSAR APIs, and audit observability. Those areas are currently
|
|
50
|
-
unpicked.
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
The **dominant theme phrase** ("structural foundation: what the data is, where it lives, immutability, and retention categories" in the example) is computed once here and reused in Option 1's prompt below — that keeps the user's decision concrete instead of abstract.
|
|
54
|
-
|
|
55
|
-
###### The 4-option prompt (plain language only — no score previews)
|
|
56
|
-
|
|
57
|
-
Reuse the dominant-theme phrase from the analysis paragraph in Option 1 so the user reads the *narrowed scope* in product terms before deciding, not after.
|
|
58
|
-
|
|
59
|
-
```
|
|
60
|
-
How should I treat the unpicked areas?
|
|
61
|
-
|
|
62
|
-
1. Out of scope — tighten the problem statement around {dominant theme
|
|
63
|
-
from analysis paragraph: e.g. "data structure, storage, immutability,
|
|
64
|
-
and retention categories"}.
|
|
65
|
-
Unpicked concerns are dropped from the current HMW.
|
|
66
|
-
|
|
67
|
-
2. Later phase — keep the broad scope, but mark unpicked matters as
|
|
68
|
-
phase-2 candidates surfaced in the build brief.
|
|
69
|
-
Use this when the unpicked work depends on the picked foundation
|
|
70
|
-
being settled first.
|
|
71
|
-
|
|
72
|
-
3. Open questions — keep the broad scope and treat unpicked areas as
|
|
73
|
-
context debt to revisit.
|
|
74
|
-
|
|
75
|
-
4. Pick more — return to Step 7.3 and add picks before continuing.
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**Copy notes:**
|
|
79
|
-
- "the current HMW" (not "the HMW") — Branch 1 is present-cycle, not permanent. Reduces commitment-anxiety.
|
|
80
|
-
- "treat unpicked areas as context debt" (not "Unpicked counts as context debt") — grammatical, less terse.
|
|
81
|
-
- Option 2's "Use this when..." stays as a separate declarative sentence — less leading than a parenthetical, but still teaches the right sequencing intuition.
|
|
82
|
-
- Option 4 uses "return to" not "loop back to" — cleaner agent voice.
|
|
83
|
-
|
|
84
|
-
###### Per-branch handlers
|
|
85
|
-
|
|
86
|
-
**Branch 1 — Out of scope (tighten):**
|
|
87
|
-
1. Mark all unpicked questions across all matters as `dropped`.
|
|
88
|
-
2. Call `mcp__ritual__refine_problem_statement` with `change_prompt`: *"Narrow the scope to focus only on {comma-joined matter names of picked matters}. Drop concerns related to {comma-joined names of dropped matters}."*
|
|
89
|
-
3. Emit post-choice pulse — **reuse the same dominant-theme phrase** that appeared in the analysis paragraph + Option 1's prompt, so the user sees their choice acknowledged in the exact words they read:
|
|
90
|
-
```
|
|
91
|
-
✓ Tightened the problem statement around {dominant theme — same phrase as analysis paragraph + Option 1 prompt}.
|
|
92
|
-
Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +{delta}% (feature clarity ↑ from narrower scope)
|
|
93
|
-
```
|
|
94
|
-
Concrete example matching the django-oscar GDPR exploration: *"✓ Tightened the problem statement around data structure, storage, immutability, and retention categories."* — names what survived, not abstract *"the structural picks"*.
|
|
95
|
-
|
|
96
|
-
**Branch 2 — Later phase (defer):**
|
|
97
|
-
1. Mark all unpicked questions across all matters as `deferred`.
|
|
98
|
-
2. No problem statement change (broad scope preserved).
|
|
99
|
-
3. Emit post-choice pulse — **note the second-field label is `deferred`, not `debt`**:
|
|
100
|
-
```
|
|
101
|
-
✓ {N} unpicked questions marked as phase-2 candidates.
|
|
102
|
-
Pulse: Reasoning Readiness {readiness}% · Phase-later {deferred}% · +{delta}% (decision resolution ↑ from deliberate deferral)
|
|
103
|
-
```
|
|
104
|
-
The `deferred` label (instead of `debt`) is load-bearing — deliberate sequencing is NOT a liability, and the pulse line should reflect that. Same number, different character.
|
|
105
|
-
4. At Step 10c (build brief generation), the deferred matters MUST appear in the brief's *"Phase Candidates / Deferrable Items"* section. The agent appends the `deferred[]` set to the `generate_build_brief` `recon_context` payload as supplementary "explicit phase-2 candidates set by the user during discovery." The main `recon_context` payload remains the `codebase_context_packet`.
|
|
106
|
-
|
|
107
|
-
**Branch 3 — Open questions (debt):**
|
|
108
|
-
1. Mark all unpicked questions as `unreviewed` (their default state — no change).
|
|
109
|
-
2. No problem statement change.
|
|
110
|
-
3. Emit post-choice pulse — uses the `debt` label:
|
|
111
|
-
```
|
|
112
|
-
✓ {N} unpicked questions marked as context debt.
|
|
113
|
-
Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +0% (open questions remain unresolved)
|
|
114
|
-
```
|
|
115
|
-
Avoid words like *"status quo"* — phrase it as a state, not a non-event.
|
|
116
|
-
4. The next `/ritual context-pulse` will surface the unresolved questions as top debt sources.
|
|
117
|
-
|
|
118
|
-
**Branch 4 — Pick more (loop):**
|
|
119
|
-
1. No status change.
|
|
120
|
-
2. No pulse.
|
|
121
|
-
3. Surface the unpicked matters in a numbered list grouped by matter:
|
|
122
|
-
```
|
|
123
|
-
Returning to question picking. Unpicked matters and questions:
|
|
124
|
-
|
|
125
|
-
M5 — Erasure Anonymization Contract (10 questions)
|
|
126
|
-
M6 — Scheduled Cleanup Idempotency (8 questions)
|
|
127
|
-
M7 — DSAR Attribution Interfaces (9 questions)
|
|
128
|
-
M8 — Compliance Audit Observability (8 questions)
|
|
129
|
-
|
|
130
|
-
Pick any subset. Same per-matter accept flow as Step 7.4.
|
|
131
|
-
```
|
|
132
|
-
4. After new picks land, re-evaluate the trigger conditions. If still met, fire 7.4.5 again. Otherwise proceed to 7.5.
|
|
133
|
-
|
|
134
|
-
###### The no-discrimination case (100% pick-rate)
|
|
135
|
-
|
|
136
|
-
If trigger fired because pick-rate = 100% (user picked every question), the prompt shape is gentler — there's no "unpicked areas" to classify. Instead:
|
|
137
|
-
|
|
138
|
-
```
|
|
139
|
-
You picked everything (73/73 questions).
|
|
140
|
-
|
|
141
|
-
That may mean every question is genuinely relevant — the breadth is real.
|
|
142
|
-
Or it may mean we haven't narrowed the investigation yet. Pick one:
|
|
143
|
-
|
|
144
|
-
1. Proceed broadly — run all questions through the agentic pipeline. The
|
|
145
|
-
build brief will be wide; recommendations cover everything.
|
|
146
|
-
|
|
147
|
-
2. Sharper first pass — let me suggest 5-10 highest-leverage questions
|
|
148
|
-
that would give you the most signal per LLM call. The rest become
|
|
149
|
-
phase-2 candidates.
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
If user picks (1): proceed silently to Step 7.5. No pulse change.
|
|
153
|
-
If user picks (2): agent ranks the 73 questions by leverage (LLM call OR heuristic: questions earlier in each matter tend to be foundational), surfaces the top 5-10, user re-confirms picks, others become `deferred`. Fall back to Branch 2's behavior.
|
|
154
|
-
|
|
155
|
-
###### Two-score model in the pulse (CP3 update)
|
|
156
|
-
|
|
157
|
-
Once Step 7.4.5 has run, the `/ritual context-pulse` Step CP3 formula reads from the typed-status counts:
|
|
158
|
-
|
|
159
|
-
- **Decision Resolution (current scope):** `picked / (picked + unreviewed)`. Excludes `deferred` + `dropped`. Reaches near-100% if the user classified everything (picked, deferred, or dropped) — judgment rewarded.
|
|
160
|
-
- **Total-problem Coverage:** `(picked + deferred + dropped) / total`. Shows how much of the original surfaced space has been *classified at all*, regardless of how. Surfaces in the full pulse as an annotation; `unreviewed` count is the implicit debt.
|
|
161
|
-
|
|
162
|
-
Compact pulse continues to lead with the single readiness · {debt|deferred} · delta line per the per-branch templates above. Full pulse adds the breakdown:
|
|
163
|
-
|
|
164
|
-
```
|
|
165
|
-
Reasoning readiness: 72%
|
|
166
|
-
Context debt: 12% (4 questions unreviewed)
|
|
167
|
-
Context deferred: 16% (12 questions phase-2 candidates)
|
|
168
|
-
Context surface: Recommendation-ready
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
When `Context deferred` is zero, omit that line (CLI Tenet #6 — silence on no-data).
|
|
172
|
-
|
|
173
|
-
###### After Step 7.4.5 completes
|
|
174
|
-
|
|
175
|
-
Continue to Step 7.5 (anti-goals capture) per the existing flow.
|