Scout

---
name: scout
description: >-
  Competitive reconnaissance for your project — what do the repos solving
  this same problem do better, and what's worth adopting? Finds peer repos
  (ranked by activity, downloads, dependents — never raw stars), mines what
  their users beg for — issue reactions, releases, docs claims, every
  finding with a locator — and verdicts each candidate feature
  ADOPT/ADAPT/SKIP/WATCH, where SKIP is the default and "a competitor has
  it" is never a reason. ADOPT items become ready seeds for feature or
  autopilot; verdicts persist in out/scout/tracker.md so repeat runs open
  with what changed. Keyless. Use for "what are similar projects doing",
  "compare us to X", "what are we missing" — e.g. "/scout",
  "/scout <owner/repo>", "/scout deep <repo>". For X-vs-Y tech choices use
  verdict; for community buzz use pulse.
---

# scout — know the neighbors before building blind

`/scout` — find peer projects, then reconnoiter them
`/scout <owner/repo> [...]` — reconnoiter exactly these peers
`/scout deep <owner/repo>` — one peer, source-level (clone + file:line evidence)

Answer one question: **what have the projects solving this same problem
learned that we haven't — and which of those lessons deserves to exist
here?** Both halves matter: a scout that only returns "features to copy" is
just an automated parity trap. The deliverable is judgment: adopt this,
skip that, and the evidence either way.

## Step 0 — Know thyself first

Recon of others starts with a fix on your own position:

- Read this repo's `AGENTS.md` (the map skill writes it), `README`, and its
  own issue tracker's top-reacted open requests. Distill: **the project's
  job in one sentence**, and its **differentiation axis** — the thing it
  does that peers don't, which every later verdict is judged against.
- Read `out/scout/tracker.md` if it exists: peers already scouted, verdicts
  already made. A feature SKIPped with a reason isn't re-litigated unless
  the evidence changed; repeat runs open with **"Since last scout"** — new
  releases, new high-reaction requests, verdicts due for revisit.
- "Similar" means **same problem, not same tech stack** — a peer in another
  language that owns your problem space teaches more than a same-framework
  neighbor that doesn't.

## Step 1 — Find the peers (skip when the user names them)

Discover candidates keyless, then rank by signals that resist gaming:

- **GitHub topics overlap** (`/repos/{o}/{r}/topics`, then
  `/search/repositories?q=topic:X`) and README/description keyword search.
- **Registry keyword co-occurrence** — npm `/-/v1/search?text=keywords:...`,
  PyPI JSON — projects sharing your package keywords.
- Awesome lists and "alternatives to X" directories for the long tail.

Rank by **recent push cadence, download counts (api.npmjs.org /
pypistats.org), and dependents (deps.dev)** — never by raw stars; star
counts are purchasable and four-figure HN threads document the fake-star
economy. Present the candidates with one line each on why they qualify;
settle on **3–6 peers**. Fewer, studied properly, beats a survey.

## Step 2 — Reconnoiter each peer

One sub-agent per peer, in parallel. Budget first: keyless GitHub allows
**60 core req/hr and 10 search req/min shared across all sub-agents** —
allocate calls per peer up front, and on a 403 mark the signal unknown
rather than retrying in a loop. Each agent mines three signal layers:

1. **What their users beg for** — open issues sorted by 👍 reactions
   (`/search/issues?q=repo:X+is:issue+is:open&sort=reactions-%2B1`).
   Enhancement requests draw ~4× the reactions bugs do; this is raw market
   demand. A high-reaction request a peer *hasn't* built is as valuable as
   a shipped feature — it's an open lane, not a gap to close.
2. **What they shipped, and when** — the releases API: feature inventory
   from release notes, plus shipping cadence (a peer releasing weekly
   pressures differently than an annual one).
3. **What they claim** — README/docs feature inventory, marked as claims,
   not verified behavior.

**Every finding carries a locator** — issue URL with reaction count,
release tag, doc anchor. AI summaries of unfamiliar repos are exactly where
confident hallucination lives; a claim without a pointer is discarded, not
softened. Each agent writes full findings to `out/scout/.work/<peer>.md`
and returns a summary; synthesize from the files.

**Deep mode** (`/scout deep <repo>`, or offered when a verdict needs it):
clone the peer locally and read the implementation — architecture choices,
the tricky parts of a feature you're weighing. Evidence tightens to
**file:line**. This is the expensive tier; use it on the one or two peers
that earned it, never the whole field.

## Step 3 — The gap, both ways

Lay the feature inventories side by side against your project's job:

- **They have, we lack** — the adoption candidates, each with its demand
  evidence attached.
- **We have, they lack** — the moat. Knowing what not to break or dilute
  is half the value of the exercise; these feed the differentiation axis,
  not the backlog.
- **Nobody has, their users want** — open lanes from layer-1 signals; often
  the best entries on the list.

## Step 4 — Verdicts, with the parity gate

For each candidate: **ADOPT / ADAPT / SKIP / WATCH**. The gate:

- **SKIP is the default.** "A peer has it" removes a reason to say no and
  supplies none to say yes; parity-chasing is the documented failure mode
  of this whole exercise. Promotion out of SKIP needs positive evidence:
  demand in *your* tracker or stated goals, fit with *your*
  differentiation axis, and a cost that fits the value.
- **ADOPT** — wanted here, fits the axis: one-paragraph implementation
  sketch shaped to this codebase + effort estimate. **ADAPT** — the idea
  transfers, their shape doesn't; name what changes. **WATCH** — promising
  but unproven; note the revisit trigger (adoption numbers, a stable
  release).
- **License check before any ADAPT that borrows shape:** ideas are free,
  code is licensed — flag the peer's license (a GPL peer next to your MIT
  project means re-implement from the idea, never from the source).

## Step 5 — Brief, memory, handoff

- Render the brief **in chat** per `references/brief-template.md` (read it
  when you reach this step), then save to `out/scout/<slug>-<YYYY-MM-DD>.md`
  (date via `date +%F` — never guessed; create the folder if needed;
  committing the brief is the user's call).
- Update `out/scout/tracker.md`: one row per peer (last release seen, last
  scout date) and one per verdict (feature · verdict · reason · date) — the
  memory that makes the next run a delta instead of a redo.
- Offer the handoff, never perform it: each ADOPT item is phrased as a
  ready `/feature <item>` or `/autopilot <item>` invocation, with the
  brief's sketch as the spec seed.

## Guardrails

- **"A competitor has it" is never a reason.** Every ADOPT cites demand or
  goal-fit from *this* project's side. The skill exists to prevent the
  parity trap, not to automate it.
- **Evidence is a locator.** Issue URL, reaction count, release tag,
  file:line in deep mode. No locator, no finding.
- **Stars are noise.** Rank and argue from cadence, downloads, dependents,
  and reaction counts — the signals that resist buying.
- **Respect the budget.** 60 req/hr shared; allocate up front, degrade
  honestly ("signal unknown") instead of retry-looping.
- **The moat is output too.** A brief that only lists what to copy failed;
  what to protect and what lanes are open carry equal weight.
- **Advisory, not authoritative.** It recommends with evidence; the human
  decides what enters the backlog. Nothing is implemented, filed, or
  committed by this skill.