# Write Research Doc

> Use when documenting research findings to create properly structured research documents with frontmatter, sections, and file references.

- Skill: `tomevault-io/write-research-doc` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/write-research-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/write-research-doc/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/write-research-doc

---


# Write Research Document

Create structured research documents following project conventions.

## Document Structure

Use the template from `templates/research-document.md`:

1. **Frontmatter** (YAML):
   - date, researcher, git info, topic, tags, status
   - feature_slug (e.g., "erik/0005-authentication" for personal, "0042-authentication" for shared)
   - Optional: shared_as, shared_date (added by share-docs skill)

2. **Research Question**:
   - Original user query verbatim

3. **Summary**:
   - High-level findings (2-3 paragraphs)

4. **Detailed Findings**:
   - Organized by component/area
   - Include file:line references
   - Explain purpose and implementation

5. **Key Discoveries**:
   - Bullet list of important findings

6. **Implementation Patterns**:
   - Common patterns found

7. **References**:
   - Links to source files and related docs

## File Path and Naming

Determine feature slug first using `determine-feature-slug` skill:
- Auto-detects namespace from git user.name
- Auto-detects next number in personal namespace (0001, 0002, etc.)
- Suggests description from research question
- Prompts user to accept or customize

Save to: `thoughts/{namespace}/NNNN-description/research.md`

Example workflow:
1. User provides research question: "How does authentication work?"
2. Skill detects namespace: `erik` (from git config)
3. Skill suggests: `erik/0005-authentication`
4. User accepts or modifies
5. Document saved to: `thoughts/erik/0005-authentication/research.md`

**Collaboration**: Documents start in personal namespace. Use `share-docs` skill to promote to `thoughts/shared/` when ready for team review.

**Backward compatibility**: Old path `thoughts/shared/research/YYYY-MM-DD-NN-description.md` still recognized by all commands.

## Metadata Collection

Use `gather-project-metadata` skill to get:
- Timestamp
- Git commit and branch
- Repository name

## File References

Always include specific file:line references:
- `src/auth/handler.go:45` - Format for references
- Use actual line numbers where functions/types are defined

## Path Corrections

Watch for these common mistakes:
- ✅ `thoughts/shared/research/` - Correct for shared research
- ❌ `thoughts/searchable/` - Old path, don't use
- ✅ `thoughts/notes/` - Correct for reference documents

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/eveld) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->