Merge pull request #105 from hua7450/improve-user-checkpoints

Improve user checkpoints with structured AskUserQuestion

Author: hua7450

changelog.d/improve-user-checkpoints.changed.md

@@ -0,0 +1 @@
+Improve user checkpoints with structured AskUserQuestion across commands

commands/backdate-program.md

@@ -366,11 +366,58 @@ subagent_type: "general-purpose", team_name: "{st}-{prog}-backdate", name: "cons
 
 ### Regulatory Checkpoint 1
 
-Read ONLY `/tmp/{st}-{prog}-impl-summary.md`. Present to user:
-- Number of files affected, date entries to add
-- Any Tier B/C items (require user confirmation before proceeding)
-- Source gaps or unresolved conflicts
-- **Stop here if `--research-only`**
+Read ONLY `/tmp/{st}-{prog}-impl-summary.md`. Present a brief overview:
+
+```
+## {STATE_FULL} {PROGRAM} — Research Complete
+
+**Parameters**: {N} files, {M} date entries to add
+**Earliest date**: {YYYY-MM-DD} → backdating to {TARGET_YEAR}
+**Source gaps**: {count, if any}
+```
+
+Then walk through decisions one at a time using `AskUserQuestion`:
+
+**Decision 1: Proceed with implementation?**
+
+```
+AskUserQuestion:
+  Question: "Proceed with backdating {N} parameter files?"
+  Options:
+    - "Yes, proceed" (default/recommended)
+    - "Show me more details first"
+    - "Stop here (research only)"
+```
+
+**Decision 2: Tier B/C items** (only if impl-summary lists any)
+
+For each Tier B/C item, ask separately:
+
+```
+AskUserQuestion:
+  Question: "{Description of Tier B/C item}"
+  Description: "{Brief context — e.g., 'New parameter needed for provision X, not in current implementation'}"
+  Options:
+    - "Include — implement this change" (recommended if Tier B)
+    - "Skip — defer to follow-up PR"
+    - "Need more info"
+```
+
+**Decision 3: Source gaps** (only if impl-summary lists any)
+
+```
+AskUserQuestion:
+  Question: "How to handle {N} source gap(s)?"
+  Description: |
+    {List each gap, e.g.:
+    - No PDF found for 2003-2007 period
+    - Two sources disagree on 2010 value}
+  Options:
+    - "Proceed — use best available data" (recommended)
+    - "Pause — let me find the missing sources"
+```
+
+**Stop here if `--research-only`.**
 
 ---
 
@@ -437,10 +484,58 @@ Write SHORT summary (max 15 lines) to /tmp/{st}-{prog}-phase2-summary.md."
 
 ### Regulatory Checkpoint 2
 
-Read ONLY `/tmp/{st}-{prog}-phase2-summary.md`. Present to user:
-- Broken URLs, generic refs, missing subsections count
-- Unused parameters, zero-sentinels, missing provisions count
-- **Formula fixes require user confirmation** before implementation
+Read ONLY `/tmp/{st}-{prog}-phase2-summary.md`. Present a brief overview:
+
+```
+## Audit Results
+
+**References**: {N} broken URLs, {M} generic refs, {P} missing subsections
+**Formulas**: {X} unused params, {Y} zero-sentinels, {Z} missing provisions
+```
+
+Then walk through decisions using `AskUserQuestion`:
+
+**Decision 1: Reference fixes**
+
+```
+AskUserQuestion:
+  Question: "Apply {N} reference fixes? (broken URLs, missing page numbers, generic citations)"
+  Options:
+    - "Yes, fix all" (default/recommended)
+    - "Show me the list first"
+    - "Skip reference fixes"
+```
+
+**Decision 2: Formula fixes** (only if audit found formula issues)
+
+Ask for each formula fix category separately:
+
+```
+AskUserQuestion:
+  Question: "Fix {X} unused parameters? (parameters exist but no formula reads them)"
+  Options:
+    - "Yes, wire them into formulas" (recommended)
+    - "Skip — defer to follow-up"
+    - "Show me which ones"
+```
+
+```
+AskUserQuestion:
+  Question: "Fix {Y} zero-sentinel anti-patterns? (value=0 used instead of explicit in_effect boolean)"
+  Options:
+    - "Yes, refactor to in_effect pattern" (recommended)
+    - "Skip — cosmetic, defer"
+```
+
+```
+AskUserQuestion:
+  Question: "Implement {Z} missing provisions? (regulations found but not yet coded)"
+  Description: "{Brief list of missing provisions}"
+  Options:
+    - "Yes, implement all"
+    - "Let me pick which ones"
+    - "Skip — defer to follow-up PR"
+```
 
 ---
 

commands/encode-policy-v2.md

@@ -171,37 +171,93 @@ After consolidator completes, read ONLY:
 
 ## Phase 2: Scope Review (USER CHECKPOINT)
 
