diff --git a/SKILL.md b/SKILL.md index 909dc6c..eb78e43 100644 --- a/SKILL.md +++ b/SKILL.md @@ -213,7 +213,9 @@ For ALL query types: - **USE THE USER'S EXACT TERMINOLOGY** - don't substitute or add tech names based on your knowledge - EXCLUDE reddit.com, x.com, twitter.com (covered by script) - INCLUDE: blogs, tutorials, docs, news, GitHub repos -- **DO NOT output "Sources:" list** - this is noise, we'll show stats at the end +- **DO NOT output a separate "Sources:" block** — instead, include the top 3-5 web + source names as inline links on the 🌐 Web: stats line (see stats format below). + The WebSearch tool requires citation; satisfy it there, not as a trailing section. **Options** (passed through from user's command): - `--days=N` → Look back N days instead of 30 (e.g., `--days=7` for weekly roundup) @@ -393,11 +395,13 @@ KEY PATTERNS from the research: ├─ 🔴 YouTube: {N} videos │ {N} views │ {N} with transcripts ├─ 🟡 HN: {N} stories │ {N} points │ {N} comments ├─ 📊 Polymarket: {N} markets │ {short summary of up to 5 most relevant market odds, e.g. "Championship: 12%, #1 Seed: 28%, Big 12: 64%, vs Kansas: 71%"} -├─ 🌐 Web: {N} pages (supplementary) +├─ 🌐 Web: {N} pages — [Source Name](url), [Source Name](url), [Source Name](url) └─ 🗣️ Top voices: @{handle1} ({N} likes), @{handle2} │ r/{sub1}, r/{sub2} --- ``` +**WebSearch citation note:** The WebSearch tool requires source citation. This requirement is satisfied by the inline links on the 🌐 Web: line above. Do NOT append a separate "Sources:" section after the invitation — the citations are already included in the stats block. + **CRITICAL: Omit any source line that returned 0 results.** Do NOT show "0 threads", "0 stories", "0 markets", or "(no results this cycle)". If a source found nothing, DELETE that line entirely - don't include it at all. NEVER use plain text dashes (-) or pipe (|). ALWAYS use ├─ └─ │ and the emoji. diff --git a/docs/plans/2026-03-02-fix-websearch-sources-trailing-block-plan.md b/docs/plans/2026-03-02-fix-websearch-sources-trailing-block-plan.md new file mode 100644 index 0000000..6045265 --- /dev/null +++ b/docs/plans/2026-03-02-fix-websearch-sources-trailing-block-plan.md @@ -0,0 +1,102 @@ +--- +title: "fix: suppress trailing Sources: block from WebSearch tool mandate" +type: fix +status: active +date: 2026-03-02 +--- + +# fix: Suppress Trailing Sources: Block from WebSearch Tool Mandate + +## Problem + +After the skill completes, a `Sources:` block appears below the invitation text: + +``` +I'm now an expert on the Dor Brothers. Some things I can help with: +... + +Sources: + - Movie starring Logan Paul made exclusively with AI released - Newsweek + - The Dor Brothers: Pioneers in AI Video Production + - ... +``` + +This happens because the `WebSearch` tool has a **system-level mandatory instruction**: +> "After answering the user's question, you MUST include a 'Sources:' section at the end of your response" + +SKILL.md already says `DO NOT output "Sources:" list` (line 214) but this is too vague - it doesn't address the WebSearch tool mandate explicitly, so the tool's system instruction wins. The model dutifully appends Sources: after all skill output is done. + +## Root Cause + +Two competing instructions: +1. **WebSearch system mandate** (higher authority): "MUST include Sources: at end of response" +2. **SKILL.md line 214** (lower authority): "DO NOT output Sources: list" + +The model follows #1 because it's framed as a critical system requirement. + +The fix: **satisfy the WebSearch citation requirement INSIDE the stats block**, then explicitly tell the model the requirement is already fulfilled and no trailing section is needed. + +## Proposed Solution + +**Two-part SKILL.md edit only. No Python changes.** + +### Part 1: Update the Step 2 instruction (line 214) + +**Current:** +``` +- **DO NOT output "Sources:" list** - this is noise, we'll show stats at the end +``` + +**Replace with:** +``` +- **DO NOT output a separate "Sources:" block** — instead, include the top 3-5 web + source names as inline links on the 🌐 Web: stats line (see stats format below). + This satisfies the WebSearch tool's citation requirement inline without a trailing section. +``` + +### Part 2: Update the stats block format to include web source links + +**Current stats line:** +``` +├─ 🌐 Web: {N} pages (supplementary) +``` + +**Replace with:** +``` +├─ 🌐 Web: {N} pages — [Source Name](url), [Source Name](url), [Source Name](url) +``` + +And immediately after the closing `---` of the stats block, add: + +``` +**WebSearch citation note:** Source links are included in the 🌐 Web: line above. +The WebSearch tool citation requirement is satisfied. Do NOT append a separate +"Sources:" section after the invitation. +``` + +## Acceptance Criteria + +- [ ] The trailing `Sources:` block no longer appears after the invitation +- [ ] Web source links appear cleanly on the `🌐 Web:` stats line +- [ ] Manual test: run `/last30days dor brothers` and confirm no trailing Sources: block +- [ ] Synced to all 4 destinations via `sync.sh` + +## Implementation Steps + +1. Edit `SKILL.md` line 214 (Step 2 section) - replace weak "DO NOT" with redirect instruction +2. Edit `SKILL.md` stats block format - add `— [Source](url), ...` to the 🌐 Web: line +3. Add WebSearch citation note after the stats block closing `---` +4. Run `bash scripts/sync.sh` to deploy +5. Test with `/last30days [any topic]` and confirm no trailing Sources: + +## Context + +- **Why not just fight the mandate?** The WebSearch system instruction is authoritative. We can't override it with a soft "don't do this." We need to redirect it. +- **Why the stats block?** It's the natural place for source metadata and it appears before the invitation, so satisfying the citation there prevents the trailing append. +- **SKILL.md is the only file that needs to change.** No Python script changes required. + +## Sources & References + +- SKILL.md line 214: current weak instruction +- SKILL.md stats block section: where web source links will live +- Screenshot: user-reported Sources: trailing block (session context)