---
name: ln-120-reference-docs-creator
description: "Creates reference docs (ADRs, guides, manuals) for nontrivial tech stack choices. Use when project needs justified architecture decision records."
license: MIT
---

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Reference Documentation Creator

**Type:** L2 Worker

This skill creates the reference documentation structure (docs/reference/) and **smart documents** (ADRs, Guides, Manuals) based on project's TECH_STACK. Documents are created only when justified (nontrivial technology choices with alternatives).

## Purpose

Create the reference documentation directory structure (docs/reference/) with README hub, then generate ADRs, Guides, and Manuals only for justified (nontrivial) technology choices based on TECH_STACK from Context Store.

## When to Use This Skill

**This skill is a L2 WORKER** invoked by **ln-100-documents-pipeline** orchestrator.

This skill should be used directly when:
- Creating only reference documentation structure (docs/reference/)
- Setting up directories for ADRs, guides, and manuals
- NOT creating full documentation structure (use ln-100-documents-pipeline for complete setup)

## Inputs

**From ln-100 (via ln-110 Context Store):**
```json
{
  "context_store": {
    "PROJECT_NAME": "my-project",
    "TECH_STACK": {
      "frontend": "React 18",
      "backend": "Express 4.18",
      "database": "PostgreSQL 15",
      "orm": "Prisma 5.0",
      "auth": "JWT",
      "cache": "Redis 7"
    },
    "DEPENDENCIES": [...],
    "flags": { "hasBackend": true, "hasDatabase": true, "hasFrontend": true }
  }
}
```

**TECH_STACK** is used for smart document creation in Phase 2.

**MANDATORY READ:** Load `references/docs_quality_contract.md`, and `references/markdown_read_protocol.md`.
Optional rule catalog: load `references/docs_quality_rules.json` only when exact rule IDs, path matrices, or allowlisted placeholder exceptions are needed.

## Workflow

The skill follows a 4-phase workflow: **CREATE STRUCTURE** → **SMART DOCUMENT CREATION** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Phase 2 creates documents only for justified technology choices.

---

### Phase 1: Create Structure

**Objective**: Establish reference documentation directories and README hub.

**Process**:

**1.1 Check & create directories**:
- Check if `docs/reference/adrs/` exists → create if missing
- Check if `docs/reference/guides/` exists → create if missing
- Check if `docs/reference/manuals/` exists → create if missing
- Check if `docs/reference/research/` exists → create if missing
- Log for each: "✓ Created docs/reference/[name]/" or "✓ docs/reference/[name]/ already exists"

**1.2 Check & create README**:
- Check if `docs/reference/README.md` exists
- If exists:
  - Skip creation
  - Log: "✓ docs/reference/README.md already exists, proceeding to validation"
- If NOT exists:
  - Copy template: `ln-120-reference-docs-creator/references/templates/reference_readme_template.md` → `docs/reference/README.md`
  - Replace placeholders:
    - `{{VERSION}}` — "1.0.0"
    - `{{DATE}}` — current date (YYYY-MM-DD)
    - `{{ADR_LIST}}` — `- No ADRs yet. Add the first ADR when a nontrivial decision is accepted.`
    - `{{GUIDE_LIST}}` — `- No project guides yet. Add guides when patterns need project-specific explanation.`
    - `{{MANUAL_LIST}}` — `- No package manuals yet. Add manuals only for complex external APIs.`
    - `{{RESEARCH_LIST}}` — `- No research notes yet. Add research only when a concrete question is investigated.`
  - Preserve the shared opening contract and standard top sections from the template
  - Log: "✓ Created docs/reference/README.md from template"

**1.3 Output**:
```
docs/reference/
├── README.md         # Created or existing
├── adrs/            # Empty, ready for ADRs
├── guides/          # Empty, ready for guides
├── manuals/         # Empty, ready for manuals
└── research/        # Empty, ready for research documents
```

---

### Phase 2: Smart Document Creation

**Objective**: Create ADRs, Guides, and Manuals for justified technology choices. Skip trivial/obvious selections.

