Feature Discovery

# Feature Discovery

## Purpose

Perform a read-only discovery pass over one or more projects. Explain what the requested topic does, how it works, where it is used, and why it may have been needed. Return the discovery report in chat only.

Use this skill for prompts shaped like:

```markdown
Projects Affected: [Project Code], [Project Code]

What:
[FEATURE / ISSUE / BEHAVIOR / MODULE / WORKFLOW]
```

## Rules

- Stay read-only during discovery. Do not edit code, config, docs, native memory, ADRs, prompts, issues, generated artifacts, or discovery files while discovering.
- Never create or update `docs/discovery/` files. Discovery output is chat-only.
- `CONTEXT.md` edits and any artifact edits are separate follow-up actions. Before editing, show the exact file(s), proposed text or section changes, and reason. Only edit after explicit approval.
- Prefer CLI tools over MCP for codebase evidence.
- Use `rg` first for text search.
- Use `git`, `git grep`, `find`, `gh`, package metadata, local docs, issues, and tests as needed.
- Keep discovery scope thin. If intake spans many workflows or projects, split into slices and discover the first slice before expanding.
- Keep the human in charge. Discovery questions are for blocking clarifications only, not open-ended interrogation.
- Prefer code-as-source-of-truth over prose docs when evidence conflicts.
- When the runtime supports subagents and the user has allowed them, act as the orchestrator: dispatch read-only **Explorer** lanes for independent codebase discovery and **Researcher** lanes for external docs or dependency source. Use local subagents only — never cloud agents. See the `agents-md` `tool-calling.md` reference for the role-to-mechanism map per runtime.
- Run independent Explorer/Researcher lanes in parallel — by project, module, or evidence stream — and push long scans to local background where the runtime supports it.
- Keep the main session responsible for synthesis, evidence quality, uncertainty calls, conflict resolution, and final reporting. Subagents return summaries, not raw transcripts.
- Do not run `git fetch`, `git pull`, installs, migrations, or destructive commands.
- Scan the codebase before using git history.
- Do not write `docs/discovery/` files. Do not read legacy discovery files unless the user explicitly asks you to use a specific file. Discovery files can be stale; prefer current code, ADRs, CONTEXT, issues, tests, and fresh search.
- Check available context before doing broad GitHub issue discovery. Context can include the current conversation, AGENTS.md, `<artifacts-root>/CONTEXT.md`, ADRs under `<artifacts-root>/docs/adr/`, local docs, local issue caches, prior issue references, and prompt context.
- If external dependency internals are critical and local evidence is insufficient, optionally fetch targeted dependency source with `opensrc` and cite concrete files/functions. Keep fetch scope minimal.
- If available context identifies relevant GitHub issue numbers, URLs, titles, labels, milestones, or search terms, read all GitHub issues in that bounded set.
- If no reliable context exists for the topic, ask the user for approval before scanning broadly across GitHub issues. Explain that reading all related issues can take a long time.
- If approval for broad GitHub issue scanning is not granted, continue with code, docs, tests, local context, and git history, and state that broad GitHub issue scanning was skipped.
- Review git commits only when code scanning does not explain the topic clearly.