Codebase Evidence Review
Purpose
Produce answers that are grounded in the actual repository instead of product assumptions, docs-only reasoning, or visible UI labels. The user's repeated pattern is to ask for the real source path, real control fields, and real activation conditions before deciding whether to patch.
When to use
Use this skill for:
- Codebase exploration, architecture tracing, source-backed explanations, PR/spec reviews, and bug triage.
- Questions that compare a visible symptom with implementation reality, such as model labels, Slack threading, runtime ownership, or route behavior.
- Review requests where findings must be actionable and tied to exact locations.
Do not use it for pure brainstorming, copy editing, or tasks where the user explicitly says not to inspect files.
Workflow
Orient on the repo
- Run
pwd and inspect the nearest AGENTS.md.
- Use
rg --files or fd to find likely entrypoints, tests, config, and docs.
- Read the smallest set of files that can answer the question.
Trace the primary path
- Identify the first real entrypoint: CLI command, route handler, monitor, hook, service, component, or worker.
- Follow data and control flow to the final side effect.
- Name the decisive symbols: functions, classes, fields, env vars, config keys, routes, and storage tables.
Separate facts from hypotheses
- Mark as fact only what is proven by source, local files, tests, logs, or a direct command.
- Treat UI labels, model names, stale docs, and memory summaries as clues until source confirms them.
- If external docs are needed because the code calls a third-party API, use primary docs and cite them.
Check for real enablement
- Distinguish "code exists" from "this path is active."
- Verify wiring: imports, route registration, package scripts, feature flags, env gates, config defaults, and runtime command path.
- For reviews, include missing tests only when they would catch the actual risk.
Report with evidence
- Findings first for reviews, ordered by severity.
- For explanations, start with the direct answer, then show the source path that proves it.
- Use exact local file links with line numbers when available.
Review Output
For review-style tasks, use:
**Findings**
- [P1] Title
File: path:line
Why it matters:
Fix:
**Open Questions**
- ...
**Verification**
- Command/result or why not run.
For explanation-style tasks, use:
Direct answer:
Evidence:
- path:line -> what it proves
- path:line -> what it proves
What could go wrong:
- ...
Common Failure Modes
| Risk |
Likelihood |
Mitigation |
| Broad greps create noise and hide the real path |
High |
Narrow quickly to entrypoints, helpers, and final send/side-effect code |
| Visible UI label is mistaken for implementation truth |
Medium |
Check the source fields and config that produce the behavior |
| A doc/spec is treated as shipped behavior |
Medium |
Verify route registration, scripts, tests, and runtime defaults |
| A code path exists but is not enabled |
High |
Check imports, feature gates, env, and package scripts |
Key Principle
The answer is not "what seems likely"; the answer is the smallest source-backed path that explains the behavior.
1---2name: codebase-evidence-review3description: Use this when the user asks to research, review, audit, explain, or trace behavior in a codebase, repository, PR, spec, architecture doc, or local implementation. This skill should trigger for phrases like "基于 codebase", "从头梳理", "review", "audit", "看源码", "研究这份 codebase", "这个流程怎么跑", or when a symptom may be explained by local source. It enforces source-backed findings, exact file/function references, and verification before claims.4---56# Codebase Evidence Review78## Purpose910Produce answers that are grounded in the actual repository instead of product assumptions, docs-only reasoning, or visible UI labels. The user's repeated pattern is to ask for the real source path, real control fields, and real activation conditions before deciding whether to patch.1112## When to use1314Use this skill for:15- Codebase exploration, architecture tracing, source-backed explanations, PR/spec reviews, and bug triage.16- Questions that compare a visible symptom with implementation reality, such as model labels, Slack threading, runtime ownership, or route behavior.17- Review requests where findings must be actionable and tied to exact locations.1819Do not use it for pure brainstorming, copy editing, or tasks where the user explicitly says not to inspect files.2021## Workflow22231. **Orient on the repo**24 - Run `pwd` and inspect the nearest `AGENTS.md`.25 - Use `rg --files` or `fd` to find likely entrypoints, tests, config, and docs.26 - Read the smallest set of files that can answer the question.27282. **Trace the primary path**29 - Identify the first real entrypoint: CLI command, route handler, monitor, hook, service, component, or worker.30 - Follow data and control flow to the final side effect.31 - Name the decisive symbols: functions, classes, fields, env vars, config keys, routes, and storage tables.32333. **Separate facts from hypotheses**34 - Mark as fact only what is proven by source, local files, tests, logs, or a direct command.35 - Treat UI labels, model names, stale docs, and memory summaries as clues until source confirms them.36 - If external docs are needed because the code calls a third-party API, use primary docs and cite them.37384. **Check for real enablement**39 - Distinguish "code exists" from "this path is active."40 - Verify wiring: imports, route registration, package scripts, feature flags, env gates, config defaults, and runtime command path.41 - For reviews, include missing tests only when they would catch the actual risk.42435. **Report with evidence**44 - Findings first for reviews, ordered by severity.45 - For explanations, start with the direct answer, then show the source path that proves it.46 - Use exact local file links with line numbers when available.4748## Review Output4950For review-style tasks, use:5152```markdown53**Findings**54- [P1] Title55 File: path:line56 Why it matters:57 Fix:5859**Open Questions**60- ...6162**Verification**63- Command/result or why not run.64```6566For explanation-style tasks, use:6768```markdown69Direct answer:7071Evidence:72- path:line -> what it proves73- path:line -> what it proves7475What could go wrong:76- ...77```7879## Common Failure Modes8081| Risk | Likelihood | Mitigation |82| --- | --- | --- |83| Broad greps create noise and hide the real path | High | Narrow quickly to entrypoints, helpers, and final send/side-effect code |84| Visible UI label is mistaken for implementation truth | Medium | Check the source fields and config that produce the behavior |85| A doc/spec is treated as shipped behavior | Medium | Verify route registration, scripts, tests, and runtime defaults |86| A code path exists but is not enabled | High | Check imports, feature gates, env, and package scripts |8788## Key Principle8990The answer is not "what seems likely"; the answer is the smallest source-backed path that explains the behavior.
kaichen