**2.1 Check Context Store**:
- If no `context_store` provided → skip Phase 2, proceed to Phase 3
- If no `TECH_STACK` in context_store → skip Phase 2, proceed to Phase 3
- Log: "Context Store received with TECH_STACK: [categories count]"

**2.2 Load Justification Rules**:
- Read `references/tech_justification_rules.md`
- Parse category → justified/skip conditions

**2.3 Analyze TECH_STACK for ADRs**:

For each category in TECH_STACK (frontend, backend, database, orm, auth, cache):

1. **Check if justified** (from justification rules):
   - `frontend`: Justified if React/Vue/Angular/Svelte (multiple options exist)
   - `backend`: Justified if Express/Fastify/NestJS/Koa (multiple options exist)
   - `database`: Justified if PostgreSQL/MySQL/MongoDB (multiple options exist)
   - `auth`: Justified if JWT/OAuth/Session (decision required)
   - `orm`: Justified if Prisma/TypeORM/Sequelize (multiple options exist)
   - `cache`: Justified if Redis/Memcached (decision required)

2. **Skip if trivial**:
   - jQuery-only frontend (no framework choice)
   - Simple http server (no framework)
   - SQLite for dev only
   - No auth required
   - Raw SQL only
   - In-memory cache only

3. **Create ADR if justified**:
   - Determine next ADR number: `adr-NNN-{category}.md`
   - Use template: `references/templates/adr_template.md`
   - MCP Research: `mcp__context7__resolve-library-id(technology)`
   - Fill template:
     - Title: "ADR-NNN: {Category} Selection"
     - Context: Why decision was needed
     - Decision: Technology chosen with version
     - Rationale: 3 key reasons from research
     - Alternatives: 2 other options with pros/cons
   - Save: `docs/reference/adrs/adr-NNN-{category}.md`
   - Log: "✓ Created ADR for {category}: {technology}"

4. **Skip if not justified**:
   - Log: "⊘ Skipped ADR for {category}: trivial choice"

**2.4 Analyze TECH_STACK for Guides**:

For each technology with complex configuration:

1. **Check if justified**:
   - Has config file with >20 lines
   - Uses custom hooks/middleware/decorators
   - Has 3+ related dependencies

2. **Create Guide if justified**:
   - Determine next guide number: `NN-{technology-slug}-patterns.md`
   - Use template: `references/templates/guide_template.md`
   - MCP Research: `mcp__Ref__ref_search_documentation("{technology} patterns {current_year}")`
   - Fill template:
     - Principle: Industry standard from research
     - Our Implementation: How project uses it
     - Patterns table: 3 Do/Don't/When rows
   - Save: `docs/reference/guides/NN-{technology}-patterns.md`
   - Log: "✓ Created Guide for {technology}"

3. **Skip if standard usage**:
   - Log: "⊘ Skipped Guide for {technology}: standard usage"

**2.5 Analyze TECH_STACK for Manuals**:

For each package with complex API:

1. **Check if justified**:
   - Package has >10 exported methods
   - Has breaking changes in current version
   - NOT in trivial list: lodash, uuid, dotenv

2. **Create Manual if justified**:
   - Use template: `references/templates/manual_template.md`
   - MCP Research: `mcp__context7__get-library-docs(topic: "API")`
   - Fill template:
     - Package info with version
     - 2-3 most used methods
     - Configuration section
   - Save: `docs/reference/manuals/{package}-{version}.md`
   - Log: "✓ Created Manual for {package}"

3. **Skip if trivial API**:
   - Log: "⊘ Skipped Manual for {package}: trivial API"

**2.6 Report Smart Creation**:
```
✅ Smart Document Creation complete:
  - ADRs created: [count] (justified: frontend, backend, database)
  - ADRs skipped: [count] (trivial: cache=in-memory)
  - Guides created: [count]
  - Guides skipped: [count]
  - Manuals created: [count]
  - Manuals skipped: [count]
```

