fix(skills): strengthen sniff gate and add absorb gate options (#49)

66cbbc9847de465a1d82be11ddb3a2ea517f2f91 · 2026-03-29 11:41:36 -0700 · Matt Van Horn

Two UX fixes from ESPN test run:

1. Sniff Gate: removed "(Optional)" from heading, added MUST-ask
   enforcement. Added decision matrix row for "no spec but community
   docs exist" (the ESPN case). Agent was silently skipping sniff
   when it should have asked.

2. Absorb Gate: added "Add features first" and "Review the research"
   options alongside Approve and Trim. Users want to add their own
   ideas and review before committing to generation.

Co-authored-by: Matt Van Horn <mvanhorn@MacBook-Pro.local>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Files touched

M skills/printing-press/SKILL.md

Diff

commit 66cbbc9847de465a1d82be11ddb3a2ea517f2f91
Author: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date:   Sun Mar 29 11:41:36 2026 -0700

    fix(skills): strengthen sniff gate and add absorb gate options (#49)
    
    Two UX fixes from ESPN test run:
    
    1. Sniff Gate: removed "(Optional)" from heading, added MUST-ask
       enforcement. Added decision matrix row for "no spec but community
       docs exist" (the ESPN case). Agent was silently skipping sniff
       when it should have asked.
    
    2. Absorb Gate: added "Add features first" and "Review the research"
       options alongside Approve and Trim. Users want to add their own
       ideas and review before committing to generation.
    
    Co-authored-by: Matt Van Horn <mvanhorn@MacBook-Pro.local>
    Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 skills/printing-press/SKILL.md | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index 80f38142..73b1f7a4 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -320,17 +320,20 @@ Suggested shape:
 3. ...
 ```
 
-## Phase 1.7: Sniff Gate (Optional)
+## Phase 1.7: Sniff Gate
 
 After Phase 1 research, evaluate whether sniffing the live site would improve the spec. Skip this gate entirely if the user already passed `--har` or `--spec` (spec source is already resolved).
 
+**IMPORTANT:** When the decision matrix below says "Offer sniff", you MUST ask the user via `AskUserQuestion`. Do NOT silently decide to skip sniff because the docs look thorough — the user should make that call. The only case where you skip silently is "spec appears complete" (no gap detected).
+
 ### When to offer sniff
 
 | Spec found? | Research shows gaps? | Auth required? | Action |
 |-------------|---------------------|----------------|--------|
-| Yes | Yes — docs or competitors show significantly more endpoints than the spec | No | **Offer sniff as enrichment** |
+| Yes | Yes — docs or competitors show significantly more endpoints than the spec | No | **MUST offer sniff as enrichment** |
 | Yes | No — spec appears complete | Any | Skip silently |
-| No | N/A | No | **Offer sniff as primary discovery** |
+| No | Community docs exist (e.g., Public-ESPN-API) | No | **MUST offer sniff OR --docs** — present both options so the user decides |
+| No | No docs found either | No | **MUST offer sniff as primary discovery** |
 | No | N/A | Yes (login required) | Skip — fall back to `--docs` |
 
 **Gap detection heuristic:** If Phase 1 research found documentation, competitor tools, or community projects that reference significantly more endpoints or features than the resolved spec covers, that's a gap signal. Example: "The Zuplo OpenAPI spec has 42 endpoints, but the Public-ESPN-API docs describe 370+."
@@ -576,11 +579,17 @@ Write to `$RESEARCH_DIR/<stamp>-feat-<api>-pp-cli-absorb-manifest.md`
 
 ### Phase Gate 1.5
 
-**STOP.** Present the absorb manifest to the user:
+**STOP.** Present the absorb manifest to the user via `AskUserQuestion`:
+
+"Found [N] features across [X] tools (MCPs, skills, CLIs, scripts). Our CLI will absorb all [N] and add [M] transcendence features. Total: [N+M] features. This is [Z]% more than the best existing tool."
 
-"Found [N] features across [X] tools (MCPs, skills, CLIs, scripts). Our CLI will absorb all [N] and add [M] transcendence features. Total: [N+M] features. This is [Z]% more than the best existing tool. Approve to proceed to generation."
+Options:
+1. **Approve — generate now** — Start CLI generation with the full manifest
+2. **Add features first** — You have specific features or ideas you want added to the manifest before building
+3. **Review the research** — Show me the full brief and manifest before deciding
+4. **Trim scope** — The feature count is too ambitious, let's focus on a subset
 
-Use AskUserQuestion. WAIT for approval. Do NOT generate until approved.
+WAIT for approval. Do NOT generate until approved.
 
 ---

← ca675212 fix(skills): auto-install printing-press binary in setup con · back to Cli Printing Press · feat(skills): auto-suggest novel CLI features before absorb a350f419 →