/iterate-research

name: iterate-research
description: Only use when the user explicitly invokes this skill by name.

Iterate Research

You are iterating on an existing research document based on user feedback.

Initial Setup:

When this command is invoked, check the task artifact directory from your system prompt for documents like `*research*.md` (NOT `*research-questions*.md` - `research-questions` documents are EXCLUDED) with `ls -La` (the directory may be a symlink - do NOT use regular `ls` or grep/glob tools). If you find a research document, read it and proceed.

If you see several research documents, ask the user which one to proceed with before reading any of them.

If you do not know what the artifact task directory is from your system prompt, respond with:

I'm ready to iterate on researching the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.

**IMPORTANT**: You may NEVER read `ticket.md`/`task.md` files or other files from the artifact directory which do not match the `*research*.md` pattern above unless such a file is explicitly asked for by the user.

Steps

1. **Read the existing document FULLY**:

• Use Read tool WITHOUT limit/offset to read the entire document at `docPath`
• Understand what research was previously conducted
• Don't read any other files in the rpi/ directory for the task, focus on the research document and the provided feedback.
• **DO NOT read ticket files** - research must stay objective about the current codebase.
• **If a document path was not provided:**
• List the contents of the task's artifact directory from your propmt. Run `ls -La .humanlayer/tasks/<task slug>` to find all related documents in the task directory. Do not use glob or grep, or use `ls -l` or `ls` without `-L` as the directory may be a symlink.

2. **Process the feedback**:

• If user requested additional research: Spawn sub-agents to investigate
• If user requested corrections: Update the document at the same path
• Keep the same YAML frontmatter and format

3. **Conduct additional research** (if needed):

• Spawn parallel sub-agent tasks for comprehensive research
• Use only the specialized research agents listed below. Do not use other agent types, including `general-purpose`, `Explore`, or `Plan`.
• Agent names differ by runtime. Use the exact name from the available agent list for the matching role (for example, `rpi:codebase-analyzer` where namespaced or `codebase-analyzer` where unprefixed).

**For codebase research:**

• **codebase-locator**: Find WHERE files and components live
• Finds relevant source files, configs, and tests
• Returns file paths organized by purpose
• **codebase-analyzer**: Understand HOW specific code works (without critiquing it)
• Traces data flow and key functions
• Returns detailed explanations with file:line references
• **codebase-pattern-finder**: Find examples of existing patterns (without evaluating them)
• Identifies conventions and patterns
• Returns code examples with locations

**For web research (only if user explicitly asks):**

• **web-search-researcher**: For external documentation and resources
• If used, instruct agents to return LINKS with their findings
• Include those links in the updated document

**Agent usage tips:**

• Start with locator agents to find what exists
• Then use analyzer agents on the most promising findings
• Run multiple agents in parallel when searching for different things
• Each agent knows its job - just tell it what you're looking for
• Don't write detailed prompts about HOW to search - the agents already know
• Keep the main agent focused on synthesis, not deep file reading

4. **Update document** (if changes needed):

• Update the document at the same `docPath`
• Add new findings to relevant sections

5. **Update the user**

• Read the final output template:

`Read({SKILLBASE}/references/research_final_answer.md)`

• Respond following the template exactly, include cloud permalinks if you have them.

Research Guidelines

Your job is to DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY:

• DO NOT suggest improvements or changes unless explicitly asked
• DO NOT perform root cause analysis unless explicitly asked
• DO NOT propose future enhancements unless explicitly asked
• DO NOT critique the implementation or identify problems
• DO NOT recommend refactoring, optimization, or architectural changes
• ONLY describe what exists, where it exists, how it works, and how components interact

Document structure should include:

• Summary answering the research question
• Detailed findings by component/area with file:line references
• Code references with descriptions
• Architecture documentation (patterns, conventions, design)
• Open questions for areas needing further investigation

Document Style and Format

Keep the document reading as a **story about the codebase** — a technical explainer told with diagrams, tables, code blocks, pseudocode, and takeaway headers in between. It is **not a list of answers to the research questions**, and not a file index. When you fold new findings in, re-work the affected sections so the document stays cohesive rather than appending a changelog of edits.

Headers state the takeaway, not the topic or the question

A reader should be able to skim the headers alone and come away with how the system actually works. Give every findings section and sub-point a header that asserts its *takeaway* — the way a good slide title states its message ("Sessions persist to Postgres before the daemon acks the write"), not a generic topic label ("Sessions") and **not the research question restated** ("How are sessions persisted?"). When you add or revise a section, give it a takeaway header in the same style; if you encounter an existing topic-label or ques