Grind Research
You are performing an autonomous deep-dive pass on an existing research document. Self-direct the review by identifying gaps and verifying claims.
Steps
Read the existing document FULLY:
- Understand what research was previously conducted - there may be more than one research file - they are ALL in scope unless a single doc is explicitly specified
- Use Read tool WITHOUT limit/offset to read the entire document(s)
- Don't read any other files in the rpi/ directory for the task, focus on the research document.
- DO NOT read ticket files - research must stay objective about the current codebase.
Gap analysis — identify thin sections:
- Review every section of the document
- Identify areas where related components or interactions are mentioned but not explored
- Note any "Open Questions" that could be answered with codebase research or web research
- Build a list of investigation targets
Spawn sub-agents to fill gaps:
For each gap identified, spawn the appropriate sub-agent:
codebase-locator: Find WHERE files and components live
- Use when a section mentions a component but doesn't provide file paths
- Use to discover related files not yet documented
codebase-analyzer: Understand HOW specific code works (without critiquing it)
- Use when a section describes behavior but lacks implementation detail
- Use to trace data flow through components mentioned in the doc
codebase-pattern-finder: Find examples of existing patterns (without evaluating them)
- Use when a section describes a pattern but lacks concrete code examples
web-researcher: Deep research the web
- Use to add color around library behavior, external systems, and behavior that cannot be discovered through codebase research
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
Claim verification — vet existing claims:
Re-read the document after gap-filling
Identify specific factual claims about the codebase (file paths, line numbers, function names, behavior descriptions)
Spawn sub-agents to verify each claim is still accurate:
codebase-pattern-finder: Verify that described patterns and code examples still exist as documented
codebase-analyzer: Verify that described behavior and data flows are accurate
For any claim that is outdated or incorrect, note it for correction in the update step
Update document:
- Update the document at the same
docPath
- Add new findings to relevant existing sections
- Deepen shallow sections with file:line references and implementation details
- Correct any outdated or inaccurate claims found during verification
- Move answered items out of "Open Questions"
- Add any new open questions discovered during the deep-dive
- Keep the same YAML frontmatter and format
Refine and Split:
- Check if any document is over 1000 lines
- if so, split it into 2-3 documents, using your judgement to decide subject matter boundaries and what makes sense, don't ask the user
Update the user
- Read the final output template:
Read({SKILLBASE}/references/research_final_answer.md)
- Respond with a summary following the template, including GitHub permalinks.
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
When you write or edit documents in .humanlayer/tasks/, a cloud permalink is automatically provided in the hook response.
- The permalink appears as
additionalContext after Write/Edit/MultiEdit/Read operations
- Use this permalink in your final output for easy navigation
- Example format:
http(s)://{DOMAIN}/artifacts/{artifactId}
Markdown Formatting
When writing markdown files that contain code blocks showing other markdown (like README examples or SKILL.md templates), use 4 backticks (````) for the outer fence so inner 3-backtick code blocks don't prematurely close it:
# Example README
## Installation
```bash
npm install example
```
Important notes:
- Use parallel Task agents to maximize efficiency and minimize context usage
- Focus on finding concrete file paths and line numbers for developer reference
- Research documents should be self-contained with all necessary context
- Each sub-agent prompt should be specific and focused on read-only documentation operations
- Document cross-component connections and how systems interact
- Link to GitHub when possible for permanent references
- Stay focused on synthesis, not deep file reading
- Have sub-agents document examples and usage patterns as they exist
- REMEMBER: Document and Ask about what IS and WHY, not what SHOULD BE
- NO RECOMMENDATIONS OR IMPLEMENTATION SUGGESTIONS: Only describe the current state of the codebase
- File reading: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
- Critical ordering: Follow the numbered steps exactly
- ALWAYS read mentioned files first before spawning sub-tasks (step 1)
- ALWAYS wait for all sub-agents to complete before synthesizing (step 5)
- NEVER write the research document with placeholder values
- Path handling: Task-specific research goes in .humanlayer/tasks/
- Use
.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-research.md for task research
Remember, you must respond to the user according to the output template at {SKILLBASE}/references/research_final_answer.md
1---2name: grind-research3description: autonomous deep-dive pass on research document. Use when you want to grind on a research doc without user feedback - digs deeper, vets claims, adds detail.4metadata:5 source: https://skillmd.com/skills/humanlayer/grind-research6---78# Grind Research910You are performing an autonomous deep-dive pass on an existing research document. Self-direct the review by identifying gaps and verifying claims.1112## Steps13141. **Read the existing document FULLY**:15 - Understand what research was previously conducted - there may be more than one research file - they are ALL in scope unless a single doc is explicitly specified16 - Use Read tool WITHOUT limit/offset to read the entire document(s)17 - Don't read any other files in the rpi/ directory for the task, focus on the research document.18 - **DO NOT read ticket files** - research must stay objective about the current codebase.19202. **Gap analysis — identify thin sections**:21 - Review every section of the document22 - Identify areas where related components or interactions are mentioned but not explored23 - Note any "Open Questions" that could be answered with codebase research or web research24 - Build a list of investigation targets25263. **Spawn sub-agents to fill gaps**:27 - For each gap identified, spawn the appropriate sub-agent:2829 - **codebase-locator**: Find WHERE files and components live30 - Use when a section mentions a component but doesn't provide file paths31 - Use to discover related files not yet documented32 - **codebase-analyzer**: Understand HOW specific code works (without critiquing it)33 - Use when a section describes behavior but lacks implementation detail34 - Use to trace data flow through components mentioned in the doc35 - **codebase-pattern-finder**: Find examples of existing patterns (without evaluating them)36 - Use when a section describes a pattern but lacks concrete code examples37 - **web-researcher**: Deep research the web 38 - Use to add color around library behavior, external systems, and behavior that cannot be discovered through codebase research3940 **Agent usage tips:**41 - Start with locator agents to find what exists42 - Then use analyzer agents on the most promising findings43 - Run multiple agents in parallel when searching for different things44 - Each agent knows its job — just tell it what you're looking for45464. **Claim verification — vet existing claims**:47 - Re-read the document after gap-filling48 - Identify specific factual claims about the codebase (file paths, line numbers, function names, behavior descriptions)49 - Spawn sub-agents to verify each claim is still accurate:5051 - **codebase-pattern-finder**: Verify that described patterns and code examples still exist as documented52 - **codebase-analyzer**: Verify that described behavior and data flows are accurate5354 - For any claim that is outdated or incorrect, note it for correction in the update step55565. **Update document**:57 - Update the document at the same `docPath`58 - Add new findings to relevant existing sections59 - Deepen shallow sections with file:line references and implementation details60 - Correct any outdated or inaccurate claims found during verification61 - Move answered items out of "Open Questions"62 - Add any new open questions discovered during the deep-dive63 - Keep the same YAML frontmatter and format64656. **Refine and Split**:66 - Check if any document is over 1000 lines67 - if so, split it into 2-3 documents, using your judgement to decide subject matter boundaries and what makes sense, don't ask the user68697. **Update the user**70 - Read the final output template:71 `Read({SKILLBASE}/references/research_final_answer.md)`72 - Respond with a summary following the template, including GitHub permalinks.7374## Research Guidelines7576Your job is to DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY:77- DO NOT suggest improvements or changes unless explicitly asked78- DO NOT perform root cause analysis unless explicitly asked79- DO NOT propose future enhancements unless explicitly asked80- DO NOT critique the implementation or identify problems81- DO NOT recommend refactoring, optimization, or architectural changes82- ONLY describe what exists, where it exists, how it works, and how components interact8384Document structure should include:85- Summary answering the research question86- Detailed findings by component/area with file:line references87- Code references with descriptions88- Architecture documentation (patterns, conventions, design)89- Open questions for areas needing further investigation9091<guidance>92## Cloud Permalinks9394When you write or edit documents in .humanlayer/tasks/, a cloud permalink is automatically provided in the hook response.95- The permalink appears as `additionalContext` after Write/Edit/MultiEdit/Read operations96- Use this permalink in your final output for easy navigation97- Example format: `http(s)://{DOMAIN}/artifacts/{artifactId}`9899## Markdown Formatting100101When writing markdown files that contain code blocks showing other markdown (like README examples or SKILL.md templates), use 4 backticks (````) for the outer fence so inner 3-backtick code blocks don't prematurely close it:102103````markdown104# Example README105## Installation106```bash107npm install example108```109````110## Important notes:111- Use parallel Task agents to maximize efficiency and minimize context usage112- Focus on finding concrete file paths and line numbers for developer reference113- Research documents should be self-contained with all necessary context114- Each sub-agent prompt should be specific and focused on read-only documentation operations115- Document cross-component connections and how systems interact116- Link to GitHub when possible for permanent references117- Stay focused on synthesis, not deep file reading118- Have sub-agents document examples and usage patterns as they exist119- **REMEMBER**: Document and Ask about what IS and WHY, not what SHOULD BE120- **NO RECOMMENDATIONS OR IMPLEMENTATION SUGGESTIONS**: Only describe the current state of the codebase121- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks122- **Critical ordering**: Follow the numbered steps exactly123 - ALWAYS read mentioned files first before spawning sub-tasks (step 1)124 - ALWAYS wait for all sub-agents to complete before synthesizing (step 5)125 - NEVER write the research document with placeholder values126- **Path handling**: Task-specific research goes in .humanlayer/tasks/127 - Use `.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-research.md` for task research128</guidance>129130131Remember, you must respond to the user according to the output template at `{SKILLBASE}/references/research_final_answer.md`