software-research

# Software Research ## What this does Turns one software-engineering question into a verified, multi-perspective deliverable. It picks a research mode, simulates that mode's expert lenses, maps where they contradict, synthesizes an HTML briefing plus a Markdown or ADR record, then adversarially verifies every claim against its primary source — version-aware — before delivering. Run the full pipeline; do not shortcut a phase. ## Portability Self-contained. Built-in tools only (`Agent` general-purpose, `Write`, web search/fetch inside agents) plus the files in this folder. Drop the folder into any `.claude/skills/` directory and it works. ## Phase 0: Scope & detect the mode 1. If `$ARGUMENTS` has the question, use it; else ask what to research. 2. Read `data/modes.csv`. Match the question against each row's `signals` (semicolon-delimited cues). Pick the best-matching `mode_id`. - If two+ modes match with similar confidence, **ask the user which mode** (offer the matching modes + one-line descriptions). Otherwise proceed. - If nothing matches, use `deep-research` (the fallback). 3. State the chosen mode + your one-line interpretation of the question. The user may override the mode. 4. Identify the **reader role** (developer / tech-lead / architect) from context; default `tech-lead`. 5. Derive a kebab-case `topic-slug` for filenames. 6. **Gate 1 — confirm scope (one pause).** Show a compact block and wait for the user to confirm or redirect before spawning any agents: ``` Mode: <mode_id> — <one-line why this mode> Question: <your one-line interpretation> Reader: <developer | tech-lead | architect> Lenses: <the N lens names about to run in parallel> Outputs: <primary + secondary format, e.g. HTML briefing + MD> Then: adversarial verification against primary sources. Proceed? (or correct the mode / scope) ``` This is the one place to catch a wrong mode or misread scope cheaply — before spending ~9-12 agents. Once confirmed, run Phases 1–3 autonomously (no more pauses until Gate 2). ## Phase 1: Parallel expert lenses Open `references/modes/{mode_id}.md` — it contains the exact lens prompts for this mode. Spawn that mode's lenses as **`general-purpose` agents in a single message** so they run concurrently. Give every agent the SAME question frame plus: - its lens prompt (from the mode file), - the source hierarchy + verification expectations from `references/source-hierarchy.md` (paste the tier list + all 7 rules — including Rule 7: load-bearing claims must resolve to Tier 1–3, never a blog/Q&A), - the instruction to return EXACTLY: (1) CORE POSITION in 2 sentences; (2) STRONGEST EVIDENCE, 3-5 bullets, each with a concrete data point + a **primary-source URL** and **the version/date the claim applies to**; (3) THE ONE THING only this lens would say. Under 400 words. Real fetched sources only — no invented studies, numbers, or URLs. As each lens returns, append its brief to a working scratch file `software-research-reports/{topic-slug}.work.md` (create it now) under a `## Lens: <name>` heading. Writing briefs as they land means a crash mid-run loses nothing — the run is resumable from what's already on disk. Set the run-state block at the top of that file: `stepsCompleted: [0, 1]`. When all return, post a 2-3 line note in chat: convergence + sharpest disagreement. Keep raw briefs out of chat. ❌ **Common failures here:** - Citing a blog / SO answer / model memory *as proof* instead of climbing to the primary source behind it (Rule 3 + Rule 7). The blog locates the fact; the primary *is* the fact. - Presenting an unversioned claim as current — "X does Y" with no version is unverified (Rule 1). - Letting one loud lens set the narrative before the others return; wait for all N. ## Phase 2: Map the contradictions (inline, no agents) From the briefs only, determine: 1. **Direct conflicts** — name the specific clashing claims. 2. **Strongest vs weakest evidence** — rank by source tier (Tier 1 primary/spec > Tier 2 security/aggregator > Tier 3 registry > Tier 4 benchmark > Tier 5 survey). 3. **The resolving question** — the single empirical test that settles the biggest conflict. 4. **Universal agreement** — what every lens confirms (load-bearing finding). 5. **The blind spot** — what NO lens addressed (missing 6th lens → frontier question). Append this map to the scratch file under `## Contradiction map` and bump the run-state to `stepsCompleted: [0, 1, 2]`. The map is the raw material for the synthesis; not a separate deliverable. ## Phase 3: Synthesize the output(s) Read the mode's `primary_output` and `secondary_output` from `data/modes.csv`. **Before writing any output, load `references/report-structure.md`.** It defines the **concreteness contract** (specific > generic: exact versions, real commands/config/ code, real numbers, tied to THE READER's stack — and a ban list of filler phrases) and the **12-section deep spine**. Detail is not optional padding: a report earns its length by being practical and about the reader's situation, not a survey of the topic. - For `html`: clone `assets/briefing-template.html`; do not rebuild the CSS. Fill every `{{TOKEN}}`. It has two layers: (a) the **fast-scan layer** up top — verdict scoreboard, key findings, and (for option-comparison modes) the Side-by-Side table — so the answer lands in five seconds; then (b) the **12-section deep body** (sections 06–16) that carries the full spine. Fill the deep sections per the concreteness contract; render comparisons/numbers/flows with widgets, not prose. - For `md`: the full **12-section spine** from `references/report-structure.md` — introduction/methodology, landscape, implementation how-to, stack, integration, performance, security, recommendation, roadmap, risks, methodology, and a closing References appendix. This is the detailed report; make each section concrete. In the References appendix every source is a clickable `[title — version/date](url)` Markdown link (never a bare URL in a table cell — those don't reliably render as links). - For `adr`: clone `assets/adr-template.md`; fill the MADR sections (Context, Decision Drivers, Considered Options, Decision Outcome, Consequences, Pros/Cons per option, More Information) and the closing **References** section. Document rejected options + why. The ADR stays a lean decision record — no 12-section spine — but the concreteness contract still applies (name versions, cite specifics). **Write for a busy engineer, not a journal.** Short sentences, plain words, lead with the answer. Define any unavoidable term inline. If a reader needs a dictionary to parse a finding, rewrite it. **Add a visualization when it earns its place.** `assets/widgets/` holds ~45 drop-in, zero-dependency visual blocks (inline SVG / CSS / a little vanilla JS). **Read `assets/widgets/README.md`** — it has the full catalog grouped by job (compare & decide, numbers & evidence, explain how it works, sequence over time, org & management, inline accents) plus a numbered "which visual to use" decision order. Pick by what the content is, not by novelty; copy the file, replace its `FILL:` markers. A few high-use anchors: `comparison-matrix` (options × criteria), `weighted-decision-matrix` (ADR scoring), `metric-bars` (benchmark/cost/size), `evidence-confidence` (per-finding trust), `callout` (gotchas/warnings), `verdict-card` (the recommendation), and `slider-metric` (the one interactive "drag it" widget — at most one per report). Default to the zero-dependency widgets: they render instantly, work offline, print, and can't be blanked by a CDN outage or a runtime handshake failing. For any tree/graph/diagram the widgets use **hand-placed coordinates** — don't auto-layout. Reach for a library only for what bespoke SVG is bad at: a standard flow/sequence/ER diagram easier written as text → Mermaid (pinned, `securityLevel:'strict'`); real quantitative data at scale → Chart.js; **code snippets that need syntax coloring → `code-compare` (it loads highlight.js pinned+SRI — include that block once per report, set `class="language-…"` per snippet)**. Then pin the version + prefer SRI/inline over a bare CDN `<script>`. **If you let the model generate arbitrary widget JS rather than filling a template, sandbox it** (iframe `sandbox="allow-scripts"` without `allow-same-origin`, CSP blocking `connect-src`) — generated markup is untrusted code in the report's origin; SRI does not help there. Full rules in `assets/widgets/README.md`. Write outputs to `software-research-reports/` (create if needed): - HTML → `{topic-slug}-briefing.html` - MD → `{topic-slug}.md`; ADR → `ADR-{topic-slug}.md` ❌ **Common failures here:** - Burying the recommendation under prose — the scoreboard and Bottom Line exist so the reader gets the answer before the detail. - Academic / oblique phrasing that reads as clever but doesn't inform. - For an X-vs-Y question, skipping the comparison table (the reader wants the side-by-side). ## Phase 4: Adversarial verification (mandatory) **Gate 2 — confirm findings before verifying (one pause).** With the draft synthesized, post a tight list in chat: the recommendation, the 3–5 key findings, and which claims are **load-bearing** (the recommendation rests on them). Ask the user to confirm the finding set / flag anything to scrutinize harder. This is the last cheap moment to redirect before spending verifier agents. Then run 4a–4c. `verify_depth` comes from `data/modes.csv` (`full` = every citation; `load-bearing` = the claims the recommendation rests on — still mandatory). **4a. Self-review (inline).** Score each finding 1-10 for reliability (by source tier, not confidence) and justify. Identify the weakest link + what would verify it. Bias check: which lens dominated, what got underweighted. Name the missing 6th lens. Assign an honest overall grade. **4b. Verify citations (parallel agents).** Spawn `general-purpose` agents in one message, one per citation cluster (~4-6). Each prompt: independently verify the claim against its PRIMARY source, applying all **7 rules** in `references/source-hierarchy.md` (version-bind; check current-version validity; climb to primary; date-stamp; security via OSV/GHSA + version range; benchmarks need reproducible methodology; **load-bearing claims must resolve to Tier 1–3**). Return VERDICT = CONFIRMED / PARTIALLY CONFIRMED (list corrections) / UNVERIFIED / FALSE / VERSION-STALE / **UNVERIFIED-LOWTIER** (a load-bearing claim backed only by Tier 5–6 — no primary found), the corrected one-line citation with version+date, and 2-4 specifics with the primary URL. Under 280 words. **4c. Apply corrections.** Fix wrong figures/titles/dates/versions. Downgrade confidence where evidence is thin; demote contested/preprint/version-stale AND `UNVERIFIED-LOWTIER` claims into the contested sidebar (a load-bearing claim with no primary backing must not stand as a finding). Fill the verification banner (`N checked · X corrected · Y demoted · Z version-stale`) and per-citation status tags. Populate the claim-safety guide (assert / caveat / avoid), the version-currency note, and confirm every source appears in the References section. Bump the run-state to `stepsCompleted: [0, 1, 2, 3, 4]`. ❌ **Common failures here:** - Skipping verification because the findings "look plausible" — plausible-but-wrong is exactly what an LLM panel produces; the verifier is the guard. - Leaving a load-bearing claim backed only by a blog/SO answer in the main findings instead of demoting it (Rule 7 → `UNVERIFIED-LOWTIER`). - Verifier "confirming" from memory instead of fetching the primary source. ## Output 1. Deliverables: the post-verification HTML + MD/ADR in `software-research-reports/`. 2. Open the HTML with the platform opener: macOS `open <path>`, Linux `xdg-open <path>`, Windows `start "" <path>`. If unclear, print the path. 3. Chat summary: file paths; verification tally; the one universal finding; the recommendation + its load-bearing claim; the frontier question; the claim-safety summary (safe to assert vs avoid). Keep it tight. ## Notes & guardrails - **Web search is required.** The lenses and verifiers depend on fetching live primary sources. If web search/fetch is unavailable inside the agents, abort and tell the user — never answer version- or security-sensitive software questions from training data alone; a model's memory is Tier 6 and goes stale. - **Real research only.** Every lens and citation traces to a real, fetched primary source with a version/date. If a figure can't be verified, demote or cut it; never paper over it. - **Prefer official docs over Q&A.** A load-bearing claim must resolve to Tier 1–3 (official docs/specs, security DBs, registries). Blogs, Stack Overflow, Medium, and model memory are signposts to find the primary — never proof on their own. - **Specific and practical, never generic.** Name exact versions; show real commands/ config/code; use real numbers; tie every recommendation to the reader's stack, team, and scale. Cut any sentence that describes a category instead of stating a fact ("offers robust support for…", "is widely used…", "can help improve performance…"). If a sentence wouldn't change what the reader does, delete it. Full contract + good/bad example in `references/report-structure.md`. - **Scratch file.** `{topic-slug}.work.md` holds lens briefs + the contradiction map for resumability; it is a working artifact, not a deliverable. Leave it in place (a resumed or re-run pass can reuse it); the deliverables are the HTML/MD/ADR. - **Version-aware.** "X does Y" is only valid as "…in version N". Flag deprecated or version-stale claims; never present stale info as current. - **The panel is author-built.** Disclose it. Lens agreement is a strong hypothesis, not field consensus. - **Reliability = source-tier evidence quality**, not confidence. - **Cost.** ~9-12 agents per run (lenses + verifiers). Expected. Don't fan wider than the mode's lenses / one verifier per citation cluster. - **Design.** Keep the HTML template CSS verbatim (clean white, Montserrat / Roboto Mono, blue accent).