From f3d7c5bc2daa1792506954ba1fff0f5aa225fcd9 Mon Sep 17 00:00:00 2001 From: dan Date: Sun, 28 Dec 2025 22:21:05 -0500 Subject: [PATCH] docs: resolve web search design questions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Context changed - Claude Code now has built-in WebSearch/WebFetch. Decisions: - Keep two separate skills (web-search, web-research) - web-search: OpenCode only (Claude Code has native search) - web-research: Both (deep research beyond built-in capability) - Source filtering via WebSearch allowed_domains, not skill feature - Summaries by default, not raw links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .beads/issues.jsonl | 2 +- web_search_brainstorm.md | 24 ++++++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index a49f1fb..5f33efd 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -98,7 +98,7 @@ {"id":"skills-u3d","title":"Define skill trigger conditions","description":"How does an agent know WHEN to apply a skill/checklist?\n\nOptions:\n- frontmatter triggers: field with patterns\n- File-based detection\n- Agent judgment from description\n- Beads hooks on state transitions\n- LLM-based pattern detection","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-23T17:59:09.69468767-05:00","updated_at":"2025-12-23T17:59:09.69468767-05:00"} {"id":"skills-uan","title":"worklog: merge Guidelines and Remember sections","description":"Guidelines (8 points) and Remember (6 points) sections overlap significantly - both emphasize comprehensiveness, future context, semantic compression. Consolidate into single principles list. Found by bloat lens review.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.148596791-05:00","updated_at":"2025-12-27T10:05:51.527595332-05:00","closed_at":"2025-12-27T10:05:51.527595332-05:00","close_reason":"Closed"} {"id":"skills-uz4","title":"Compare RESUMABILITY.md with upstream","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.897754095-08:00","updated_at":"2025-12-03T20:19:29.384645842-08:00","closed_at":"2025-12-03T20:19:29.384645842-08:00","dependencies":[{"issue_id":"skills-uz4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.899671178-08:00","created_by":"daemon","metadata":"{}"}]} -{"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-11-30T11:58:33.482270742-08:00"} +{"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"in_progress","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-12-28T22:19:31.779352551-05:00"} {"id":"skills-vjm","title":"Refactor update-agent-context.sh: reduce nesting depth","description":"File: .specify/scripts/bash/update-agent-context.sh\n\nIssues:\n- update_existing_agent_file() has 4-level deep nesting (lines 360-499)\n- State machine with multiple variables: in_tech_section, in_changes_section, tech_entries_added\n- 70+ lines of while loop processing\n\nFix:\n- Extract file processing to separate function\n- Consider sed/awk for line-based transformations\n- Use guard clauses to reduce nesting\n\nSeverity: HIGH","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:57.874439288-05:00","updated_at":"2025-12-25T01:44:58.38265672-05:00","closed_at":"2025-12-25T01:44:58.38265672-05:00","close_reason":"update-agent-context.sh is .specify upstream code, not maintained here"} {"id":"skills-vpy","title":"Design checklist support for skills","description":"Design how checklists fit into the skills system.\n\nQuestions:\n- Skill-as-checklist (SKILL.md with just items, no scripts)?\n- Separate checklist format?\n- Trigger conditions in frontmatter?\n- Integration with bd audit for tracking?\n\nTiers considered:\n1. AGENTS.md (simplest, no tracking)\n2. Skill-as-checklist (deployed, invokable)\n3. Proto (full tracking, overhead)","status":"in_progress","priority":2,"issue_type":"task","created_at":"2025-12-23T17:59:09.569427412-05:00","updated_at":"2025-12-23T17:59:25.865326103-05:00"} {"id":"skills-wm9","title":"Research Steve Yegge's orchestration work","description":"Steve Yegge is working on something new related to AI orchestration. Research what it is and how it might inform our skills+molecules integration design.\n\nBlocks: skills-hin (ADR finalization)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:41:47.848905848-05:00","updated_at":"2025-12-24T02:42:24.40239935-05:00","closed_at":"2025-12-24T02:42:24.40239935-05:00","close_reason":"Not needed - just parking the ADR work"} diff --git a/web_search_brainstorm.md b/web_search_brainstorm.md index 7faa591..11a834f 100644 --- a/web_search_brainstorm.md +++ b/web_search_brainstorm.md @@ -51,3 +51,27 @@ Create a versatile web search skill that supports multiple search modes, provide - Do you prefer a single "smart" skill that figures out what to do, or explicit flags/subcommands? - Are there specific sources you search often (e.g., NixOS packages)? - Do you want raw links or summarized answers? + +## Resolution (2025-12-28) + +**Context changed**: Claude Code now has built-in WebSearch and WebFetch tools. + +**Decisions:** + +1. **Single smart skill vs flags?** Keep two separate skills: + - web-search: Quick searches (for OpenCode which lacks built-in search) + - web-research: Deep research with structured reports (valuable for both) + +2. **Specific sources priority?** Not needed as skill feature. + - WebSearch has `allowed_domains` parameter + - User says "search nixos wiki for X" and agent uses domain filtering + +3. **Raw links vs summaries?** Summaries by default (current behavior). + - Raw links without context are less useful + - Agent synthesizes information + +**Deployment:** +- web-search: OpenCode only (Claude Code has native WebSearch) +- web-research: Both (deep research with backends beyond built-in capability) + +**Status:** Questions resolved, no changes needed to skills.