Artefact: Research

Research a focus and render what was found as an HTML artefact. The research is the expensive part; the artefact is the honest record of it, so every claim on the page carries a source or a visible unverified mark.

Worked example of the format bar, when working in ~/.claude: ~/.claude/docs/artefacts/swamp-club.html ("swamp club free tier" resource assess). Worth a look before writing HTML there, but not a prerequisite: Step 4 below and references/formats.md already state the full contract, and artefact-conventions Step 2 finds and reads whatever existing artefacts a project has on disk regardless.

Step 1: Parse $ARGUMENTS

Positional, in this order. Quote the focus; the rest are bare words.

Target says what kind of thing is under the lens:

• resource: one nameable thing with a maintainer: a tool, library, service, plan, dataset
• practice: a way of working with no single owner: a pattern, technique, convention, workflow
• field: a space containing many candidates, where the subject is the space itself

Format says the shape of the page. Section schemas are in references/formats.md; read the one you need in Step 4.

Invalid pairs (field assess, resource primer of a tool that has docs) get one line saying why and the nearest valid pair, then stop.

Missing or unparseable required args: ask once with AskUserQuestion, one question per missing arg, then continue.

• All three required args resolved and the pair is valid
• source split into a list (empty list when absent)

Step 2: Resolve sources

source restricts where evidence comes from; it never merely suggests.

• Given: read only those. A domain means its docs and pricing pages; a repo URL means README, licence, releases, issues; a local path means the files under it. Web search is allowed only to locate pages within the given sources.
• Absent: you choose. Default order: the subject's own docs and repo, then independent coverage (issues, changelogs, third-party write-ups), then the user's own code under ~/code when the format has a fit section. Web search freely.

Either way, keep a running source ledger: every URL or path actually read, with the date. It becomes the footer. A page read but not cited still belongs in the ledger; a claim with no ledger entry is unverified by definition.

Vendor-only evidence is a finding, not a footnote: when no independent source turned up, the page says so in the constraints or method section (the reference artefact does this in one sentence).

• Ledger started before the first fetch
• Restriction honoured when source was given

Step 3: Research

Split the work by where the evidence lives, and run the two halves in parallel:

• External evidence (docs, repo, registries, independent coverage): delegate to one general-purpose agent. The prompt names the format's schema sections as required headings, demands the exact URL and a verbatim quote for every load-bearing fact, and ends with a mandatory source ledger (every URL read, one per line, with what it gave) plus a could-not-find list. Return raw findings, not prose. Keeping the fetches out of the main context is what leaves room to write the page.
• Local evidence (the ~/code inventory, per-repo second passes): do it inline with Bash. One survey loop over every git repo (last commit, 90-day commits and authors, the dependency in question, files importing it, rival libraries present), then targeted greps on the candidates that surfaced.

Read until the format's schema is filled or the sources run out, whichever comes first. Two rules that separate research from summarising:

1. Quote the load-bearing sentence. Pricing gates, licence carve-outs, rate limits, "only when the server is running": copy the words, in a blockquote.ev, with the page cited beside it. Paraphrase is where errors creep in.
2. Name what you could not find. A limit that no page states, a claim with a single vendor source, a question two readings of the docs leave open: each becomes an explicit unverified chip on the page (artefact-conventions, epistemic honesty). Absence of a documented limit is not absence of a limit.

For assess and compare, fit against real projects is required when the sources allow it: inventory the candidate repos (git log recency, stack, who commits), and for each say fits / stretch / no fit with the reason. The reference artefact's Strand III is the model: the verdict names one project to spike first, a time estimate for the spike, and the condition under which the spike should be abandoned.

• External research delegated with ledger and could-not-find list required
• Local survey run inline before the agent returns, so neither waits on the other
• Every load-bearing claim quoted, not paraphrased
• Every gap marked, none smoothed over

Step 4: Render

Follow artefact-conventions (announce, location, existing aesthetic, shared rules). Then:

1. Read references/formats.md, the section for the chosen format. Its sections are the page's sections, in that order; drop a section only when the sources gave nothing for it, and say so in one line where it would have sat.
2. Masthead: kicker {Target} {format} · {date}, title, one-paragraph standfirst that already states the answer, then a statline of research counts (pages read, candidates assessed, repos checked, whatever the format makes real). Counts come from the ledger, not from memory.
3. Verdict box first, for every format except primer: the reader who stops after the masthead has the answer. primer opens with its anchor concept instead.
4. Legend for the chip set the format uses (fits / stretch / no fit / unverified for assess; the format schema names the others).
5. Sections as collapsible <details> past the conventions' threshold, with the rail table of contents and expand/collapse controls.
6. Footer: the source ledger as a closed <details>, every entry a link, plus the method in two sentences (what was read, what was not, when).

Location: <project-root>/docs/artefacts/research-{slug}.html, then publish with the Artifact tool (favicon 🔬, description = the standfirst's first sentence). In ~/.claude the artefact joins the existing aesthetic (warren-report.html, swamp-club.html); elsewhere, Step 2 of artefact-conventions decides.

• Verdict readable without opening any <details>
• Ledger footer present, all entries linked
• artefact-conventions checklist run

Step 5: Report

File path, artefact URL, the verdict in one line, and the count of unverified marks with what each one is waiting on. If the verdict recommends a spike, end with its first action.