| name | investigate-codebase |
| description | Read-only codebase investigation — trace flows, map dependencies, explain behavior with evidence. Use with /investigate before refine-us, spike US, or architecture updates. |
| allowed-tools | Read, Glob, Grep, Bash |
Investigate codebase (Meridian)
Answers one concrete question about how the code works — with paths, flow, and confidence. No product code, no delivery rows unless manager asks.
Operator workflow
| Workflow | Purpose |
|---|
/investigate | Read-only trace and explanation report |
Selective reading
| File | When to read |
|---|
references/investigation-checklist.md | Mandatory — every /investigate run |
Target US via meridian_delivery.py show US-XXXX --full | When $ARGUMENTS is US-XXXX |
docs/05_architecture.md | When question touches boundaries or modules |
docs/inventory/as-is.md | Brownfield — known capabilities |
When to trigger
/investigate or "how does X work?", "where is Y?", "trace this flow"- Before
/refine-us when Plan needs code facts
- Spike prep (timeboxed US optional — see
scrum-meridian-map.md)
- Manager asks to compare implementation vs assumption
Do not use for:
- Full brownfield documentation →
/document-project
- Phase doc drift →
/audit-docs
- Security audit →
/security-review
- Implementing a fix →
/implement-us after /refine-us
Procedure
Phase 0 — frame the question
- Restate the question in one sentence.
- Set depth:
quick | medium | thorough (default medium).
- Set scope: whole repo, path prefix, or US Plan boundaries.
- If question is vague → ask one clarifying question, then proceed with stated assumptions.
Phase 1 — orient
- Manifests (
package.json, pyproject.toml, etc.) and top-level layout.
- README and
docs/05_architecture.md if present.
- Grep for symbols, routes, env keys, feature names from the question.
Phase 2 — trace
- Identify entry points (HTTP route, CLI, job, event handler).
- Follow call chain: handler → service → store → external API.
- Note config, feature flags, and test files as evidence.
- For
thorough: check alternate paths, error handling, and one consumer.
Phase 3 — report
Use output template in references/investigation-checklist.md.
- Answer first (plain language).
- Evidence:
path:line or path + symbol.
- Flow diagram (text):
A → B → C.
- Confidence:
high | medium | low + what would raise it.
- Handoff: none |
/refine-us | /architecture | spike US | /update-decisions-log.
Phase 4 — persistence (optional)
- Material product understanding change →
update-decisions-log (run date first).
- Implementation needed → suggest spike US or
/create-us — do not create without manager ask.
Forbidden
| Forbidden | Why |
|---|
| Product code | developer + /implement-us |
| Create US/epic/version | backlog-refiner / product-owner |
Mark docs approved | Human only |
Guess without labeling low confidence | Report integrity |
Output
Pergunta:
Resposta:
Evidência:
Fluxo:
Confiança: high | medium | low
Lacunas:
Handoff:
Next:
