software-research

Files (59)

• SKILL.md
• adr-template.md · assets/
• briefing-template.html · assets/
• README.md · assets/widgets/
• annotated-diagram.html · assets/widgets/
• before-after-architecture.html · assets/widgets/
• c4-container-view.html · assets/widgets/
• callout.html · assets/widgets/
• capacity-scaling-curve.html · assets/widgets/
• code-compare.html · assets/widgets/
• comparison-matrix.html · assets/widgets/
• cost-projection-lines.html · assets/widgets/
• cost-tco-breakdown.html · assets/widgets/
• cost-treemap.html · assets/widgets/
• decision-tree.html · assets/widgets/
• deployment-pipeline.html · assets/widgets/
• diff-block.html · assets/widgets/
• donut-gauge.html · assets/widgets/
• error-budget-gauge.html · assets/widgets/
• escalation-ladder.html · assets/widgets/
• evidence-confidence.html · assets/widgets/
• kpi-row.html · assets/widgets/
• maturity-radar-rings.html · assets/widgets/
• metric-bars.html · assets/widgets/
• migration-checklist.html · assets/widgets/
• okr-alignment-tree.html · assets/widgets/
• org-chart-tree.html · assets/widgets/
• ownership-map.html · assets/widgets/
• phasing-roadmap.html · assets/widgets/
• quadrant-plot.html · assets/widgets/
• quality-attribute-tree.html · assets/widgets/
• raci-matrix.html · assets/widgets/
• radar-scores.html · assets/widgets/
• rag-status-board.html · assets/widgets/
• range-bar.html · assets/widgets/
• region-az-topology.html · assets/widgets/
• rice-score-table.html · assets/widgets/
• risk-heatmap.html · assets/widgets/
• rollout-bar.html · assets/widgets/
• sequence-flow.html · assets/widgets/
• severity-summary.html · assets/widgets/
• skills-heatmap.html · assets/widgets/
• slider-metric.html · assets/widgets/
• spotify-model-grid.html · assets/widgets/
• state-machine.html · assets/widgets/
• status-badge.html · assets/widgets/
• team-topologies-map.html · assets/widgets/
• timeline.html · assets/widgets/
• verdict-card.html · assets/widgets/
• weighted-decision-matrix.html · assets/widgets/
• modes.csv · data/
• evals.json · evals/
• architecture.md · references/modes/
• deep-research.md · references/modes/
• library-eval.md · references/modes/
• migration.md · references/modes/
• spike.md · references/modes/
• report-structure.md · references/
• source-hierarchy.md · references/

SKILL.md (first lines)

# 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

From bmad-labs/skills, MIT.

More from bmad-labs/skills