-Present to user:
+This phase walks the user through scope decisions one at a time using `AskUserQuestion` with structured options. Do NOT dump all requirements at once.
+
+### Step 2A: Show Summary
+
+Display a brief overview (from scope-summary.md):
 
 ```
 ## {STATE} {PROGRAM} — Scope Review
 
 **Complexity**: {Simple/Complex} ({N} requirements)
 **Reference impl**: {path}
+```
 
+Then list requirements grouped by tag. Example:
+
+```
 ### Requirements Found ({N} total):
-REQ-001: [ELIGIBILITY] Income <= 261% FPL (entry) — OAR 461-155-0180
-REQ-002: [ELIGIBILITY] Income <= 300% FPL (transitional) — OAR 461-155-0180
-REQ-003: [RESOURCE] Assets <= $1M — OAR 461-160-0015
-REQ-004: [DEMOGRAPHIC] Child under 13 (under 19 if disabled) — OAR 461-120-0510
-REQ-005: [IMMIGRATION] Child must be US citizen or qualified immigrant — 8 USC 1612
-REQ-006: [BENEFIT] Co-payment 0%/2%/5%/7% by FPL tier — OAR 461-155-0150
-REQ-007: [BENEFIT] Co-payment capped at 7% of income (federal) — 45 CFR 98.45
-REQ-008: [EXEMPTION] RI Works families get $0 co-payment — DHS Policy Manual
-REQ-009: [NOT-MODELED] 20 hrs/week work activity requirement — OAR 461-135-0400
-...
 
-Implement all? Or exclude any? (e.g., "Skip REQ-009, REQ-010")
+**Eligibility** ({X})
+  REQ-001: Income <= 261% FPL (entry) — OAR 461-155-0180
+  REQ-002: Income <= 300% FPL (transitional) — OAR 461-155-0180
+
+**Benefit Calculation** ({X})
+  REQ-006: Co-payment 0%/2%/5%/7% by FPL tier — OAR 461-155-0150
+  REQ-007: Co-payment capped at 7% of income — 45 CFR 98.45
+
+**Not Modeled** ({X})
+  REQ-009: 20 hrs/week work activity requirement — OAR 461-135-0400
 ```
 
-Wait for user response via AskUserQuestion.
+### Step 2B: Key Decisions (One at a Time)
+
+For each key decision point identified in the scope summary, ask the user ONE question at a time using `AskUserQuestion`.
 
-User can say:
-- "All" — implement everything (except NOT-MODELED)
-- "Skip REQ-009, REQ-010" — orchestrator records exclusions
-- Any other guidance
+**Decision 1: Overall scope**
+
+```
+AskUserQuestion:
+  Question: "Implement all {N} simulatable requirements? ({M} NOT-MODELED items will be excluded automatically)"
+  Options:
+    - "Yes, implement all" (default/recommended)
+    - "Let me pick which to skip"
+```
 
-Write the decision to `/tmp/{PREFIX}-scope-decision.md`:
+If user picks "Let me pick which to skip", present each questionable requirement group:
+
+```
+AskUserQuestion:
+  Question: "Include {TAG} requirements?"
+  Description: |
+    REQ-XXX: {description}
+    REQ-YYY: {description}
+  Options:
+    - "Yes, include all" (default)
+    - "Skip these"
+    - "Let me pick individually"
+```
+
+**Decision 2+: Program-specific complexity decisions**
+
+If the scope summary identifies key decision points (e.g., provider rates, simplified vs full approach), ask each as a separate question:
+
+```
+AskUserQuestion:
+  Question: "{Decision description}"
+  Description: "{Brief context — e.g., 'Provider rates have ~240 rate cells. Implementing now adds complexity.'}"
+  Options:
+    - "{Option A}" (recommended if applicable)
+    - "{Option B}"
+    - "{Option C if needed}"
+```
+
+Examples of program-specific decisions:
+- "Provider rates have ~240 rate cells — implement now or defer?"
+  - "Defer to follow-up PR" (recommended)
+  - "Implement now"
+- "TANF approach — simplified or full?"
+  - "Simplified (eligibility + benefit amount)" (recommended)
+  - "Full (all components)"
+- "13 income types have no PE equivalent — how to handle?"
+  - "Map to closest existing variables" (recommended)
+  - "Create new variables for each"
+  - "Skip unmappable income types"
+
+### Step 2C: Write Scope Decision
+
+After all questions are answered, write the decision to `/tmp/{PREFIX}-scope-decision.md`:
 
 ```markdown
 ## Scope Decision for {STATE} {PROGRAM}
@@ -213,7 +269,11 @@ REQ-002: [ELIGIBILITY] Income <= 300% FPL (transitional)
 
 ### Excluded
 REQ-009: [NOT-MODELED] 20 hrs/week work activity — Reason: not simulatable
-REQ-010: [BENEFIT] Provider payment rates — Reason: user excluded
+REQ-010: [BENEFIT] Provider payment rates — Reason: user deferred
+
+### Key Decisions
+- Provider rates: deferred to follow-up PR
+- Income variable gaps: map to closest existing variables
 
 ### User Notes
 {any additional guidance from user}