---

### Phase 3: Validate Structure

**Objective**: Ensure reference/README.md complies with structural requirements and auto-fix violations.

**Process**:

**2.1 Check opening contract**:
- Read `docs/reference/README.md` (first 5 lines)
- Check for `<!-- SCOPE: ... -->` tag and metadata markers
- Expected: `<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->`
- If missing:
  - Use Edit tool to add missing opening markers near the top of the file
  - Track violation: `opening_contract_fixed = True`

**2.2 Check required sections**:
- Load expected sections from `references/questions.md`
- Required sections:
  - "Architecture Decision Records (ADRs)"
  - "Project Guides"
  - "Package Manuals"
  - "Research"
- For each section:
  - Check if `## [Section Name]` header exists
  - If missing:
    - Use Edit tool to add section with placeholder:
      ```markdown
      ## [Section Name]

      {{PLACEHOLDER}}
      ```
    - Track violation: `missing_sections += 1`

**2.3 Check Maintenance section**:
- Search for `## Maintenance` header
- If missing:
  - Use Edit tool to add at end of file:
    ```markdown
    ## Maintenance

    **Last Updated:** [current date]

    **Update Triggers:**
    - New ADRs added to adrs/ directory
    - New guides added to guides/ directory
    - New manuals added to manuals/ directory

    **Verification:**
    - [ ] All ADR links in registry are valid
    - [ ] All guide links in registry are valid
    - [ ] All manual links in registry are valid
    - [ ] Placeholders {{ADR_LIST}}, {{GUIDE_LIST}}, {{MANUAL_LIST}} synced with files
    ```
  - Track violation: `maintenance_added = True`

**2.4 Check POSIX file endings**:
- Check if file ends with single blank line
- If missing:
  - Use Edit tool to add final newline
  - Track fix: `posix_fixed = True`

**2.5 Report validation**:
- Log summary:
  ```
  ✅ Structure validation complete:
    - SCOPE tag: [added/present]
    - Missing sections: [count] sections added
    - Maintenance section: [added/present]
    - POSIX endings: [fixed/compliant]
  ```
- If violations found: "⚠️ Auto-fixed [total] structural violations"

---

### Phase 4: Validate Content

**Objective**: Ensure each section answers its questions with meaningful content and populate registries from auto-discovery (including documents created in Phase 2).

**Process**:

**4.1 Load validation spec**:
- Read `references/questions.md`
- Parse questions and validation heuristics for all 3 sections

**4.2 Validate sections (parametric loop)**:

Define section parameters:
```
sections = [
  {
    "name": "Architecture Decision Records (ADRs)",
    "question": "Where are architecture decisions documented?",
    "directory": "docs/reference/adrs/",
    "empty_state": "No ADRs yet.",
    "glob_pattern": "docs/reference/adrs/*.md",
    "heuristics": [
      "Contains link: [ADRs](adrs/) or [adrs](adrs/)",
      "Mentions 'Architecture Decision Record' or 'ADR'",
      "Has actual list or empty-state note",
      "Length > 30 words"
    ]
  },
  {
    "name": "Project Guides",
    "question": "Where are reusable project patterns documented?",
    "directory": "docs/reference/guides/",
    "empty_state": "No project guides yet.",
    "glob_pattern": "docs/reference/guides/*.md",
    "heuristics": [
      "Contains link: [Guides](guides/) or [guides](guides/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  },
  {
    "name": "Package Manuals",
    "question": "Where are third-party package references documented?",
    "directory": "docs/reference/manuals/",
    "empty_state": "No package manuals yet.",
    "glob_pattern": "docs/reference/manuals/*.md",
    "heuristics": [
      "Contains link: [Manuals](manuals/) or [manuals](manuals/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  },
  {
    "name": "Research",
    "question": "Where are research/investigation documents stored?",
    "directory": "docs/reference/research/",
    "empty_state": "No research notes yet.",
    "glob_pattern": "docs/reference/research/*.md",
    "heuristics": [
      "Contains link: [Research](research/) or [research](research/)",
      "Has actual list or empty-state note",
      "Length > 20 words"
    ]
  }
]
```

