Implement PAI user-choice Q&A contract (closes #148)#154
Merged
virtualian merged 1 commit intomainfrom Apr 24, 2026
Merged
Conversation
Introduce a PAI-level trigger-consistency layer over the existing AskUserQuestion usage. No renames, no wrappers, no new tools — only new prompt/doc machinery so the existing 13 call sites and hooks stay untouched. - Algorithm: ENUMERATE→OFFER sub-step at OBSERVE exit, after the assumption-verification gate, with commit-with-rationale and AskUserQuestion escape paths plus worked examples. - NATIVE format: new ❓ OPEN_CHOICES: field in CLAUDE.md and its template, with a pairing rule that forbids non-empty values without an accompanying AskUserQuestion call. - AISTEERINGRULES: "AskUserQuestion for choices" rewritten with six concrete triggers (OBSERVE ambiguity, capability substitution, commit-message approval, branch-naming, skill-routing, effort-level) and a worked example. - PROTOCOLS/qa-contract.md (new, 194 lines): normative Request/ Response schema, Carrier A (subagent return-value) and Carrier B (DA→user AskUserQuestion) mappings, nine invariants, non-CC harness stub note. Single source of truth referenced by callers. - THEDELEGATIONSYSTEM: new "User-choice bubbling" subsection formalising pending_user_choices[] with anti-pattern and correct code examples. - SKILLSYSTEM: one-line pack user-choice policy plus a concrete done-state for new packs. - reports/: subagent probe results for Architect, Engineer, and Plan — all three report AskUserQuestion as ABSENT, confirming the bubble protocol is mandatory across the specialised fleet. Runtime installation at ~/.pai/ intentionally untouched; edits target the shipped repo artefact at Releases/v4.0.3+/.
virtualian
added a commit
that referenced
this pull request
Apr 26, 2026
Plan file capturing the per-file selective merge approach used to apply PR #154 to the live runtime at ~/.pai/ + ~/.claude/ without a fresh install. Documents path mapping, three-way merge strategy per file class, drift-preservation criteria, and verification logic. Runtime application is complete; this commit lands the planning artefact only — the runtime files themselves live outside git.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AskUserQuestionusage — an Algorithm ENUMERATE→OFFER sub-step, a NATIVE❓ OPEN_CHOICES:output field, a rewrittenAISTEERINGRULES.md"AskUserQuestion for choices" rule with six concrete triggers, and a new normative protocol atPAI/PROTOCOLS/qa-contract.md.THEDELEGATIONSYSTEM.mdwith correct + anti-pattern code. Adds a pack user-choice policy toSKILLSYSTEM.mdwith a done-state for new packs.reports/20260421-issue-143-askuserquestion-pai-design.md(investigation landed in Add issue #143 report: AskUserQuestion PAI Q&A pattern design #149). Runtime probe ofArchitect,Engineer,Plansubagents confirmed all three reportAskUserQuestionas ABSENT — bubble protocol is the only workable path across the specialised fleet. Probe results inreports/20260422-issue-148-subagent-probes.md.Non-goals (per issue body)
AskUserQuestion, no new tool.AskUserQuestioncall sites, no runtime code edits.~/.pai/intentionally untouched; edits target the shipped repo artefact atReleases/v4.0.3+/.Design notes for review
OBSERVE EXIT GATE — EXTERNAL ASSUMPTION VERIFICATIONblock (not before), so the order is "verify assumptions → enumerate open choices → transition to THINK". Avoids gate collision..claude/CLAUDE.md(live) and.claude/CLAUDE.md.template(installer source). Diff of the two files post-edit shows only the pre-existing preamble/placeholder differences — no drift introduced.qa-contract.mdline budget: 194 lines (issue requested 150-250). Expanded from initial 180 after peer review and a scoped RedTeam pass surfaced three must-fixes and two silent-corruption risks (dedupe identity, label canonicalisation). Invariants grew from 6 to 9 to patch these.qa-contract.mdcarries schema blocks and code examples. This is a pragmatic reading of the standard's scope — operational PAI protocol files behave likeTHEDELEGATIONSYSTEM.md(which already uses code blocks), not like.claude/marr/standards/meta-prompts. Flagging here so reviewers can push back if the strict reading should apply.Test plan
PAI/PROTOCOLS/qa-contract.mdend-to-end; confirm schema, carriers, and invariants read cleanly as a standalone spec.❓ OPEN_CHOICES:field in a test session — confirm non-empty values render and that the pairedAskUserQuestionrule is observed.AskUserQuestionsplit behaves as described.pending_user_choices[]rather than attempting direct invocation.~/.pai/after a fresh install to confirm the newPROTOCOLS/directory propagates.Closes #148.