Initial commit

skills/ln-112-reference-docs-creator/references/questions.md

@@ -0,0 +1,119 @@
+# 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