git:20260328.3507ecf to git:20261016.a8588fa
116 added, 167 removed. Audit A to A.
---
name: meta-methodology-research-methodology
description: Investigation flow (Glob -> Grep -> Read), evidence-based research with file:line references, structured output format for AI consumption. Use for pattern discovery, implementation research, and codebase investigation.
---
# Research Methodology
- > **Quick Guide:** Investigation flow is Glob -> Grep -> Read. All claims require file:line evidence. Structured output format for AI consumption. Read-only operations only. Verify every path before reporting.
-
- ---
+ > **Quick Guide:** Research hands another agent findings it can act on without repeating the search. Locate files by name, narrow by content, then read the files that carry the answer; every claim names the file, line range and symbol it came from, and a search that found nothing is reported together with the search. Two tool facts change what a result means. A search that returns nothing is not proof of absence: the Grep tool skips gitignored files, Glob's list is capped, and a long file's Read can come back partial. And on macOS, Linux and WSL, Claude Code leaves the Glob and Grep tools out of the default tool set, so the same steps run through `find` and `grep` in the shell.
**Detailed Resources:**
- - [examples/core.md](examples/core.md) - Investigation templates, output formats, progress tracking
- - [reference.md](reference.md) - Decision frameworks, anti-patterns, quality checklist
+ - [examples/core.md](examples/core.md) — the search sequence, the evidence shape, the findings template, path and absence checks, scoping, progress notes, and a worked example
+ - [reference.md](reference.md) — what each search tool skips and where it truncates, which tools a session has, and the pre-report checklist
---
- <critical_requirements>
+ ## Which path applies
- ## CRITICAL: Before Any Research
+ - **The instructions you are working under define a report shape** — fill that shape; this skill supplies the evidence each entry carries and the checks it passes.
+ - **No report shape is given** — use the findings template in [examples/core.md](examples/core.md#pattern-3-structured-findings).
- > **All research must be evidence-based with file:line references**
+ ---
- **(You MUST read actual code files before making any claims - never speculate about patterns)**
+ <critical_requirements>
- **(You MUST verify every file path exists using Read tool before including it in findings)**
+ ## Before reporting findings
- **(You MUST include file:line references for all pattern claims)**
+ **Open a file before its path or contents enter the findings.** A path inferred from convention is a guess, and the agent acting on it opens a file that is not there.
- **(You MUST NOT attempt to write or edit any files - you are read-only)**
+ **Give every claim the file, line range and symbol it came from.** The range lets the reader check the claim in one read; the symbol lets them find it again once an edit has moved the lines.
- **(You MUST produce structured, AI-consumable findings that downstream agents can act on)**
+ **Report a search that found nothing together with the search.** An absence is only as strong as the pattern, path and filters behind it, and the reader can rerun those but not your conclusion.
+ **Leave the code as you found it while you investigate.** A change made mid-investigation alters the evidence, and the reader can no longer tell which state a claim was read from.
+
</critical_requirements>
---
- **Auto-detection:** Pattern research, implementation discovery, architecture investigation, API cataloging
-
- **When to use:**
-
- - Discovering how patterns are implemented in a codebase
- - Cataloging components, APIs, or architectural decisions
- - Finding similar implementations to reference for new features
- - Understanding existing conventions before implementation
+ **Auto-detection:** where is X defined, how does X work in this codebase, find similar implementations, catalogue the components / endpoints / commands, pattern discovery, codebase investigation, architecture investigation, API catalogue, file:line references, usage count, Files to Reference, research findings, Glob, Grep
- **Key patterns covered:**
+ **Applies to:**
- - Investigation flow (Glob -> Grep -> Read)
- - Evidence-based claims with file:line references
- - Structured output format for AI consumption
- - Self-correction triggers for research quality
- - Progress tracking for complex research
+ - Finding where a pattern lives and how consistently it is followed
+ - Cataloguing what exists — components, APIs and endpoints, commands, configuration, architectural decisions
+ - Finding the closest existing implementation before building something new
+ - Writing findings another agent acts on without repeating the search
- **When NOT to use:**
+ **Handled elsewhere:**
- - When you need to implement code (research informs, doesn't replace implementation)
- - When you need to create specifications (research feeds into specs, but doesn't produce them)
- - When you need to review existing code for quality (research discovers patterns, doesn't judge them)
+ - Making the change the findings point at — research ends at the location, and the implementation and its tests are a separate step
+ - Judging whether the code is good — research reports what is there and how often; quality and security verdicts belong to review
+ - Turning findings into a specification — scope and acceptance criteria belong to planning
---
<philosophy>
- ## Philosophy
-
- Research is investigation, not speculation. Every claim must be backed by evidence from actual code files. The output format is designed for consumption by other AI agents, not humans - this means structured sections, explicit file paths, and actionable recommendations.
-
- **Core Research Principles:**
-
- 1. **Evidence First** - Never claim a pattern exists without reading the file
- 2. **Verify Paths** - Every file path in findings must be confirmed with Read
- 3. **Be Specific** - Line numbers, not vague references
- 4. **Be Actionable** - Tell developers exactly which files to reference
- 5. **Be Honest** - If you can't find something, say so
+ The reader of a finding did not watch the investigation. They cannot tell a claim that was read from one that was inferred, so the only claims worth handing over are ones they can check: a location, the code as it reads there, and the search that produced it. A finding they have to re-derive saved them nothing, and a wrong one costs more than none, because they build on it.
</philosophy>
---
- <patterns>
+ <decision_framework>
- ## Core Patterns
+ ## Which search first
- ### Pattern 1: Investigation Flow (Glob -> Grep -> Read)
+ ```text
+ What do you already know?
+ ├─ The symbol's name → its definition first (a language server's go-to-definition
+ │ where one is running, else a search for the declaration),
+ │ then its references
+ ├─ Text the code contains → content search, scoped to the directory if known
+ ├─ What the file would be called → name search, then read the likeliest match
+ └─ Nothing yet → list the top-level layout, then search by name
+ ```
- The three-step investigation flow ensures thorough and efficient research.
+ ## How far to go
- #### Flow Structure
+ The question sets the deliverable, and the deliverable sets the depth.
+ ```text
+ "How does X work?" → X's flow: 2–3 exemplary files read end to end
+ "What exists for X?" → a catalogue with counts; 1–2 files sampled
+ "Find similar to Y" → the closest match, read completely
+ "How should I implement Z?" → the existing code to follow, in reading order
+ "Patterns for X?" → several instances, and where they vary
```
- 1. GLOB - Find candidate files
- ├── Use file patterns (*.tsx, *store*, *auth*)
- ├── Target specific directories when known
- └── Cast wide net initially, narrow later
- 2. GREP - Search for keywords/patterns
- ├── Use content patterns (useQuery, export const)
- ├── Narrow down to relevant files
- └── Note frequency of pattern usage
+ ## When to stop
- 3. READ - Examine key files completely
- ├── Don't skim - read files that matter
- ├── Note line numbers for key patterns
- └── Understand the full context
+ ```text
+ Is the question that was asked answered?
+ ├─ NO → keep going, inside the question
+ └─ YES → Does every claim carry a location you read?
+ ├─ YES → report
+ └─ NO → read the file now, or drop the claim
```
- **Why this flow:** Glob finds files efficiently, Grep narrows to relevant content, Read provides complete understanding. This prevents speculation and ensures evidence-based claims.
-
- For detailed code examples, see [examples/core.md](examples/core.md#pattern-1-investigation-flow).
-
- ---
-
- ### Pattern 2: Evidence-Based Claims
-
- Every claim in research findings must have supporting evidence with file paths and line numbers. Include the file path, line range, usage count, actual code snippet, and verification status.
-
- **Why this matters:** Downstream agents will use your research to implement features. Inaccurate or unverified claims will lead them astray.
-
- For the claim structure template and good/bad comparison examples, see [examples/core.md](examples/core.md#pattern-2-evidence-based-claims).
+ </decision_framework>
---
- ### Pattern 3: Structured Output Format
-
- Research findings follow a consistent structure for AI consumption. Every output includes: Research Summary, Patterns Found (with file:line evidence), Files to Reference table, Recommended Approach, and Verification Checklist.
-
- **Why structured:** Other AI agents parse this output. Consistent structure enables reliable extraction of relevant information.
-
- For the complete output template, see [examples/core.md](examples/core.md#pattern-3-structured-output-format).
+ <patterns>
- </patterns>
+ ## Core patterns
- ---
+ ### Pattern 1: Locate, Narrow, Read
- <self_correction_triggers>
+ Find candidates by name, narrow them by content, then read the files that carry the answer. Each step is cheaper than the next, so the expensive reads land only on files already shown to matter.
- ## Self-Correction Checkpoints
+ ```text
+ Glob "src/**/*error*" → 6 candidate files
+ Grep "extends AppError" in src/ (count) → 4 matches in 4 files
+ Read src/errors/app-error.ts → class AppError, lines 8–31
+ ```
- **If you notice yourself:**
+ Where the session has no Glob or Grep tool, `find` and `grep` in the shell are the same two steps.
- - **Reporting patterns without reading files first** -> STOP. Use Read to verify the pattern exists.
- - **Making claims about architecture without evidence** -> STOP. Find specific file:line references.
- - **Attempting to write or edit files** -> STOP. You are read-only. Produce findings instead.
- - **Providing generic advice instead of specific paths** -> STOP. Replace with concrete file references.
- - **Assuming APIs without reading source** -> STOP. Read the actual source file.
- - **Skipping file path verification** -> STOP. Use Read to confirm every path you report.
- - **Expanding scope beyond the research question** -> STOP. Answer what was asked, no more.
- - **Giving implementation opinions when asked for research** -> STOP. Report findings, not recommendations.
+ Full walk-through: [examples/core.md](examples/core.md#pattern-1-locate-narrow-read)
- </self_correction_triggers>
+ ### Pattern 2: Evidence-Based Claims
- ---
+ One claim, one location: the file, the line range, the symbol, the code as it reads there, and how many instances exist.
- <post_action_reflection>
+ ```text
+ AppError base class — src/errors/app-error.ts:8-31, class AppError
+ Usage: 4 subclasses (Grep "extends AppError" in src/, count mode → 4)
+ ```
- ## Post-Action Reflection
+ Full shape, beside the version that fails: [examples/core.md](examples/core.md#pattern-2-evidence-based-claims)
- **After each research action, evaluate:**
+ ### Pattern 3: Structured Findings
- 1. Did I verify all file paths exist before including them?
- 2. Are my pattern claims backed by specific code examples?
- 3. Have I included line numbers for key references?
- 4. Is this research actionable for the consuming agent?
- 5. Did I stay within the scope of the research question?
- 6. Did I miss any obvious related patterns?
+ Where no report shape is given: a summary, the patterns found, the files to read in order, the existing files to follow, the gaps, and a verification table that includes the searches that came back empty.
- Only report findings when you have verified evidence for all claims.
+ ```text
+ ## Research Summary ## Recommended Approach
+ ## Patterns Found ## Gaps
+ ## Files to Reference ## Verification Checklist
+ ```
- </post_action_reflection>
+ Full template: [examples/core.md](examples/core.md#pattern-3-structured-findings)
- ---
+ ### Pattern 4: Verifying Paths and Absences
- <progress_tracking>
+ A path enters the findings once the file has been opened, never from convention; a path seen only in a search result goes under Gaps as not read. An absence enters with its search, after a control — a search for something known to be there, over the same path with the same filters — has shown the search can find text at all.
- ## Progress Tracking
+ ```text
+ Grep "jwt" -i in src/ → 0 matches
+ Grep "session" -i in src/ → 12 matches (control: the search works here)
+ Finding: no JWT handling in src/ — gitignored files not searched
+ ```
- For complex research spanning multiple areas, use the progress tracking template to maintain orientation. Track files examined, patterns found, and gaps identified.
+ Full code: [examples/core.md](examples/core.md#pattern-4-verifying-paths-and-absences)
- See [examples/core.md - Pattern 6](examples/core.md#pattern-6-progress-tracking-for-complex-research) for the full template.
+ ### Pattern 5: Scope to the Question
- </progress_tracking>
+ Report what the question asked for. Material outside it becomes one line under Gaps where it bears on the answer, and is left out where it does not.
- ---
+ ```text
+ Asked: How does the API authenticate requests?
+ Report: the session flow, the route guard, the files to read first
+ Leave: database schema, deployment, the client's login form
+ ```
- <integration>
+ Full code: [examples/core.md](examples/core.md#pattern-5-scope-to-the-question)
- ## Integration Guide
+ ### Pattern 6: Progress Notes for Long Research
- **Research is read-only.** Never write or edit files during research. Produce structured findings that other agents can act on.
+ Research spanning several packages keeps a running note — files examined, patterns found with their counts, gaps — so a compaction or a handoff resumes from the note rather than from memory.
- **Output consumers:** Any agent that needs to understand codebase patterns before implementing, specifying, or reviewing code.
+ Full template: [examples/core.md](examples/core.md#pattern-6-progress-notes-for-long-research)
- </integration>
+ </patterns>
---
<red_flags>
- ## RED FLAGS
-
- **High Priority Issues:**
-
- - Claiming patterns without file:line evidence
- - Including file paths that weren't verified with Read
- - Speculating about code structure without investigation
- - Providing implementation advice when asked for research
- - Missing verification checklist in output
-
- **Medium Priority Issues:**
-
- - Vague line references ("around line 50" instead of "lines 45-67")
- - Not reporting usage counts when available
- - Skipping the Files to Reference section
- - Not noting gaps or inconsistencies found
-
- **Common Mistakes:**
+ ## Red flags
- - Assuming file locations from convention without checking
- - Inferring patterns from file names without reading content
- - Mixing research findings with opinions
- - Expanding scope without asking
+ **Misleads the agent acting on the findings:**
- **Gotchas & Edge Cases:**
+ - A path written from convention (`utils/formatDate.ts`) rather than from a search result — the reader opens a file that is not there. Write the path the search returned.
+ - A pattern inferred from a file name, or from what codebases in that framework usually do — it describes other codebases. Read the file and quote it.
+ - An API described from a call site — one caller's arguments, not the contract. Follow it to the declaration.
+ - "Around line 50", "in the auth module", "follow the existing convention" — the reader repeats your search. Give the file, the range and the symbol.
+ - A usage count read off a listing of matching lines — the listing stops at the tool's result limit, so the count comes out low. Count with the count mode, whose total covers every match.
+ - A universal ("all routes use this") with no count behind it — the one exception the reader trusted you about breaks their change. State the count and the search.
+ - Implementation code, or verdicts on quality, in findings that asked for locations — an answer to a question nobody asked, arriving without the context the implementer has. Name the existing file to follow.
+ - Findings with no reading order — the reader opens files at random. Rank the two or three to open first.
- - Some patterns exist but are deprecated (check for `@deprecated` comments)
- - Tests may show patterns that differ from production code
- - Config files may override patterns in source code
- - Monorepo patterns may vary by package
+ **Surprising behaviour:**
- See [reference.md](reference.md) for anti-pattern code examples and the quality checklist.
+ - The Grep tool skips gitignored files, so "0 matches" says nothing about generated code, build output or installed dependencies. Glob applies no gitignore filtering by default, so it lists files Grep never searches.
+ - Glob's results are sorted by modification time, not relevance, and capped; a truncation flag means the list is partial.
+ - A Read of a long file can return only its first page, marked `PARTIAL view` — "the file does not contain X" after that read is unverified.
+ - Grep patterns are ripgrep regex, so `interface{}` has to be written `interface\{\}`. On older Claude Code builds a pattern ripgrep rejected, or a path the tool could not read, came back as no matches rather than as an error.
+ - Line numbers describe the file as it was read. A later edit — another agent's included — moves them, which is why the symbol travels with the range.
+ - Tests can show a pattern production code has moved away from, configuration can override what the source suggests, and each package in a monorepo can follow its own convention. Say which one a finding came from.
+ - A pattern still in wide use may be marked `@deprecated`; report it as deprecated rather than as the convention to copy.
</red_flags>
-
- ---
-
- <critical_reminders>
-
- ## CRITICAL REMINDERS
-
- > **All research must be evidence-based with file:line references**
-
- **(You MUST read actual code files before making any claims - never speculate about patterns)**
-
- **(You MUST verify every file path exists using Read tool before including it in findings)**
-
- **(You MUST include file:line references for all pattern claims)**
-
- **(You MUST NOT attempt to write or edit any files - you are read-only)**
-
- **(You MUST produce structured, AI-consumable findings that downstream agents can act on)**
-
- **Failure to follow these rules will produce inaccurate research that misleads downstream agents.**
-
- </critical_reminders>