diff --git a/README.md b/README.md index 9c3f979..9cc022c 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,8 @@ After installation, the package registers one tool: `ask_user`. That is enough for the agent to gain this clarification capability. The extension already injects prompt guidance that encourages the agent to call `ask_user` when requirements are ambiguous or user preference matters, instead of guessing. +This package also includes an optional skill profile at `skills/ask-user/SKILL.md` (`ask-user-decision-gate`) for stricter decision-gate behavior in high-stakes or ambiguous boundaries. + You can still add your own agent instruction if you want to further reinforce when and how the tool should be used. Use `type: "preview"` only when every option includes `preview` text for a dedicated preview pane. Descriptions alone are not enough. diff --git a/skills/ask-user/SKILL.md b/skills/ask-user/SKILL.md new file mode 100644 index 0000000..9536925 --- /dev/null +++ b/skills/ask-user/SKILL.md @@ -0,0 +1,83 @@ +--- +name: ask-user-decision-gate +description: "Use ask_user as a decision gate before high-stakes or ambiguous implementation choices." +metadata: + short-description: Decision gate for ambiguity and high-stakes choices +--- + +# Ask User decision gate + +Use this skill to force explicit user alignment before consequential decisions. + +This skill is for decision control, not general chat. + +## Trigger + +Classify the next step as one of: + +- `high_stakes` +- `ambiguous` +- `both` +- `clear` + +Use `ask_user` when the next step is ambiguous, preference-sensitive, or high-stakes and the user has not already made the decision explicitly. + +### Treat as `high_stakes` when the next step changes: + +- architecture, schema, API contract, deployment, or security posture +- production-facing behavior in a costly-to-undo way +- large refactors, migrations, or destructive edits + +### Treat as `ambiguous` when: + +- requirements or success criteria are missing/conflicting +- multiple valid options exist and the trade-off is preference-sensitive +- you would otherwise make a material assumption + +## Handshake (required) + +1. Gather evidence first from code/docs/tools. +2. Summarize neutral context (current state, constraints, trade-offs, recommendation). +3. Ask one focused `ask_user` decision question. +4. Restate the user decision and proceed explicitly with it. +5. Re-open only for materially new ambiguity. + +## Question budget and escalation + +- Max 1 `ask_user` call per decision boundary in normal cases. +- Max 2 calls for the same boundary if first answer is unclear/cancelled. +- Never re-ask the same trade-off without new evidence. + +Attempt 2 (only if needed) must be narrower and include: + +- `Proceed with recommended option` +- `Choose another option` +- `Stop for now` + +After attempt 2: + +- for `high_stakes` or `both`: stop as blocked until explicit decision +- for `ambiguous` only: if user delegates ("your call"), proceed with the most reversible default and state assumptions + +## ask_user payload quality + +- Ask one concrete decision at a time. +- Prefer 2-4 clear options (single-select by default). +- Use `multi` only when selections are truly independent. +- Keep option labels short and outcome-oriented. +- Include trade-off descriptions when non-obvious. +- Prefer non-`preview` questions when a free-form answer may be useful, since those include an internal `Type your own` option. + +## Guardrails + +- Do not ask before reading available context. +- Do not use for trivial formatting/style micro-decisions. +- Do not continue implementation after unclear high-stakes answers. + +## Conflict rule + +If this skill conflicts with implementation behavior or tests, the project contract wins: + +1. `docs/contract.md` +2. `tests/*.test.ts` +3. this skill