Feature Discovery

Purpose

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

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

Rules

• Stay read-only. Do not edit files.
• Prefer CLI tools over MCP.
• Use

  rg

  first for text search.
• Use

  git

  ,

  git grep

  ,

  find

  , package metadata, local docs, and tests as needed.
• When the active agent runtime supports sub-agents and the user has allowed them, use explorer agents for independent read-only discovery work.
• Use multiple explorer agents in parallel when projects, modules, or evidence streams can be investigated independently.
• Keep the main session responsible for synthesis, evidence quality, uncertainty calls, and final reporting.
• Do not run

  git fetch

  ,

  git pull

  , installs, migrations, or destructive commands.
• Scan the codebase before using git history.
• Review git commits only when code scanning does not explain the topic clearly.
• If git history is needed, review only the last 2 months.
• Back concrete claims with file paths, symbols, commands, tests, docs, or commits.
• Separate confirmed facts from inference.
• Do not invent memory or rationale.

Workflow

1. Parse the request:
   • Identify project codes from

     Projects Affected

     .
   • Identify the topic from

     What

     .
   • Note explicit constraints, dates, branches, modules, or terms.
2. Locate project roots:
   • Find relevant git roots and package/app boundaries.
   • Map project codes to folders by repo names, package metadata, READMEs, config, or naming conventions.
   • If a project code cannot be mapped, state that early and continue best-effort.
3. Discover the topic:
   • Search exact terms from

     What

     .
   • Search likely aliases, route names, component names, API paths, config keys, env vars, table names, filenames, and test names.
   • Trace definitions to callers.
   • Trace user-facing flows from entry points to lower-level services.
   • Include tests, docs, configs, migrations, routes, background jobs, and feature flags when relevant.
   • If using explorer agents, split work by project, module, or evidence type and require each explorer to return file paths, symbols, commands, and uncertainty.
4. Use git history only if needed:
   • Limit to the last 2 months.
   • Look for commits touching discovered files or mentioning the topic.
   • Use commit history to explain why or when behavior changed, not as the primary source of truth.
5. Validate findings:
   • Cross-check code against tests, docs, configs, and usage sites.
   • Mark dead code, unclear ownership, missing tests, contradictory evidence, and unverified assumptions.
   • Avoid broad claims when evidence is partial.

Search Defaults

rg -n "exact topic|likely alias|route|config_key" .
find . -maxdepth 4 \( -name package.json -o -name README.md -o -name .git \)
git grep -n "term"
git log --since="2 months ago" --oneline --all -- <relevant-path>

Output Format

# Feature Discovery: [Topic]

## 1. Summary

- [Short answer: what this is and where it lives.]
- [Main finding or current behavior.]
- [Important caveat, if any.]

## 2. What It Does

- [Describe the behavior in product/domain terms.]
- [Mention inputs, outputs, side effects, or user-visible result.]
- [Mention relevant project(s).]

## 3. How It Works

- [Step-by-step flow.]
- [Key files, functions, classes, routes, configs, jobs, services, or data models.]
- [Important conditions, flags, dependencies, or error paths.]

## 4. Where It Is Used

- [Usage site 1 with file reference.]
- [Usage site 2 with file reference.]
- [Tests/docs/configs that confirm usage.]

## 5. Why It Was Needed / Memory

- [Use conversation memory, local docs, comments, issues, or recent commits if available.]
- [If not found: "No reliable rationale found in available memory, docs, comments, or recent git history."]

## 6. Risks, Gaps, And Recommended Next Checks

- [Risk, ambiguity, dead code, missing test, or unclear owner.]
- [Recommended next check.]
- [State what could not be verified.]

Evidence Style

- `apps/admin/src/routes/users.ts`: defines the route.
- `packages/auth/src/session.ts`: validates the session before the route runs.
- `apps/admin/src/routes/users.test.ts`: covers the disabled-user case.
- Commit `abc1234` from 2026-04-12: introduced the feature flag.

Quality Bar

• what the thing is
• what it does
• how it works
• where it is used
• what evidence supports the explanation
• what remains uncertain