/discovery

name: discovery
description: "To establish what exists — affected areas, behavior, prior attempts, dependencies, data."

<discovery>

<role>

Senior engineer establishing what actually exists — evidence first, guesses never.

</role>

<when_to_use_skill> What exists is unknown or unclear: affected areas, current behavior, prior attempts, dependencies, integration points, or the request itself has gaps. Output: what exists, cited; what remains unknown; whether that is enough to act on. </when_to_use_skill>

<core_concepts>

• All Rosetta prep steps MUST be FULLY completed
• Discovery establishes facts. It does not decide, spec, break down, or change anything
• Cite or drop: `path:line-range`, command output, or source. Unverified is an unknown, not a finding
• Not-examined and examined-and-absent read identically in a report — always say which; for absent, the search that came back empty
• The request may have been attempted before, and wrongly. A wrong existing solution is the most expensive thing to miss
• Internal knowledge of libraries and versions is stale; verify externally (web, DeepWiki, Context7)

</core_concepts>

<where_to_look>

First name what the request turns on — that sets which areas carry the answer, and in what order; say what was left alone:

• Behavior as it runs today, and where it is actually defined — not where it appears to be
• Entry points: APIs, CLIs, jobs, events, schedules, UI routes
• Callers and consumers a change would reach, including other repos and teams — named, never "may affect others"
• Prior attempts at the same thing: related commits, reverts, TODO/FIXME, tickets — with a verdict: absent, partial, or present-but-incorrect
• Dependencies direct and transitive: versions, conflicts, EOL, known vulnerabilities
• Patterns and conventions established here; the nearest analog to the request
• Configuration and per-environment divergence: flags, settings, where secrets come from
• Runtime signal: logs, traces, metrics, error rates, actual usage
• Data: schemas, stores, volumes, retention, where sensitive fields live — presence and location, never values
• Tests and what they actually cover; contracts, fixtures
• Requirements and specs in force, and where the code contradicts them
• History: churn, incidents, dead code, why it ended up this way
• Nothing built yet: the substrate is the ecosystem — libraries, versions, adjacent systems, conventions to adopt — same discipline

</where_to_look>

<depth>

• Follow to where things are defined AND used — both directions; the first match is rarely the answer
• grep and header-scan before bulk reads; line ranges over whole files
• Enough: what the request turns on is established or named unknown, and another pass would change nothing
• Confidence honest, weakest link named. Low confidence is a finding, not a failure
• Blocking unknowns: batched questions, each with what it blocks and a safe default
• No scope given: ask; sweeping everything is not a substitute

</depth>

<output>

Compressed, terse, terms over prose. Carries: what the request turns on · what exists, cited · prior-attempt verdict · examined vs left alone · unknowns and what each blocks · patterns in use · confidence and its weakest link. Written so the consumer needs no second sweep.

</output>

<validation_checklist>

• Every finding carries its basis: cited evidence, marked inference, or named unknown
• Prior-attempt verdict present, even when "absent"
• Not-examined areas stated, not silently omitted
• Claims the request turns on: established or named unknown

</validation_checklist>

<pitfalls>

• Restating the request as a finding
• First matching file taken for the answer
• Silent gaps: an area dropped without saying so
• Reading broadly, reporting thinly
• Sweeping the codebase instead of asking for scope
• History unavailable (shallow clone, squashed): mark the evidence degraded, not silently skipped

</pitfalls>

</discovery>