For each section in sections:

1. **Read section content**:
   - Extract section from reference/README.md

2. **Check if content answers question**:
   - Apply validation heuristics
   - If ANY heuristic passes → content valid, skip to next section
   - If ALL fail → content invalid, continue

3. **Auto-discovery** (if content invalid or empty-state present):
   - Scan directory using Glob tool (section.glob_pattern)
   - If files found:
     - Extract filenames
     - Generate dynamic list:
       ```markdown
       - [ADR-001: Frontend Framework](adrs/adr-001-frontend-framework.md)
       - [02-Repository Pattern](guides/02-repository-pattern.md)
       - [Axios 1.6](manuals/axios-1.6.md)
       ```
     - Use Edit tool to replace empty-state text with generated list
     - Track change: `sections_populated += 1`
   - If NO files:
     - Keep concise empty-state note
     - Track: `empty_states_kept += 1`

4. **Skip external API calls**:
   - Do NOT use MCP Ref search (template already has format examples)

**4.3 Report content validation**:
- Log summary:
  ```
  ✅ Content validation complete:
    - Sections checked: 4
    - Populated from auto-discovery: [count]
    - Placeholders kept (no files): [count]
    - Already valid: [count]
  ```

---

## Complete Output Structure

```
docs/
└── reference/
    ├── README.md                     # Reference hub with registries
    ├── adrs/                         # Empty or with ADR files
    ├── guides/                       # Empty or with guide files
    ├── manuals/                      # Empty or with manual files
    └── research/                     # Empty or with research files
```

---

## Reference Files

### Templates

**Reference README Template**:
- `references/templates/reference_readme_template.md` (v2.0.0) - Reference hub with:
  - SCOPE tags (reference documentation ONLY)
  - Three registry sections with placeholders
  - Maintenance section

