3.9 KiB
Reference Documentation Questions
Purpose: Define what each section of reference documentation should answer.
Format: Question → Expected Content → Validation Heuristics → Auto-Discovery Hints → MCP Ref Hints
Table of Contents
| Document | Questions | Auto-Discovery | Priority | Line |
|---|---|---|---|---|
| docs/reference/README.md | 3 | High | High | L23 |
Priority Legend:
- Critical: Must answer all questions
- High: Strongly recommended
- Medium: Optional (can use template defaults)
Auto-Discovery Legend:
- None: No auto-discovery needed (use template as-is)
- Low: 1-2 questions need auto-discovery
- High: All questions need auto-discovery
docs/reference/README.md
File: docs/reference/README.md (reference documentation hub) Target Sections: Architecture Decision Records (ADRs), Project Guides, Package Manuals
Rules for this document:
- Hub file for reference documentation subdirectories
- Must link to adrs/, guides/, manuals/ directories
- Auto-discovery of existing files in each directory
Question 1: Where are architecture decisions documented?
Expected Answer: Link to adrs/ directory, ADR format description (Nygard template), list of existing ADRs or placeholder Target Section: ## Architecture Decision Records (ADRs)
Validation Heuristics:
- ✅ Contains link:
[ADRs](adrs/)or[adrs](adrs/) - ✅ Mentions "Architecture Decision Record" or "ADR"
- ✅ Has placeholder
{{ADR_LIST}}or actual ADR list - ✅ Length > 30 words
Auto-Discovery:
- Scan
docs/reference/adrs/for *.md files - Generate list dynamically from filenames
- Example:
adr-001-frontend-framework.md→ "ADR-001: Use React+Next.js"
MCP Ref Hints:
- Research: "Michael Nygard ADR format" (if no ADRs exist and need to explain format)
- Extract: ADR template structure (Context, Decision, Status, Consequences)
Question 2: Where are reusable project patterns documented?
Expected Answer: Link to guides/ directory, description of guide purpose (reusable patterns, how-tos), list of existing guides or placeholder Target Section: ## Project Guides
Validation Heuristics:
- ✅ Contains link:
[Guides](guides/)or[guides](guides/) - ✅ Mentions "patterns" or "guides" or "how-to"
- ✅ Has placeholder
{{GUIDE_LIST}}or actual guide list - ✅ Length > 20 words
Auto-Discovery:
- Scan
docs/reference/guides/for *.md files - Generate list dynamically from filenames
- Example:
authentication-flow.md→ "Authentication Flow Guide"
MCP Ref Hints:
- N/A (guides are project-specific)
Question 3: Where are third-party package references documented?
Expected Answer: Link to manuals/ directory, description of manual purpose (package API references, version-specific), list of existing manuals or placeholder Target Section: ## Package Manuals
Validation Heuristics:
- ✅ Contains link:
[Manuals](manuals/)or[manuals](manuals/) - ✅ Mentions "packages" or "API reference" or "manuals"
- ✅ Has placeholder
{{MANUAL_LIST}}or actual manual list - ✅ Length > 20 words
Auto-Discovery:
- Scan
docs/reference/manuals/for *.md files - Generate list dynamically from filenames
- Example:
axios-1.6.md→ "Axios 1.6 API Manual"
MCP Ref Hints:
- N/A (manuals are package-specific, created by ln-323-manual-creator)
Overall File Validation:
- ✅ Has links to all 3 subdirectories (adrs/, guides/, manuals/)
- ✅ Total length > 60 words
Version: 2.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management) Last Updated: 2025-11-18