search-first · diff
git:20260815.29dd944 to git:20260919.f95d231
74 added, 89 removed. Audit A to A.
---
name: search-first
- description: "Search npm / PyPI / MCP / GitHub / existing skills before writing code for any new feature, integration, library selection, or utility. Use whenever the user says 'add X functionality', 'implement Y', 'set up Z', 'integrate W', asks 'what library should I use for...', 'is there a package/client/MCP for...', proposes a specific tool while open to alternatives, or hits the planning.md wiring that routes dependency additions and self-built utilities here first. Especially when the task adds a dependency, picks between tools, or builds a utility that likely already exists (parser, checker, converter, linter, CI step, E2E framework, payment / auth / API client). DO NOT use for bug fixes, refactoring, config value edits, file summarization, or throwaway scripts whose approach the user already fully specified."
+ description: "Look outside before deciding: search the live web, registries and primary sources at decision time and bring back a report the caller picks from. Use for any question that may have an answer outside this repo — choosing a library or tool (「今どれが主流か」), prior implementations of a design problem (「この問題を解いた skill / repo は既にあるか」), whether a paper or post's claim applies here (「この主張はうちに当てはまるか」), what an official spec or CLI does now (「公式は何と言っているか」), the current state of practice (「今どうなっているか」), or checking a claim against its primary source (「原典は本当にそう言っているか」). Also on 'search first', 'is there a package for', or /search-first. Other entry points: this repo or the local machine → Explore agent; a whole article's fact-check → the writing repo's fact-checker; bug fixes, refactors and config edits → implementation-chain."
compatibility: Developed and tested on Claude Code; portable to other Agent Skills-compatible agents.
user-invocable: true
origin: shimo4228
---
- # /search-first — Research Before You Code
-
- Before writing a new feature, utility, integration, or picking a library, search
- for an existing solution first. The best code is code you don't have to write.
-
- This skill is **discipline, not mechanism.** The *how* of searching — parallel
- subagents, live documentation lookup, registry queries — belongs to your agent
- harness and keeps changing. What this skill pins down is the part that survives
- those changes: **articulate before you search, search by source priority, and
- end with a recorded verdict.** Lead with the discipline; delegate the mechanism.
+ # /search-first — Look Outside, Report, Let the Caller Pick
- ## Step 0 — Articulate the requirement (mandatory, user-visible text)
+ The searcher reports what exists outside and how it differs from our situation. The
+ caller — the main loop, a build session, an RFC author — reads the report and decides what
+ to adopt, adopt in part, or leave. A partial fit is a result: something found rarely drops in
+ unchanged, and a piece that transfers is worth the search (RFC-0022).
- Before any tool call or subagent, write 2–3 sentences of **plain assistant text**
- (not buried inside tool arguments) stating:
+ ## 0. State the question in text
- - **What** functionality is needed — concretely, not "X support"
- - **Language / framework** the implementation will use
- - **Constraints** — existing deps, performance limits, license requirements
+ Before the first tool call, write 2–3 sentences of plain assistant text: the question, which
+ row(s) of the table below it belongs to, and the constraints (language, existing deps,
+ license, budget). Tool arguments may mirror this text; the chat text is what lets the user
+ redirect before effort is spent.
- Why: this externalizes the search query so the user can redirect *before* you
- spend effort, and it leaves an auditable record. A subagent call whose `args`
- carry the requirement does **not** satisfy this step — the user reads chat text,
- not tool arguments. Emit the articulation as text first, then call tools whose
- arguments may mirror it.
+ ## 1. Check this repo first
- ## Step 1 — Search by source priority
+ One `rg` / Glob pass through the relevant modules, skills and notes. The thing may already
+ exist here. Then go outside.
- Check these in order; stop early when you find a strong match:
+ ## 2. Search by question type
- 0. **This repo** — `rg` / grep through the relevant modules and tests. The thing
- may already exist here.
- 1. **Package registries** — npm / PyPI / crates / Go modules for the language in play.
- 2. **MCP servers** — already-configured servers first, then the registry. The
- capability may already be wired in.
- 3. **Installed skills / agents / tools** — your harness may already carry it.
- 4. **Maintained OSS / templates** — code-search GitHub before writing net-new code.
+ The rows are handles for where to look and when to stop. A question that fits none still
+ runs; a question that fits two uses both rows.
- Query live documentation **at decision time** (e.g. context7, or the registry
- itself) rather than trusting remembered package facts — recommendations age.
+ | Type | Where to look | What counts as evidence | Stop when |
+ |---|---|---|---|
+ | Library / tool choice | registries (npm / PyPI / crates), official docs, release pages | last release date, license, dependency weight, the specific feature match | 2–3 candidates have primary facts |
+ | Prior implementation | GitHub code search, skill / agent / MCP catalogs, this harness (Glob) | the actual file (SKILL.md, source) read, with path or URL | 2 actual files read, or 3 independent sources agree |
+ | Claim of a paper / post | the primary text (arXiv, official blog, the repo file itself) | subject, premises (data, scale, environment), kind of evidence, how ours differs | subject and premises are written down |
+ | Spec / official behavior | official docs, `--help`, changelog, running it | version and date, the observed result | one version-stamped primary fact |
+ | State of practice | the rows above mixed, plus first-person operating notes | each item dated and sourced, the range covered | the next search would settle nothing you can name |
+ | Primary-source check | the full text the claim points at (past the abstract) | the passage and its locator; per claim: supported / partial / unsupported / unverified | every claim carries one of the four |
- ## Step 2 — Decide, and record a Verdict
+ Query live documentation at decision time (context7, the registry, the changelog itself):
+ recommendations age, and this harness treats external knowledge as stale within a week
+ (rule: knowledge-staleness).
- Assess candidates **holistically**: functional fit, maintenance (last commit,
- issue-response speed), community, docs, license, dependency footprint. Describe
- strengths and weaknesses in prose. **Do not** assign numeric scores (`8/10`),
- letter grades, or weighted point tables — they manufacture false precision; one
- evidence-backed verdict is the honest output.
+ ## 3. Report
- | Verdict | When | Action |
- |---------|------|--------|
- | **Adopt** | Exact match, well-maintained, permissive license | Install and use directly |
- | **Extend** | Good foundation, partial fit | Install + thin wrapper / config |
- | **Compose** | Several weak matches | Combine 2–3 small packages |
- | **Build** | Nothing suitable | Write custom — but informed by what you found |
+ The report is the deliverable. Write it so the caller can pick from it:
- **End every pass with one recognizable verdict line** — this line is the deliverable:
+ - Every claim carries an **as-of date and a source URL**.
+ - When nothing turned up, write the **range**: search terms, sources, date — "not located
+ within this boundary" leaves the next session a place to widen from.
+ - Say which you did for each source: **read the full text**, or **saw a snippet / abstract**.
+ - For every external finding give its **subject, its premises, and how our situation
+ differs**; the caller decides what transfers.
+ - Judgement is **prose backed by facts** — dates, versions, the concrete feature match.
+ Strengths and weaknesses in sentences; the canonical home of "evidence, not scores"
+ (ADR-0026).
```
- Verdict: <Adopt|Extend|Compose|Build> — <package(s) or "custom"> — <evidence-based reason>
+ ## Scope searched
+ terms / sources / as-of date — including what was not located
+ ## Found
+ per item: what (URL) / subject and premises / kind of evidence (experiment, benchmark,
+ adoption, opinion) / how our situation differs / the part that transfers
+ ## Still unknown
```
- A search with no verdict line is an **incomplete pass**: you did the work but left
- no decision the user (or the next step) can act on — the single most common failure
- of this workflow. Back the reason with evidence (stars, last-commit date, the
- specific feature match), never adjectives ("looks good", "popular").
-
- ## Quick Mode vs Full Mode
+ ## 4. Quick vs Full
- - **Quick Mode (inline)** — for a single obvious need: run Steps 0–2 yourself with
- a few searches and state the verdict.
- - **Full Mode (delegate)** — for non-trivial needs: after Step 0, hand the sweep to
- a **research subagent** (whatever your harness provides for solution discovery).
- Mirror the articulation into its prompt and have it return candidates plus a
- verdict in the format above. Reserve heavyweight multi-source research for
- genuinely hard questions — finding a library is lighter than a research report.
+ - **Quick (inline)** — a single obvious need: run 0–3 yourself with a few searches and write
+ the report in chat.
+ - **Full (delegate)** — a non-trivial question: after step 0, hand the sweep to a
+ **general-purpose subagent**. Its prompt carries the step-0 text, the table row(s), the
+ report format, a call budget (about 15 searches / fetches), and the instruction to work
+ with Read, Grep, Glob, WebSearch and WebFetch only — the Agent tool passes no tool
+ allowlist, so this restriction lives in the prompt (rule: security names web content
+ reaching a shell-capable agent as a threat surface). Read its report as the caller and
+ record what you take.
## When the user says "skip research"
- If the user tells you to skip research ("just implement", "no time", "use
- whatever"), **still record the decision as a verdict line** before implementing —
- skipping research is itself a decision, so it gets a verdict like any other pass
- (this keeps the choice auditable and the course-correct window open):
-
- > Skipping research at your request — I haven't checked for an existing library for X.
- > `Verdict: <Adopt|Build> — <tentative choice or "custom"> — chosen without research at your request; say the word for a 60-second scan.`
-
- Why: the user may not know a solution already exists; a silent skip removes their
- chance to course-correct. After the verdict line, proceed without searching —
- don't use this as a backdoor to do full research anyway.
-
- ## Anti-Patterns
-
- - **Jumping to code** — writing a utility without checking whether one exists.
- - **Ignoring MCP / installed capability** — rebuilding what is already wired in.
- - **Over-customizing** — wrapping a library so heavily its benefit is lost.
- - **Dependency bloat** — installing a massive package for one small feature.
- - **Search without verdict** — doing the legwork but never recording a decision.
+ Record the skip in one line, then proceed without searching:
- ## Examples (illustrative — verify packages live)
+ > Skipping research at your request — chosen without checking for an existing X; say the
+ > word for a 60-second scan.
- These show how a verdict *reads*; they are not current package endorsements.
- Re-search before relying on any specific package.
+ ## Example report (illustrative — format only; verify live before relying on any item)
- - **Dead-link checking** → a maintained, permissively-licensed link-check rule
- covering all link types →
- `Verdict: Adopt — textlint-rule-no-dead-link — active maintenance, MIT, full coverage`
- - **Qiita cross-posting** → only unmaintained partial wrappers exist →
- `Verdict: Build — custom — no maintained complete solution; reuse the platform API via an HTTP client`
- - **JP terminology consistency** → a dictionary-based checker needing a project config →
- `Verdict: Extend — textlint-rule-prh — install + a project dictionary`
+ ```
+ ## Scope searched
+ "markdown dead link checker" / "link check CI" — npm, crates.io, GitHub code search — 2026-09-14.
+ Not located: a checker that resolves wiki-style [[links]] in Obsidian vaults.
+ ## Found
+ 1. lychee (github.com/lycheeverse/lychee) — Rust CLI, checks http and local file links,
+ `--offline` mode; last release 2026-08 (read: README + docs/usage.md). Assumes plain
+ markdown links; our vault uses [[wikilinks]], so the http check transfers, the local
+ resolution does not.
+ 2. textlint-rule-no-dead-link (github.com/textlint-rule/textlint-rule-no-dead-link) —
+ runs inside textlint, http only (saw: README). Transfers only if textlint is already in
+ the pipeline; it is not in ours.
+ ## Still unknown
+ Whether either tool can be pointed at a custom link resolver.
+ ```