From 48984b23985df2c87c61f9a65a0b798b0890e64f Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Fri, 8 May 2026 02:20:38 -0700 Subject: [PATCH] agents|feat: Make recommendation-gradient the interactive default Promotes the recommendation-gradient format from a per-skill reference to a universal interactive convention. The directive now lives in the shared AGENTS.md and applies whenever an agent presents 2+ numbered options to the user, regardless of which skill (if any) is active. Adds the directive to `packages/agents/content/guidance/shared/AGENTS.md` under the "Prompt formatting" section, and removes the now-redundant references from `collaboration/SKILL.md` and `design-and-plan/SKILL.md`. Switches the pro/con indent character in `_data/recommendation-gradient.md` from 3 ASCII spaces to 3 NBSP characters (U+00A0). Visible characters survive the whitespace normalization that was causing agents to flatten the indent in rendered output. Adds a `Q1`/`Q2` question-identifier convention so users can reference answers unambiguously when a single response contains multiple option-style questions. --- .../agents/content/guidance/shared/AGENTS.md | 1 + .../skills/_data/recommendation-gradient.md | 40 +++++++++++++++---- .../content/skills/collaboration/SKILL.md | 4 -- .../content/skills/design-and-plan/SKILL.md | 1 - 4 files changed, 33 insertions(+), 13 deletions(-) diff --git a/packages/agents/content/guidance/shared/AGENTS.md b/packages/agents/content/guidance/shared/AGENTS.md index 5d7327f5..72a7611f 100644 --- a/packages/agents/content/guidance/shared/AGENTS.md +++ b/packages/agents/content/guidance/shared/AGENTS.md @@ -39,6 +39,7 @@ When prompting the user for input, use visual markers to make prompts more notic - **Any yes/no question** (approval, decisions, confirmations): End with `πŸ‘πŸΌπŸ‘ŽπŸΌ`. - **All other questions** (open-ended, clarifications): End with `πŸ€”` +- **Numbered options (2+ choices)**: Follow the recommendation-gradient convention β€” mark each option β– β– β– /β– β– β–‘/β– β–‘β–‘/β–‘β–‘β–‘ and list `βž•` pros and `βž–` cons. Skip the gradient for yes/no questions and next-steps menus. When a response contains 2+ option-style questions, prefix each with `Q1`, `Q2`, etc. Full spec: `_data/recommendation-gradient.md` in the agents skills tree. Examples: diff --git a/packages/agents/content/skills/_data/recommendation-gradient.md b/packages/agents/content/skills/_data/recommendation-gradient.md index 850db1fd..186e1fd8 100644 --- a/packages/agents/content/skills/_data/recommendation-gradient.md +++ b/packages/agents/content/skills/_data/recommendation-gradient.md @@ -21,28 +21,52 @@ Rank options on correctness β€” behavior, API quality, architectural soundness, ## Format -Marker, then option title and colon. Each pro (`βž•`) and con (`βž–`) goes on its own line, indented by 3 spaces. Apply this even when an option has only one pro or con. Lead with the strongest argument. Use semicolons between items and a period on the last. +Marker, then option title and colon. Each pro (`βž•`) and con (`βž–`) goes on its own line, prefixed with 3 non-breaking-space characters (NBSP, U+00A0) for visual indent β€” regular ASCII spaces are commonly stripped or normalized in model output, so a visible character is needed to make the indent reliable. Apply this even when an option has only one pro or con. Lead with the strongest argument. Use semicolons between items and a period on the last. + +## Question identifiers + +When a single response contains 2+ option-style questions, prefix each question with `Q1`, `Q2`, etc., so the user can reference answers unambiguously (e.g., "Q1: option 2"). For a single option-style question, omit the identifier. ## Examples +Single question with markers: + ``` Want me to: 1. β– β–‘β–‘ Use a single config file: - βž• minimal surface area; - βž– couples concerns. +Β Β Β βž• minimal surface area; +Β Β Β βž– couples concerns. 2. β– β– β–  Split into two configs: - βž• separates lifecycle and runtime concerns; - βž• matches existing repo pattern. +Β Β Β βž• separates lifecycle and runtime concerns; +Β Β Β βž• matches existing repo pattern. 3. β–‘β–‘β–‘ Use three configs: - βž– over-decomposed for current scope. +Β Β Β βž– over-decomposed for current scope. ``` +Single question without markers (pure taste call): + ``` Want me to: 1. Use camelCase: - βž• matches the host file's local style. +Β Β Β βž• matches the host file's local style. 2. Use kebab-case: - βž• matches the package's public API style. +Β Β Β βž• matches the package's public API style. +``` + +Multiple questions in one response (Q1/Q2 identifiers): + +``` +**Q1 β€” Naming convention?** +1. Use camelCase: +Β Β Β βž• matches the host file's local style. +2. Use kebab-case: +Β Β Β βž• matches the package's public API style. + +**Q2 β€” File location?** +1. β– β– β–‘ Co-locate with consumer: +Β Β Β βž• keeps related code close. +2. β– β–‘β–‘ Place in shared utility module: +Β Β Β βž• reusable across packages. ``` ## Don'ts diff --git a/packages/agents/content/skills/collaboration/SKILL.md b/packages/agents/content/skills/collaboration/SKILL.md index 8655ce0a..7376d72e 100644 --- a/packages/agents/content/skills/collaboration/SKILL.md +++ b/packages/agents/content/skills/collaboration/SKILL.md @@ -28,10 +28,6 @@ When you do ask, prefer forms the user can answer unambiguously: - **A clean yes/no question** (end with `πŸ‘πŸΌπŸ‘ŽπŸΌ`). - **A numbered options list.** Include a "some other approach (describe)" option if alternatives should stay open. -## Asking with a recommendation gradient - -When asking numbered clarifying questions with 2+ options, follow the [recommendation gradient](../_data/recommendation-gradient.md) format. - ## Efficient context usage When you deem appropriate, proactively dispatch subagents to perform tasks. Good examples: diff --git a/packages/agents/content/skills/design-and-plan/SKILL.md b/packages/agents/content/skills/design-and-plan/SKILL.md index be3f2ee2..04365d31 100644 --- a/packages/agents/content/skills/design-and-plan/SKILL.md +++ b/packages/agents/content/skills/design-and-plan/SKILL.md @@ -68,7 +68,6 @@ Invoke the `assess-ticket` skill with the resolved ticket source and mode `drift - Success criteria and edge cases - Prefer multiple choice when possible - Only one question per message - - When using numbered options, follow the [recommendation gradient](../_data/recommendation-gradient.md): mark each option with β– β– β–  / β– β– β–‘ / β– β–‘β–‘ / β–‘β–‘β–‘ and list `βž•` pros and `βž–` cons per the format defined there. **Important:** Do not use interactive prompt mechanisms (pop-ups, arrow-key selectors, structured choice tools) for multiple-choice questions. Ask the question as plain text in the message body, with options as a numbered list.