write-research-doc

name	write-research-doc
description	Use when documenting research findings to create properly structured research documents with frontmatter, sections, and file references.

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