# Researching > Use when you need to understand how an existing codebase works and/or survey external prior work (papers, methods, tools) before planning or changing something. Traces function call paths, maps module dependencies, searches academic papers and documentation, compares library alternatives. Triggers: research the codebase, how does X work, where is X implemented, what tools or libraries exist for X, prior art on X, has this been done before, survey approaches to X. - Skill: `uw-ssec/researching` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds add uw-ssec/researching` - Raw SKILL.md: https://api.skillmd.com/api/skills/uw-ssec/researching/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: uw-ssec (https://skillmd.com/u/uw-ssec) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/uw-ssec/researching --- # Researching Build the context a task needs by investigating the current codebase and/or external prior art in one pass, then synthesizing a single research document that feeds planning. Run the internal dimension, the external dimension, or both. ## Interaction mode Leans **Collaborative** by default; see `ai-research-workflows:using-research-workflows` for the full protocol. ## Checklist Work through these in order and track them as tasks. Do not skip the review gates (steps 5, 7, and 8): 1. **Explore context** — the request, existing `docs/rse/specs/` (and legacy `.agents/`) docs, recent commits 2. **Scope** — internal / external / both; what counts as relevant; depth 3. **Propose the research plan** — sub-questions + sources; get a quick OK 4. **Investigate** — run the codebase and/or prior-art pass 5. **Present findings** — in sections; confirm understanding *before* writing anything out 6. **Write the research document** — `docs/rse/specs/research-.md` from the template 7. **Self-review** — read the written doc with fresh eyes; fix issues inline 8. **User reviews the document** — have them go through the written doc before you move on 9. **Hand off** — point to the next skill ## Process Scope → plan → investigate → present → write → self-review → user review → hand off. ### 1. Explore context Read the request. Scan `docs/rse/specs/` (then legacy `.agents/`) for existing research and plan documents (`research-*.md`, and legacy `prior-art-*.md`). Note recent commits if relevant. ### 2. Scope the question Establish: the precise question; whether it needs **internal** codebase research, **external** prior-art research, or **both**; what counts as relevant; and the desired depth. In Collaborative mode ask one focused question at a time; in Direct mode infer scope from the request and state it before proceeding. ### 3. Propose the research plan Before investigating, present the decomposition: the codebase sub-questions you will trace and/or the prior-art sources and dimensions you will search. Get a quick OK (Collaborative) or state it and proceed (Direct). ### 4. Investigate Run the dimension(s) in scope: - **Codebase pass** — see `references/codebase-research.md` - **Prior-art pass** — see `references/prior-art-research.md` Both passes may surface gaps and light, clearly-labeled observations; defer deep critique and design decisions to planning or validation. ### 5. Present findings Present synthesized findings in sections (codebase first, then prior art), confirming understanding as you go. Use `file:line` anchors for code and citations for external sources. ### 6. Write the research document Derive a slug (lowercase, hyphenated). Read the template: `assets/research-template.md`. Fill the sections that apply and write to `docs/rse/specs/research-.md`. Omit sections for any dimension not investigated. If the internal pass ran, record the codebase state you researched against — the commit SHA (`git rev-parse --short HEAD`) and the date — so `file:line` findings can be re-checked as the code evolves. ### 7. Self-review Before showing the document, read it through with fresh eyes and fix issues inline: - **Placeholders** — no "TBD"/"TODO", empty sections, or vague findings. - **Anchors & citations** — every codebase finding cites a `file:line`; every prior-art claim cites a source. - **Consistency & coverage** — sections don't contradict, the synthesis matches the findings, and every scoped sub-question is answered (or its gap is named). Confirm the doc meets the Quality checklist below. ### 8. User reviews the document Surface the written document and let the user go through it before you move on: > Research doc written to `docs/rse/specs/research-.md`. Please review it and tell me if anything is missing or off before we move on to planning. In Collaborative mode, wait for their response; if they request changes, revise and re-run the self-review. In Direct mode, present the doc and proceed, noting it is ready for their review. ### 9. Hand off Point to the next skill — usually `ai-research-workflows:planning-implementations` (or `ai-research-workflows:running-experiments` when an approach is uncertain). ## Common Mistakes - **Researching both dimensions when one suffices** — scope first; don't search external prior art for a question that is purely about current code, or vice-versa. - **Uncited prior-art claims** — every external factual claim needs a primary-source citation; label secondary sources as such. - **Vague codebase findings** — every code finding cites a specific `file:line`; "it's somewhere in auth" is not a finding. - **Skipping the disconfirming search** — for prior art, actively search for limitations, critiques, and failures, not just supporting evidence. - **Turning research into a rewrite plan** — surface gaps and light observations, but defer detailed design and critique to planning/validation. ## Quality checklist - [ ] Scope (internal / external / both) was established and stated - [ ] Codebase findings carry `file:line` references (if the internal pass ran) - [ ] Every prior-art claim is cited and ≥1 disconfirming search ran (if the external pass ran) - [ ] Synthesis connects findings and names gaps - [ ] Codebase state recorded (commit SHA + date) if the internal pass ran - [ ] Template used; saved to `docs/rse/specs/research-.md` - [ ] Document is self-contained - [ ] Findings presented before writing; written doc self-reviewed and offered for user review before hand-off - [ ] Next skill suggested ## Cross-references - Feeds `ai-research-workflows:planning-implementations`. - For comparing uncertain approaches with real code, use `ai-research-workflows:running-experiments`. - Surveyed automatically by `ai-research-workflows:using-research-workflows`.