120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# 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](#docsreferencereadmemd) | 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
|
|
|
|
---
|
|
|
|
<!-- DOCUMENT_START: docs/reference/README.md -->
|
|
## 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_START: 1 -->
|
|
### 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_END: 1 -->
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 2 -->
|
|
### 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_END: 2 -->
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 3 -->
|
|
### 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)
|
|
<!-- QUESTION_END: 3 -->
|
|
|
|
---
|
|
|
|
**Overall File Validation:**
|
|
- ✅ Has links to all 3 subdirectories (adrs/, guides/, manuals/)
|
|
- ✅ Total length > 60 words
|
|
|
|
<!-- DOCUMENT_END: docs/reference/README.md -->
|
|
|
|
---
|
|
|
|
**Version:** 2.0.0 (MAJOR: Added Table of Contents and programmatic markers for context management)
|
|
**Last Updated:** 2025-11-18
|