**Document Templates** (for Phase 2 Smart Creation):
- `references/templates/adr_template.md` - Nygard ADR format (7 sections)
- `references/templates/guide_template.md` - Pattern documentation (Do/Don't/When)
- `references/templates/manual_template.md` - API reference format
- `references/templates/research_template.md` - Research/Spike documentation

**Justification Rules**:
- `references/tech_justification_rules.md` - Mapping: category → create/skip conditions

**Validation Specification**:
- `references/questions.md` (v2.0) - Question-driven validation:
  - Q1-Q3: Registry sections (ADRs, Guides, Manuals)
  - Q4-Q7: Smart document validation (ADR context, alternatives, patterns)
  - Auto-discovery hints

- **MANDATORY READ:** Load `references/research_tool_fallback.md`

---

## Best Practices

- **No premature validation**: Phase 1 creates structure, Phase 3 validates it
- **Smart creation**: Phase 2 creates documents only for justified choices
- **Parametric validation**: Phase 4 uses loop for 3 sections (no code duplication)
- **Auto-discovery first**: Scan actual files before external API calls
- **Idempotent**: ✅ Can run multiple times safely (checks existence before creation)
- **Separation of concerns**: CREATE → SMART DOCS → VALIDATE STRUCTURE → VALIDATE CONTENT

### NO_CODE_EXAMPLES Rule (MANDATORY for Guides)
Guides document **patterns**, NOT implementations:
- **FORBIDDEN:** Full function implementations, code blocks > 5 lines
- **ALLOWED:** Do/Don't/When tables, method signatures (1 line), pseudocode (1-3 lines)
- **INSTEAD OF CODE:** Reference source location: "See src/hooks/usePlan.ts:15-30"
- **TEMPLATE RULE:** guide_template.md includes `<!-- NO_CODE_EXAMPLES: ... -->` tag - FOLLOW IT

### Stack Adaptation Rule (MANDATORY)
- ADRs must reference stack-appropriate alternatives (Compare React vs Vue, not React vs Django)
- Guides must link to correct platform docs (Microsoft for .NET, MDN for JS)

### Format Priority (MANDATORY)
Tables (Do/Don't/When) > ASCII diagrams > Lists > Text

---

## Prerequisites

**Invoked by**: ln-100-documents-pipeline orchestrator

**Requires**:
- `docs/` directory (created by ln-111-root-docs-creator or already present in target project)

**Creates**:
- `docs/reference/` directory structure with README hub
- Validated structure and content (auto-discovery from existing files)

---

## Critical Rules

- **Justified creation only:** Documents are created only for nontrivial technology choices with real alternatives; trivial/obvious selections are skipped
- **NO_CODE_EXAMPLES:** Guides document patterns (Do/Don't/When tables), not implementations; no code blocks >5 lines
- **Stack adaptation:** ADR alternatives must be stack-appropriate (React vs Vue, not React vs Django); links must match platform docs
- **Format priority:** Tables (Do/Don't/When) > ASCII diagrams > Lists > Text
- **Idempotent:** Checks existence before creation; safe to run multiple times

## Runtime Summary Artifact

**MANDATORY READ:** Load `references/docs_generation_summary_contract.md`

Accept optional `summaryArtifactPath`.

Summary kind:
- `docs-generation`

Required payload semantics:
- `worker = "ln-120"`
- `status`
- `created_files`
- `skipped_files`
- `quality_inputs`
- `validation_status`
- `warnings`

Write the summary to the provided artifact path or return the same envelope in structured output.

## Definition of Done

Before completing work, verify ALL checkpoints:

**✅ Phase 1 - Structure Created:**
- [ ] `docs/reference/` directory exists
- [ ] `docs/reference/adrs/` directory exists
- [ ] `docs/reference/guides/` directory exists
- [ ] `docs/reference/manuals/` directory exists
- [ ] `docs/reference/research/` directory exists
- [ ] `docs/reference/README.md` exists (created or existing)

**✅ Phase 2 - Smart Documents Created (if Context Store provided):**
- [ ] ADRs created for justified technology choices (nontrivial)
- [ ] ADRs skipped for trivial choices (logged)
- [ ] Guides created for technologies with complex config
- [ ] Manuals created for packages with complex API
- [ ] Each created document has real content (not placeholders)

**✅ Phase 3 - Structure Validated:**
- [ ] SCOPE tag and metadata markers present near top
- [ ] Quick Navigation, Agent Entry, and Maintenance sections present
- [ ] Four registry sections present (ADRs, Guides, Manuals, Research)
- [ ] Maintenance section present at end
- [ ] POSIX file endings compliant

**✅ Phase 4 - Content Validated:**
- [ ] All sections checked against questions.md
- [ ] Empty-state notes or actual entries present in all registries (no raw placeholders)
- [ ] No validation heuristic failures

**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: smart creation (created/skipped counts)
- [ ] Phase 3 logged: structural fixes (if any)

## Return Contract

Return normalized status to ln-100:

```json
{
  "created_files": ["docs/reference/README.md", "docs/reference/adrs/adr-001-frontend.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/reference/README.md", "docs/reference/adrs/adr-001-frontend.md"],
    "owners": {
      "docs/reference/README.md": "ln-120-reference-docs-creator",
      "docs/reference/adrs/adr-001-frontend.md": "ln-120-reference-docs-creator"
    }
  },
  "validation_status": "passed"
}
```

**✅ Reporting (continued):**
- [ ] Phase 4 logged: content updates (if any)

## Meta-Analysis

Optional reference: load `references/meta_analysis_protocol.md` only when the user asks for post-run meta-analysis or protocol-formatted run reflection.

Skill type: `documentation-creator`. When requested, run after all phases complete. Output to chat using the `documentation-creator` format.

---

## Technical Details

**Standards**:
- Michael Nygard's ADR Format (7 sections)
- ISO/IEC/IEEE 29148:2018 (Documentation standards)

**Language**: English only

---

**Version:** 8.2.0
**Last Updated:** 2025-01-12