Problem
The recommendation-gradient format is referenced only from the collaboration and design-and-plan skills. Other skills that present options (e.g., refine-plan, plan-orchestrable-steps, brainstorming, assess-ticket) and ad-hoc option-asking outside any skill don't trigger it. Agents apply the format inconsistently, missing its productivity benefit.
Two related friction points surface in practice:
- The format specifies a 3-space indent for ➕/➖ continuation lines, but agents commonly flatten leading whitespace, so pros and cons appear unindented and visually merge with the option title.
- Multi-question responses give the user no way to reference questions unambiguously ("for option 2 of which question?").
Solution
- Promote the directive to top-level guidance. Add a short rule to the shared AGENTS.md (
packages/agents/content/guidance/shared/AGENTS.md) anchoring all interactive sessions: when presenting 2+ numbered options to the user, follow _data/recommendation-gradient.md.
- Single-source the rule. Remove the gradient references from
collaboration/SKILL.md and design-and-plan/SKILL.md.
- Switch indent to NBSP (U+00A0). Update
_data/recommendation-gradient.md's format spec and examples to use 3 NBSP characters instead of 3 ASCII spaces. Visible characters survive whitespace normalization in model output.
- Add question identifiers. When a response contains 2+ option-style questions, prefix each with
Q1, Q2, etc., so the user can reference them unambiguously.
Acceptance criteria
Problem
The recommendation-gradient format is referenced only from the
collaborationanddesign-and-planskills. Other skills that present options (e.g.,refine-plan,plan-orchestrable-steps,brainstorming,assess-ticket) and ad-hoc option-asking outside any skill don't trigger it. Agents apply the format inconsistently, missing its productivity benefit.Two related friction points surface in practice:
Solution
packages/agents/content/guidance/shared/AGENTS.md) anchoring all interactive sessions: when presenting 2+ numbered options to the user, follow_data/recommendation-gradient.md.collaboration/SKILL.mdanddesign-and-plan/SKILL.md._data/recommendation-gradient.md's format spec and examples to use 3 NBSP characters instead of 3 ASCII spaces. Visible characters survive whitespace normalization in model output.Q1,Q2, etc., so the user can reference them unambiguously.Acceptance criteria
collaboration/SKILL.mdanddesign-and-plan/SKILL.md_data/recommendation-gradient.mdformat spec and examples use NBSP for indentation_data/recommendation-gradient.mddocuments theQ1/Q2question-ID convention