---
name: ln-112-reference-docs-creator
description: Creates reference documentation structure (docs/reference/ with README, adrs/, guides/, manuals/ directories). Second worker in ln-110-documents-pipeline.
---

# Reference Documentation Creator

This skill creates the reference documentation structure: docs/reference/README.md (hub with registries for ADRs/Guides/Manuals) and empty subdirectories for storing reference materials.

## When to Use This Skill

**This skill is a WORKER** invoked by **ln-110-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-110-documents-pipeline for complete setup)

## How It Works

The skill follows a 3-phase workflow: **CREATE** → **VALIDATE STRUCTURE** → **VALIDATE CONTENT**. Each phase builds on the previous, ensuring complete structure and semantic validation.

---

### 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
- 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-112-reference-docs-creator/references/reference_readme_template.md` → `docs/reference/README.md`
  - Replace placeholders:
    - `{{VERSION}}` — "1.0.0"
    - `{{DATE}}` — current date (YYYY-MM-DD)
    - `{{ADR_LIST}}` — kept as placeholder (filled in Phase 3)
    - `{{GUIDE_LIST}}` — kept as placeholder (filled in Phase 3)
    - `{{MANUAL_LIST}}` — kept as placeholder (filled in Phase 3)
  - 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
```

---

### Phase 2: Validate Structure

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

**Process**:

**2.1 Check SCOPE tag**:
- Read `docs/reference/README.md` (first 5 lines)
- Check for `<!-- SCOPE: ... -->` tag
- Expected: `<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->`
- If missing:
  - Use Edit tool to add SCOPE tag at line 1 (after first heading)
  - Track violation: `scope_tag_added = True`

**2.2 Check required sections**:
- Load expected sections from `references/questions.md`
- Required sections:
  - "Architecture Decision Records (ADRs)"
  - "Project Guides"
  - "Package Manuals"
- 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 3: Validate Content

**Objective**: Ensure each section answers its questions with meaningful content and populate registries from auto-discovery.

**Process**:

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

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

Define section parameters:
```
sections = [
  {
    "name": "Architecture Decision Records (ADRs)",
    "question": "Where are architecture decisions documented?",
    "directory": "docs/reference/adrs/",
    "placeholder": "{{ADR_LIST}}",
    "glob_pattern": "docs/reference/adrs/*.md",
    "heuristics": [
      "Contains link: [ADRs](adrs/) or [adrs](adrs/)",
      "Mentions 'Architecture Decision Record' or 'ADR'",
      "Has placeholder {{ADR_LIST}} or actual list",
      "Length > 30 words"
    ]
  },
  {
    "name": "Project Guides",
    "question": "Where are reusable project patterns documented?",
    "directory": "docs/reference/guides/",
    "placeholder": "{{GUIDE_LIST}}",
    "glob_pattern": "docs/reference/guides/*.md",
    "heuristics": [
      "Contains link: [Guides](guides/) or [guides](guides/)",
      "Has placeholder {{GUIDE_LIST}} or actual list",
      "Length > 20 words"
    ]
  },
  {
    "name": "Package Manuals",
    "question": "Where are third-party package references documented?",
    "directory": "docs/reference/manuals/",
    "placeholder": "{{MANUAL_LIST}}",
    "glob_pattern": "docs/reference/manuals/*.md",
    "heuristics": [
      "Contains link: [Manuals](manuals/) or [manuals](manuals/)",
      "Has placeholder {{MANUAL_LIST}} or actual list",
      "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 placeholder 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 placeholder with generated list
     - Track change: `sections_populated += 1`
   - If NO files:
     - Keep placeholder as-is
     - Track: `placeholders_kept += 1`

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

**3.3 Report content validation**:
- Log summary:
  ```
  ✅ Content validation complete:
    - Sections checked: 3
    - 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
```

---

## Reference Files Used

### Templates

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

**Validation Specification**:
- `references/questions.md` (v1.0) - Question-driven validation:
  - Questions each section must answer
  - Validation heuristics
  - Auto-discovery hints

---

## Best Practices

- **No premature validation**: Phase 1 creates structure, Phase 2 validates it (no duplicate checks)
- **Parametric validation**: Phase 3 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 → VALIDATE STRUCTURE → VALIDATE CONTENT

---

## Prerequisites

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

**Requires**:
- `docs/` directory (created by ln-111-root-docs-creator)

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

---

## Definition of Done

Before completing work, verify ALL checkpoints:

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

**✅ Structure Validated:**
- [ ] SCOPE tag present in first 5 lines
- [ ] Three registry sections present (ADRs, Guides, Manuals)
- [ ] Maintenance section present at end
- [ ] POSIX file endings compliant

**✅ Content Validated:**
- [ ] All sections checked against questions.md
- [ ] Placeholders populated from auto-discovery OR kept if no files
- [ ] No validation heuristic failures

**✅ Reporting:**
- [ ] Phase 1 logged: creation summary
- [ ] Phase 2 logged: structural fixes (if any)
- [ ] Phase 3 logged: content updates (if any)

---

## Technical Details

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

**Language**: English only

---

**Version:** 7.1.0 (MINOR: Workflow optimization - merged Phase 1+2 CREATE, removed redundant Phase 2 Step 3 verification, removed Phase 3.4 project-specific standards check, parametrized Phase 4 content validation. No functionality change, pure refactoring for clarity and efficiency.)
**Last Updated:** 2025-11-18