ln-120-reference-docs-creator

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):

{
  "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):
2. frontend: Justified if React/Vue/Angular/Svelte (multiple options exist)
3. backend: Justified if Express/Fastify/NestJS/Koa (multiple options exist)
4. database: Justified if PostgreSQL/MySQL/MongoDB (multiple options exist)
5. auth: Justified if JWT/OAuth/Session (decision required)
6. orm: Justified if Prisma/TypeORM/Sequelize (multiple options exist)
7. cache: Justified if Redis/Memcached (decision required)

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

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

1. Skip if not justified:
2. Log: "⊘ Skipped ADR for {category}: trivial choice"

2.4 Analyze TECH_STACK for Guides:

For each technology with complex configuration:

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

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

1. Skip if standard usage:
2. Log: "⊘ Skipped Guide for {technology}: standard usage"

2.5 Analyze TECH_STACK for Manuals:

For each package with complex API:

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

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

1. Skip if trivial API:
2. 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