Creating Research Packages

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

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

# [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