diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index da334444..e9239452 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -1384,7 +1384,7 @@ Once selected, commit fully. Do not silently drift. Present these mode options via AskUserQuestion using the preamble's AskUserQuestion Format section: include RECOMMENDATION. These options differ in kind (review posture), not coverage — do NOT emit `Completeness: N/10` per option. Include the one-line note from step 4 of the preamble format rule instead: `Note: options differ in kind, not coverage — no completeness score.` -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ## Review Sections (11 sections, after scope and mode are agreed) @@ -1414,7 +1414,7 @@ Evaluate and diagram: **SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information. Required ASCII diagram: full system architecture showing new components and their relationships to existing ones. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 2: Error & Rescue Map @@ -1444,7 +1444,7 @@ Rules for this section: * Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable. * For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see. * For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 3: Security & Threat Model @@ -1460,7 +1460,7 @@ Evaluate: * Audit logging. For sensitive operations: is there an audit trail? For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 4: Data Flow & Interaction Edge Cases @@ -1497,7 +1497,7 @@ For each node: what happens on each shadow path? Is it tested? | Queue backs up 2 hours | ? | ``` Flag any unhandled edge case as a gap. For each gap, specify the fix. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 5: Code Quality Review @@ -1510,7 +1510,7 @@ Evaluate: * Over-engineering check. Any new abstraction solving a problem that doesn't exist yet? * Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks? * Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 6: Test Review @@ -1551,7 +1551,7 @@ Flakiness risk: Flag any test depending on time, randomness, external services, Load/stress test requirements: For any new codepath called frequently or processing significant data. For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 7: Performance Review @@ -1563,7 +1563,7 @@ Evaluate: * Background job sizing. For every new job: worst-case payload, runtime, retry behavior? * Slow paths. Top 3 slowest new codepaths and estimated p99 latency. * Connection pool pressure. New DB connections, Redis connections, HTTP connections? -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 8: Observability & Debuggability Review @@ -1580,7 +1580,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.) -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 9: Deployment & Rollout Review @@ -1596,7 +1596,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.) -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 10: Long-Term Trajectory Review @@ -1612,7 +1612,7 @@ Evaluate: * What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory? * Platform potential. Does this create capabilities other features can leverage? * (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones? -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 11: Design & UX Review (skip if no UI scope detected) @@ -1635,7 +1635,7 @@ Evaluate: Required ASCII diagram: user flow showing screens/states and transitions. If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation." -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ## Outside Voice — Independent Plan Challenge (optional, recommended) @@ -1793,7 +1793,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for * For each option: effort, risk, and maintenance burden in one line. * **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference. * Label with issue NUMBER + option LETTER (e.g., "3A", "3B"). -* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask. ## Required Outputs diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 555cba02..9fb66a2c 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -376,7 +376,7 @@ Once selected, commit fully. Do not silently drift. Present these mode options via AskUserQuestion using the preamble's AskUserQuestion Format section: include RECOMMENDATION. These options differ in kind (review posture), not coverage — do NOT emit `Completeness: N/10` per option. Include the one-line note from step 4 of the preamble format rule instead: `Note: options differ in kind, not coverage — no completeness score.` -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ## Review Sections (11 sections, after scope and mode are agreed) @@ -406,7 +406,7 @@ Evaluate and diagram: **SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information. Required ASCII diagram: full system architecture showing new components and their relationships to existing ones. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 2: Error & Rescue Map @@ -436,7 +436,7 @@ Rules for this section: * Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable. * For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see. * For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 3: Security & Threat Model @@ -452,7 +452,7 @@ Evaluate: * Audit logging. For sensitive operations: is there an audit trail? For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 4: Data Flow & Interaction Edge Cases @@ -489,7 +489,7 @@ For each node: what happens on each shadow path? Is it tested? | Queue backs up 2 hours | ? | ``` Flag any unhandled edge case as a gap. For each gap, specify the fix. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 5: Code Quality Review @@ -502,7 +502,7 @@ Evaluate: * Over-engineering check. Any new abstraction solving a problem that doesn't exist yet? * Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks? * Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 6: Test Review @@ -543,7 +543,7 @@ Flakiness risk: Flag any test depending on time, randomness, external services, Load/stress test requirements: For any new codepath called frequently or processing significant data. For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 7: Performance Review @@ -555,7 +555,7 @@ Evaluate: * Background job sizing. For every new job: worst-case payload, runtime, retry behavior? * Slow paths. Top 3 slowest new codepaths and estimated p99 latency. * Connection pool pressure. New DB connections, Redis connections, HTTP connections? -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 8: Observability & Debuggability Review @@ -572,7 +572,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.) -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 9: Deployment & Rollout Review @@ -588,7 +588,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.) -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 10: Long-Term Trajectory Review @@ -604,7 +604,7 @@ Evaluate: * What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory? * Platform potential. Does this create capabilities other features can leverage? * (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones? -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** ### Section 11: Design & UX Review (skip if no UI scope detected) @@ -627,7 +627,7 @@ Evaluate: Required ASCII diagram: user flow showing screens/states and transitions. If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation." -**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds. **Reminder: Do NOT make any code changes. Review only.** {{CODEX_PLAN_REVIEW}} @@ -651,7 +651,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for * For each option: effort, risk, and maintenance burden in one line. * **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference. * Label with issue NUMBER + option LETTER (e.g., "3A", "3B"). -* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask. ## Required Outputs diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index b31d590c..d464b20a 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -1622,7 +1622,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for * Present 2-3 options. For each: effort to specify now, risk if deferred. * **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle. * Label with issue NUMBER + option LETTER (e.g., "3A", "3B"). -* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine design choice with meaningful tradeoffs. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the fix is genuinely trivial AND there are no meaningful design alternatives. When in doubt, ask. * **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience. ## Required Outputs diff --git a/plan-design-review/SKILL.md.tmpl b/plan-design-review/SKILL.md.tmpl index a4b40d2c..5c224d13 100644 --- a/plan-design-review/SKILL.md.tmpl +++ b/plan-design-review/SKILL.md.tmpl @@ -345,7 +345,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for * Present 2-3 options. For each: effort to specify now, risk if deferred. * **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle. * Label with issue NUMBER + option LETTER (e.g., "3A", "3B"). -* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine design choice with meaningful tradeoffs. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the fix is genuinely trivial AND there are no meaningful design alternatives. When in doubt, ask. * **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience. ## Required Outputs diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index cc422bbd..bf62fed1 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -1792,8 +1792,11 @@ DX reviews: * **Map to DX First Principles above.** One sentence connecting your recommendation to a specific principle (e.g., "This violates 'zero friction at T0' because [persona] needs 3 extra config steps before their first API call"). -* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an - obvious fix, state what you'll add and move on, don't waste a question. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, + moving on" and proceed. If it has findings, use AskUserQuestion for each — a + gap with an "obvious fix" is still a gap and still needs user approval before + any change lands in the plan. Only skip AskUserQuestion when the fix is + genuinely trivial AND there are no meaningful DX alternatives. When in doubt, ask. * Assume the user hasn't looked at this window in 20 minutes. Re-ground every question. ## Required Outputs diff --git a/plan-devex-review/SKILL.md.tmpl b/plan-devex-review/SKILL.md.tmpl index 9f1e7c2d..5b4c69a9 100644 --- a/plan-devex-review/SKILL.md.tmpl +++ b/plan-devex-review/SKILL.md.tmpl @@ -666,8 +666,11 @@ DX reviews: * **Map to DX First Principles above.** One sentence connecting your recommendation to a specific principle (e.g., "This violates 'zero friction at T0' because [persona] needs 3 extra config steps before their first API call"). -* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an - obvious fix, state what you'll add and move on, don't waste a question. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, + moving on" and proceed. If it has findings, use AskUserQuestion for each — a + gap with an "obvious fix" is still a gap and still needs user approval before + any change lands in the plan. Only skip AskUserQuestion when the fix is + genuinely trivial AND there are no meaningful DX alternatives. When in doubt, ask. * Assume the user hasn't looked at this window in 20 minutes. Re-ground every question. ## Required Outputs diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 59ff5e5e..387564b5 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -1407,7 +1407,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for * **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.). * Label with issue NUMBER + option LETTER (e.g., "3A", "3B"). * **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score. -* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask. ## Required outputs diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 711e354c..a16083ed 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -186,7 +186,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for * **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.). * Label with issue NUMBER + option LETTER (e.g., "3A", "3B"). * **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score. -* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs. +* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask. ## Required outputs