Trove collection and normalization for swain-design artifacts. Collects sources from the web, local files, and media (video/audio), normalizes them to markdown, and caches them in reusable troves. Use when researching a topic for a spike, ADR, vision, or any artifact that needs structured research. Also use to refresh stale troves or extend existing ones with new sources. Triggers on: 'research X', 'gather sources for', 'compile research on', 'search for sources about', 'refresh the trove', 'find existing research on X', or when swain-design needs research inputs for a spike or ADR.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Trove collection and normalization for swain-design artifacts. Collects sources from the web, local files, and media (video/audio), normalizes them to markdown, and caches them in reusable troves. Use when researching a topic for a spike, ADR, vision, or any artifact that needs structured research. Also use to refresh stale troves or extend existing ones with new sources. Triggers on: 'research X', 'gather sources for', 'compile research on', 'search for sources about', 'refresh the trove', 'find existing research on X', or when swain-design needs research inputs for a spike or ADR.
{"short-description":"Trove collection and normalization","version":"1.0.0","author":"cristos","source":"swain"}
swain-search
Collect, normalize, and cache source materials into reusable troves that swain-design artifacts can reference.
Mode detection
Signal
Mode
No trove exists for the topic, or user says "research X" / "gather sources"
Create — new trove
Trove exists and user provides new sources or says "add to" / "extend"
Extend — add sources to existing trove
Trove exists and user says "refresh" or sources are past TTL
Refresh — re-fetch stale sources
User asks "what troves do we have" or "find sources about X"
Discover — search existing troves by tag
Prior art check
Before creating a new trove or running web searches, scan existing troves for relevant content. This avoids duplicating research and surfaces connections to prior work.
Report what was found — show the trove ID, matching source titles, and relevant excerpts
Suggest extend over create — if an existing trove covers the same topic, extend it rather than creating a parallel trove
Cross-link — if the topic is adjacent but distinct, create a new trove but note the related trove in synthesis.md
This step runs in all modes (Create, Extend, Discover) and before any web searches. Existing trove content is always checked first.
Create mode
Build a new trove from scratch.
Step 1 — Gather inputs
Ask the user (or infer from context) for:
Trove ID — a slug for the topic (e.g., websocket-vs-sse). Suggest one if the context is clear.
Tags — keywords for discovery (e.g., real-time, websocket, sse)
Sources — any combination of:
Web search queries ("search for WebSocket vs SSE comparisons")
URLs (web pages, forum threads, docs)
Video/audio URLs
Local file paths
Freshness TTL overrides — optional, defaults are fine for most troves
If invoked from swain-design (e.g., spike entering Active), the artifact context provides the topic, tags, and sometimes initial sources.
Step 2 — Collect and normalize
For each source, use the appropriate capability. Read skills/swain-search/references/normalization-formats.md for the exact markdown structure per source type.
Web search queries:
Use a web search capability to find relevant results
Select the top 3-5 most relevant results
For each: fetch the page, normalize to markdown per the web page format
If no web search capability is available, tell the user and skip
Web page URLs:
Fetch the page using a browser or page-fetching capability
git add docs/troves/<trove-id>/
git commit -m "research(<trove-id>): create trove with N sources"
TROVE_HASH=$(git rev-parse HEAD)
Commit B — back-fill the commit hash into the history entry, then update the referencing artifact's frontmatter (if one exists):
# Replace "--" with the real hash in the history entry# Update artifact frontmatter: trove: <trove-id>@<TROVE_HASH>
git add docs/troves/<trove-id>/manifest.yaml
git add docs/<artifact-type>/<phase>/<artifact-dir>/ # if artifact exists
git commit -m "docs(<trove-id>): stamp history hash ${TROVE_HASH:0:7}"
If no referencing artifact exists yet (standalone research), Commit B still stamps the history entry — report the hash so it can be referenced later.
Push — after Commit B, push to origin/trunk so the trove is immediately available to other agents and sessions:
git push origin trunk
Step 6 — Report
Tell the user what was created:
Trove <trove-id> created with N sources — committed as <TROVE_HASH:0:7>.
docs/troves/<trove-id>/manifest.yaml — provenance and metadata
docs/troves/<trove-id>/sources/ — N normalized source files
Commit B: back-fill hash in history entry, update referencing artifact(s) frontmatter — check referenced-by in manifest for all dependents
Push: git push origin trunk
Report: "Refreshed N sources. M had changed content, K were unchanged. New hash: <TROVE_HASH:0:7>."
For sources with freshness-ttl: never, skip them during refresh.
Discover mode
Help the user find existing troves relevant to their topic.
Scan docs/troves/*/manifest.yaml for all troves
Match against the user's query by:
Tag match — trove tags contain query keywords
Title match — trove ID slug contains query keywords
For each match, show: trove ID, tags, source count, last refreshed date, referenced-by list
If no matches, suggest creating a new trove
Graceful degradation
The skill references capabilities generically. When a capability isn't available:
Capability
Fallback
Web search
Skip search-based sources. Tell user: "No web search capability available — provide URLs directly or add a search MCP."
Browser / page fetcher
Try basic URL fetch. If that fails: "Can't fetch this URL — paste the content or provide a local file."
Media transcription
"No transcription capability available — provide a pre-made transcript file, or add a media conversion tool."
Document conversion
"Can't convert this file type — provide a markdown version, or add a document conversion tool."
Paywall proxy
Keep truncated content. Note in manifest: "Paywalled; proxies exhausted." Suggest user provide content manually.
Never fail the entire run because one capability is missing. Collect what you can, skip what you can't, and report clearly.
Capability detection
Before collecting sources, check what's available. Look for tools matching these patterns — the exact tool names vary by installation:
Web search: tools with "search" in the name (e.g., brave_web_search, bing-search-to-markdown)
Page fetching: tools with "fetch", "webpage", "browser" in the name (e.g., fetch_content, webpage-to-markdown, browser_navigate)
Media transcription: tools with "audio", "video", "youtube" in the name (e.g., audio-to-markdown, youtube-to-markdown)
Document conversion: tools with "pdf", "docx", "pptx", "xlsx" in the name (e.g., pdf-to-markdown, docx-to-markdown)
Report available capabilities at the start of collection so the user knows what will and won't work.
Linking from artifacts
Artifacts reference troves in frontmatter:
trove:websocket-vs-sse@abc1234
The format is <trove-id>@<commit-hash>. The commit hash pins the trove to a specific version — troves evolve over time as sources are added or refreshed, and the hash ensures reproducibility.
The dual-commit workflow in Create step 5, Extend step 8, and Refresh step 7 handles this automatically — Commit A records the trove content and Commit B stamps the hash into the history entry and referencing artifact's frontmatter. Do not defer this to the operator.
