Feature Discovery: $ARGUMENTS

The research step at the very front of the pipeline. You frame a request and surface what already exists before anyone writes a spec or a plan — so reuse opportunities and house patterns are found early, not after the fact.

This skill carries ONLY invariant workflow logic. Every project-specific fact (plans location, architecture/module map, integrations) is read at runtime from .claude/PROJECT.md. You are strictly read-only on app code — you research and write a brief; you do not edit source, write a spec, or build a plan.

Pipeline position: /discover (research) → /analyst (spec) → /prepare (plan) → /implement (code).

Phase 0 — Load profile

Before anything else, load context (this mirrors skills/implement/SKILL.md):

1. Read .claude/PROJECT.md. If it is missing, or still contains TEMPLATE / placeholder markers, fall back to the root CLAUDE.md (always in context) when it carries the stack/architecture/integrations below — proceed on it, noting you're running without a kit profile. Only if neither has those facts, STOP and tell the user: "Profile not configured — run /bootstrap to generate .claude/PROJECT.md, then re-run /discover."
2. If $ARGUMENTS is empty, ask the user what feature or question to research.
3. Read applicable .claude/rules/* (conventions, patterns) that bear on the area, and CONTEXT.md (the domain glossary) if present — frame the request in its vocabulary.

From PROJECT.md, resolve and keep handy these keys (names are profile-defined):

• Plans/backlog location — where the feature brief is written.
• Architecture — layers, module map, where code lives.
• Integrations — external APIs and where their docs are.
• Domain — vocabulary and roles, to frame the request in the project's terms.

Then, before searching, skim the Plans/backlog location for an existing brief or spec on this topic. If it has already been researched, say so and build on the prior brief rather than re-researching a settled question without new evidence.

Phase 1 — Frame the request

Turn $ARGUMENTS into a crisp framing — do not start searching until this is clear:

• Problem statement — the concrete pain or gap, in the project's domain vocabulary.
• Who / why — who benefits (user / operator / developer / system) and why now.
• What "found" looks like — what a good discovery answers (reuse? prior art? feasibility?).

If the framing is ambiguous and it changes where you'd look, ask one focused question via AskUserQuestion. Otherwise restate your framing in 2–3 sentences and proceed.

Phase 2 — Prior-art in the repo (the core pass)

Find what already exists, guided by PROJECT.md → Architecture (its layer/module map):

1. Glob/Grep for existing implementations of the same or a similar capability — feature keywords, domain nouns, entity names, route/command names.
2. Reuse candidates — for each shared/utility/helper layer and common component named in PROJECT.md → Architecture, check whether the needed thing already exists.
3. Closest existing pattern — the nearest feature to replicate, so a later design matches house style.
4. For a large or unfamiliar repo, delegate the sweep to a read-only Explore agent ("very thorough"); summarize what it reports — do not dump file lists.
5. Prior/removed attempts — git log --grep=<keyword> and git log -- <path> (Bash) to surface earlier or reverted work on this capability, so you don't re-tread abandoned ground.

Search multi-modal — one angle always misses

Each search angle is blind to what the others surface. For anything beyond a trivial lookup, run several of these deliberately (not just keyword grep):

Negative results are findings. When an angle comes up empty, record it — "searched <how/terms> — absent". Evidence of absence (you looked, it's not there) is what justifies building new; absence of evidence (you didn't look) is how duplicates get written. These lines go into the brief so the next session doesn't re-run the same dead-end searches.

Cite a repo path (path:line) for every reuse candidate and prior-art claim. A claim with no path is a guess — drop it or verify it. Mark the tier of every claim: observed (opened the file, cite path:line) vs inferred (concluded from naming/structure — say so, and from what).

Phase 3 — External prior-art (optional)

Only when the question is genuinely open and repo evidence is insufficient:

1. If the feature touches a service in PROJECT.md → Integrations, WebFetch that service's official doc URL (from the Integrations entry or the matching rule) to confirm capabilities, endpoints, and constraints — verify, don't trust memory.
2. For a genuinely open research question (unknown approach, trade-offs not answerable from the repo), chain the global deep-research skill via Skill and fold its cited findings into the brief.
3. If the question is really "which library/gem/service should we adopt (or build)" — a selection among external candidates, not prior-art — route to /select-tech instead of answering it here: it owns the hard filters, the hard-case probe, and the adapter-seam contract. Note the handoff in the brief.

Skip this phase entirely when the repo already answers the question.

Phase 3.5 — Completeness check (before writing)

One deliberate pass before the brief: which search angle did I not run, and could it change the answer? If a cheap angle (tests, config/flags, history) is unrun and could overturn a "nothing exists" conclusion, run it now; otherwise name the gap honestly in the brief's Open questions. A brief that silently covered only one angle reads as "covered everything" — that's how duplicate implementations happen.

Phase 4 — Write the feature brief

Use Write to create a short brief at the Plans location from PROJECT.md, using its naming convention with a -brief suffix (e.g. <plans>/<YYYY-MM-DD>-<slug>-brief.md). Write only creates this new brief — this skill carries no Edit, so it never modifies existing source or specs (read-only on app code stands). Structure:

# <Feature> — Discovery brief

- **Date:** <today>   ·   **Status:** Discovery

## Problem
<the framing from Phase 1: pain/gap, who, why>

## What already exists (repo)
- `path:line` — <existing implementation / similar feature, what it does>

## Reuse candidates
- `path:line` — <reusable function/module/component> — <how it would be reused>

## Searched but absent
- <what was searched, which angles/terms> — not found (justifies building new; saves re-search)

## External prior-art
<integration docs / deep-research findings, with sources — or "n/a">

## Open questions
- <unresolved decision that affects scope or design>

## Risks
- <risk> — <why it matters>

## Suggested route
<`/analyst` to write a spec | `/prepare` if scope is already clear> — <one-line reason>

Keep it short and factual. Every reuse/prior-art line carries a path:line (repo) or a source URL (external).

Phase 4.5 — Skeptic gate (optional, before the brief is queued)

When the brief will be filed into the backlog rather than implemented next — a speculative idea, a bet on future demand, anything carrying a value claim rather than a defect — offer to run the idea-skeptic agent on it before it is queued. It attacks the idea on four lenses: economics at this project's real scale, supply (is there enough data/traffic/users to reach the bar at all), claim honesty against PROJECT.md, and measurability of the bar and its kill-condition on data the project owns today. Verdict: SURVIVES / KILLED / SURVIVES-WITH-AMENDMENTS, and amendments are binding — write each one into the brief before filing, or don't file it.

Skip the gate when the brief only reports what already exists in the repo (a reuse survey has no value claim to attack), or when the work goes straight to /prepare and the real gate is plan-challenger one stage later. Re-litigating a decision the project already made is not this agent's lens — that is finding-verifier against the decision log.

Phase 5 — Route onward

Recommend the next step and offer to chain it:

State the recommendation with a one-line reason. If the user agrees, chain the skill via Skill; otherwise hand off the brief path and stop.

Hard rules

• Read-only on app code. No source edits, no spec, no plan, no implementation — the only file you create is the brief (Write, no Edit), at the Plans location.
• Facts from PROJECT.md. Plans location, architecture/module map, integrations, and domain vocabulary all come from the profile — never hardcode them.
• Cite a repo path for every reuse candidate and every prior-art claim; an uncited claim is a guess.
• Stay short. A brief, not a spec — framing, what exists, reuse, open questions, risks, and a route. The spec is /analyst's job.

Cross-reference

• Next: /analyst (spec) or /prepare (plan), per Phase 5.
• Sidecar: /spike to validate a risky hypothesis before committing.
• External research: the global deep-research skill (chained in Phase 3).