tomevault-io Write Research Document
Create structured research documents following project conventions.
Document Structure
Use the template from templates/research-document.md:
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)
Research Question:
- Original user query verbatim
Summary:
- High-level findings (2-3 paragraphs)
Detailed Findings:
- Organized by component/area
- Include file:line references
- Explain purpose and implementation
Key Discoveries:
- Bullet list of important findings
Implementation Patterns:
- Common patterns found
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:
- User provides research question: "How does authentication work?"
- Skill detects namespace:
erik(from git config) - Skill suggests:
erik/0005-authentication - User accepts or modifies
- 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 — claim your Tome and manage your conversions.