From 628224f01eec9fde6560af0e9eddc0231a80730a Mon Sep 17 00:00:00 2001
From: William Thorsen <william@thorsen.dev>
Date: Sat, 2 May 2026 04:09:53 -0700
Subject: [PATCH] agents|feat: List pros and cons one per line, indented 3
 spaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reformats the recommendation-gradient pros/cons spec from inline `➕ pro; ➖ con` to one item per line with a 3-space indent. Inline pros and cons separated by `;` were difficult to parse when option titles were long or when an option carried multiple items; option boundaries blurred and individual items ran together.

The new format applies even to single-item options, so the rule is uniform and predictable across every use.

Updates the canonical spec and both example blocks in `recommendation-gradient.md`. Reformats the convenience-led and correctness-led ranking examples in `design-priorities.md` to match. Removes the redundant inline format example from `design-and-plan/SKILL.md`, which now defers to the canonical spec via its existing link.
---
 .../content/skills/_data/design-priorities.md | 17 +++++++++++++----
 .../skills/_data/recommendation-gradient.md   | 19 +++++++++++++------
 .../content/skills/design-and-plan/SKILL.md   |  2 +-
 3 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/packages/agents/content/skills/_data/design-priorities.md b/packages/agents/content/skills/_data/design-priorities.md
index dd1c8292..bfbb565c 100644
--- a/packages/agents/content/skills/_data/design-priorities.md
+++ b/packages/agents/content/skills/_data/design-priorities.md
@@ -37,15 +37,24 @@ B. Extract a small dedicated module with a narrow interface and inject it.
 **Convenience-led ranking** (don't do this):
 
 ```
-1. ■■■ Extend the god-class: ➕ minimal diff; ➕ no new files; ➕ matches surrounding code.
-2. ■□□ Extract a module: ➖ more files; ➖ touches injection sites.
+1. ■■■ Extend the god-class:
+   ➕ minimal diff;
+   ➕ no new files;
+   ➕ matches surrounding code.
+2. ■□□ Extract a module:
+   ➖ more files;
+   ➖ touches injection sites.
 ```
 
 **Correctness-led ranking** (do this):
 
 ```
-1. ■■■ Extract a module: ➕ narrow interface; ➕ testable in isolation; ➕ untangles concerns the god-class already conflates.
-2. □□□ Extend the god-class: ➖ deepens an existing SRP violation; convenience gain is one-off, complexity cost compounds.
+1. ■■■ Extract a module:
+   ➕ narrow interface;
+   ➕ testable in isolation;
+   ➕ untangles concerns the god-class already conflates.
+2. □□□ Extend the god-class:
+   ➖ deepens an existing SRP violation; convenience gain is one-off, complexity cost compounds.
 ```
 
 The factual lists about each option are similar; the **ranking** flips because the criteria changed.
diff --git a/packages/agents/content/skills/_data/recommendation-gradient.md b/packages/agents/content/skills/_data/recommendation-gradient.md
index 9e6b6461..850db1fd 100644
--- a/packages/agents/content/skills/_data/recommendation-gradient.md
+++ b/packages/agents/content/skills/_data/recommendation-gradient.md
@@ -21,21 +21,28 @@ Rank options on correctness — behavior, API quality, architectural soundness,
 
 ## Format
 
-Marker, then option title and colon, then inline pros (`➕`) and cons (`➖`) separated by `;`. Lead with the strongest argument. One line per option when possible.
+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.
 
 ## Examples
 
 ```
 Want me to:
-1. ■□□ Use a single config file: ➕ minimal surface area; ➖ couples concerns.
-2. ■■■ Split into two configs: ➕ separates lifecycle and runtime concerns; ➕ matches existing repo pattern.
-3. □□□ Use three configs: ➖ over-decomposed for current scope.
+1. ■□□ Use a single config file:
+   ➕ minimal surface area;
+   ➖ couples concerns.
+2. ■■■ Split into two configs:
+   ➕ separates lifecycle and runtime concerns;
+   ➕ matches existing repo pattern.
+3. □□□ Use three configs:
+   ➖ over-decomposed for current scope.
 ```
 
 ```
 Want me to:
-1. Use camelCase: ➕ matches the host file's local style.
-2. Use kebab-case: ➕ matches the package's public API style.
+1. Use camelCase:
+   ➕ matches the host file's local style.
+2. Use kebab-case:
+   ➕ matches the package's public API style.
 ```
 
 ## Don'ts
diff --git a/packages/agents/content/skills/design-and-plan/SKILL.md b/packages/agents/content/skills/design-and-plan/SKILL.md
index a05e9d74..0bde40a9 100644
--- a/packages/agents/content/skills/design-and-plan/SKILL.md
+++ b/packages/agents/content/skills/design-and-plan/SKILL.md
@@ -68,7 +68,7 @@ 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 inline `➕` pros, `➖` cons (e.g., `1. ■■■ Option title: ➕ pro; ➖ con.`).
+   - 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.
 
 ### Phase 3: Converge on a design