180 lines
5.2 KiB
Markdown
180 lines
5.2 KiB
Markdown
---
|
|
name: Creating Research Packages
|
|
description: Document complex domain knowledge as self-contained packages with multiple reading paths
|
|
when_to_use: when documenting complex research topics, domain knowledge requiring multiple reading paths, technical deep dives that need verification tracking
|
|
version: 1.0.0
|
|
---
|
|
|
|
# Creating Research Packages
|
|
|
|
## Overview
|
|
|
|
Bundle complex domain knowledge into self-contained modules with multiple entry points for different time budgets and reader roles.
|
|
|
|
**Announce at start:** "I'm using the creating-research-packages skill to document this domain knowledge."
|
|
|
|
## When to Use
|
|
|
|
- Documenting complex research findings
|
|
- Creating domain knowledge packages (physics, algorithms, APIs)
|
|
- Building self-contained documentation that can be shared independently
|
|
- Topics requiring multiple reading paths (quick overview vs deep dive)
|
|
- Knowledge that needs verification tracking
|
|
|
|
## The Process
|
|
|
|
### Step 1: Identify the Package Scope
|
|
|
|
Determine what knowledge should be packaged:
|
|
|
|
- What is the core topic?
|
|
- What are the sub-topics?
|
|
- Who are the readers? (roles, time budgets)
|
|
- What verification is needed?
|
|
|
|
### Step 2: Create Directory Structure
|
|
|
|
```bash
|
|
mkdir -p docs/[topic]
|
|
```
|
|
|
|
Standard package structure:
|
|
|
|
```
|
|
[topic]/
|
|
├── 00-START-HERE.md # Entry point + verification status
|
|
├── README.md # Package overview + TL;DR
|
|
├── how-to-use-this.md # Detailed navigation guide
|
|
├── [core-topic-1].md # Main research content
|
|
├── [core-topic-2].md # Additional research
|
|
├── design-decisions.md # Why decisions were made
|
|
├── QUICK-REFERENCE.md # One-page summary
|
|
├── VERIFICATION-REVIEW.md # Accuracy audit
|
|
└── examples/ # Working examples (if applicable)
|
|
```
|
|
|
|
### Step 3: Write Entry Point (00-START-HERE.md)
|
|
|
|
Include:
|
|
- Verification status with visual indicators
|
|
- Time budget options (5 min, 20 min, 2 hours)
|
|
- Quick navigation to key documents
|
|
- Prerequisites if any
|
|
|
|
```markdown
|
|
# [Topic]: Start Here
|
|
|
|
**Status:** ✅ Verified | **Last Updated:** YYYY-MM-DD
|
|
|
|
## Choose Your Path
|
|
|
|
| Time | Goal | Start With |
|
|
|------|------|------------|
|
|
| 5 min | Quick overview | [TL;DR section in README] |
|
|
| 20 min | Understand context | [README + design-decisions] |
|
|
| 2 hours | Full understanding | [All documents in sequence] |
|
|
```
|
|
|
|
### Step 4: Write README with TL;DR
|
|
|
|
The README is the package overview:
|
|
|
|
- TL;DR section (2-3 sentences, the essential insight)
|
|
- Reading paths by time budget
|
|
- Role-based paths
|
|
- Package contents overview
|
|
- Key concepts with links to details
|
|
|
|
**Use template:** `${CLAUDE_PLUGIN_ROOT}templates/research-package-template.md`
|
|
|
|
### Step 5: Write Navigation Guide (how-to-use-this.md)
|
|
|
|
Detailed guide for different readers:
|
|
|
|
- Role-based paths with reading orders
|
|
- Time estimates for each path
|
|
- Key takeaways for each role
|
|
- Cross-references between documents
|
|
|
|
### Step 6: Write Core Content
|
|
|
|
For each topic document:
|
|
|
|
- Clear scope statement
|
|
- Structured content with headers
|
|
- Visual aids where helpful (diagrams, tables)
|
|
- Cross-references to related docs
|
|
- Verification notes if applicable
|
|
|
|
### Step 7: Create Quick Reference
|
|
|
|
One-page summary for rapid lookup:
|
|
|
|
- Key formulas/constants
|
|
- Common commands
|
|
- Quick diagnosis table
|
|
- Status icons legend
|
|
|
|
**Use template:** `${CLAUDE_PLUGIN_ROOT}templates/quick-reference-template.md`
|
|
|
|
### Step 8: Add Verification Tracking
|
|
|
|
If accuracy is critical:
|
|
|
|
- Create VERIFICATION-REVIEW.md
|
|
- Track what was verified and when
|
|
- Note discrepancies found
|
|
- Link to authoritative sources
|
|
- Include recommended updates
|
|
|
|
### Step 9: Verify Package Completeness
|
|
|
|
Checklist:
|
|
- [ ] 00-START-HERE.md has clear navigation
|
|
- [ ] README has TL;DR that captures essence
|
|
- [ ] Reading paths cover different time budgets
|
|
- [ ] Role-based paths for different readers
|
|
- [ ] QUICK-REFERENCE is truly one page
|
|
- [ ] All cross-references work
|
|
- [ ] Verification status current
|
|
|
|
## Checklist
|
|
|
|
- [ ] Package scope clearly defined
|
|
- [ ] Directory structure created
|
|
- [ ] Entry point (00-START-HERE) written
|
|
- [ ] README with TL;DR written
|
|
- [ ] Navigation guide written
|
|
- [ ] Core content documents written
|
|
- [ ] Quick reference created
|
|
- [ ] Verification tracking if needed
|
|
- [ ] All internal links verified
|
|
|
|
## Anti-Patterns
|
|
|
|
**Don't:**
|
|
- Create packages for simple topics (overkill)
|
|
- Skip the TL;DR (readers need quick overview)
|
|
- Omit time estimates (readers can't plan)
|
|
- Ignore verification for critical knowledge
|
|
- Make QUICK-REFERENCE more than one page
|
|
|
|
**Do:**
|
|
- Keep TL;DR to 2-3 sentences
|
|
- Provide multiple entry points
|
|
- Track verification for technical accuracy
|
|
- Cross-reference liberally
|
|
- Test navigation with fresh eyes
|
|
|
|
## Related Skills
|
|
|
|
- **Organizing documentation:** `${CLAUDE_PLUGIN_ROOT}skills/organizing-documentation/SKILL.md`
|
|
- **Documenting debugging workflows:** `${CLAUDE_PLUGIN_ROOT}skills/documenting-debugging-workflows/SKILL.md`
|
|
- **Creating quality gates:** `${CLAUDE_PLUGIN_ROOT}skills/creating-quality-gates/SKILL.md`
|
|
|
|
## References
|
|
|
|
- Standards: `${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md`
|
|
- Template: `${CLAUDE_PLUGIN_ROOT}templates/research-package-template.md`
|
|
- Quick Reference Template: `${CLAUDE_PLUGIN_ROOT}templates/quick-reference-template.md`
|