swain-search

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:

1. Use a web search capability to find relevant results
2. Select the top 3-5 most relevant results
3. For each: fetch the page, normalize to markdown per the web page format
4. If no web search capability is available, tell the user and skip

Web page URLs:

1. Fetch the page using a browser or page-fetching capability
2. Strip boilerplate (nav, ads, sidebars, cookie banners)
3. Normalize to markdown per the web page format
4. If fetch fails, record the URL in manifest with a failed: true flag and move on

Video/audio URLs:

1. Use a media transcription capability to get the transcript
2. Normalize to markdown per the media format (timestamps, speaker labels, key points)
3. If no transcription capability is available, tell the user and skip — or accept a pre-made transcript

Local files:

1. Use a document conversion capability (PDF, DOCX, etc.) or read directly if already markdown
2. Normalize per the document format
3. For markdown files: add frontmatter only, preserve content

Forum threads / discussions:

1. Fetch and normalize per the forum format (chronological, author-attributed)
2. Flatten nested threads to chronological order with reply-to context

Repositories:

1. Clone or read the repository contents
2. Mirror the original directory tree under sources/<source-id>/
3. Default: mirror the full tree. For large repositories (thousands of files), ingest selectively and set selective: true in the manifest entry
4. Populate the highlights array with paths to the most important files (relative to the source-id directory)

Documentation sites:

1. Crawl or fetch the documentation site
2. Mirror the section hierarchy under sources/<source-id>/
3. Default: mirror the full site. For large sites, ingest selectively and set selective: true
4. Populate the highlights array with paths to the most important pages
5. Preserve internal link structure where possible

Each normalized source gets a slug-based source ID and lives in a directory-per-source layout:

• Flat sources (web, forum, media, document, local): sources/<source-id>/<source-id>.md
• Hierarchical sources (repository, documentation-site): sources/<source-id>/ with the original tree mirrored inside

Source ID generation:

• Derive the source ID as a slug from the source title or URL (e.g., mdn-websocket-api, strangeloop-2025-realtime)
• When a slug collides with an existing source ID: append __word1-word2 using two random words from skills/swain-search/references/wordlist.txt
• If the wordlist is missing, append __ followed by 4 hex characters (e.g., __a3f8) as a fallback

Step 3 — Generate manifest

Create manifest.yaml following the schema in skills/swain-search/references/manifest-schema.md. Include:

• Trove metadata (id, created date, tags)
• Default freshness TTL per source type
• One entry per source with provenance (URL/path, fetch date, content hash, type)

Compute content hashes as bare hex SHA-256 digests (no prefix) of the normalized markdown content:

shasum -a 256 sources/mdn-websocket-api/mdn-websocket-api.md | cut -d' ' -f1

Step 4 — Generate synthesis

Create synthesis.md — a structured distillation of key findings across all sources.

Structure the synthesis by theme, not by source. Group related findings together, cite sources by ID, and surface:

• Key findings — what the sources collectively say about the topic
• Points of agreement — where sources converge
• Points of disagreement — where sources conflict or present alternatives
• Gaps — what the sources don't cover that might matter

Keep it concise. The synthesis is a starting point, not a comprehensive report — the user or artifact author will refine it.

Step 5 — Commit and stamp

Use the dual-commit pattern (same as swain-design lifecycle stamps) to give the trove a reachable commit hash.

Before Commit A — append a history entry to manifest.yaml with a -- placeholder for the commit hash: