Skip to content

Apply recommendation-gradient universally in interactive sessions #526

Description

@williamthorsen

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:

  1. 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.
  2. Multi-question responses give the user no way to reference questions unambiguously ("for option 2 of which question?").

Solution

  1. 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.
  2. Single-source the rule. Remove the gradient references from collaboration/SKILL.md and design-and-plan/SKILL.md.
  3. 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.
  4. 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

  • Shared AGENTS.md contains the recommendation-gradient directive
  • References removed from collaboration/SKILL.md and design-and-plan/SKILL.md
  • _data/recommendation-gradient.md format spec and examples use NBSP for indentation
  • _data/recommendation-gradient.md documents the Q1/Q2 question-ID convention

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:agents

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions