with one click
ln-120-reference-docs-creator
// Creates reference docs (ADRs, guides, manuals) for nontrivial tech stack choices. Use when project needs justified architecture decision records.
// Creates reference docs (ADRs, guides, manuals) for nontrivial tech stack choices. Use when project needs justified architecture decision records.
[HINT] Download the complete skill directory including SKILL.md and all related files
| 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.
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).
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.
This skill is a L2 WORKER invoked by ln-100-documents-pipeline orchestrator.
This skill should be used directly when:
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.
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.
Objective: Establish reference documentation directories and README hub.
Process:
1.1 Check & create directories:
docs/reference/adrs/ exists ā create if missingdocs/reference/guides/ exists ā create if missingdocs/reference/manuals/ exists ā create if missingdocs/reference/research/ exists ā create if missing1.2 Check & create README:
docs/reference/README.md existsln-120-reference-docs-creator/references/templates/reference_readme_template.md ā docs/reference/README.md{{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.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
Objective: Create ADRs, Guides, and Manuals for justified technology choices. Skip trivial/obvious selections.
2.1 Check Context Store:
context_store provided ā skip Phase 2, proceed to Phase 3TECH_STACK in context_store ā skip Phase 2, proceed to Phase 32.2 Load Justification Rules:
references/tech_justification_rules.md2.3 Analyze TECH_STACK for ADRs:
For each category in TECH_STACK (frontend, backend, database, orm, auth, cache):
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)Skip if trivial:
Create ADR if justified:
adr-NNN-{category}.mdreferences/templates/adr_template.mdmcp__context7__resolve-library-id(technology)docs/reference/adrs/adr-NNN-{category}.mdSkip if not justified:
2.4 Analyze TECH_STACK for Guides:
For each technology with complex configuration:
Check if justified:
Create Guide if justified:
NN-{technology-slug}-patterns.mdreferences/templates/guide_template.mdmcp__Ref__ref_search_documentation("{technology} patterns {current_year}")docs/reference/guides/NN-{technology}-patterns.mdSkip if standard usage:
2.5 Analyze TECH_STACK for Manuals:
For each package with complex API:
Check if justified:
Create Manual if justified:
references/templates/manual_template.mdmcp__context7__get-library-docs(topic: "API")docs/reference/manuals/{package}-{version}.mdSkip if 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]
Objective: Ensure reference/README.md complies with structural requirements and auto-fix violations.
Process:
2.1 Check opening contract:
docs/reference/README.md (first 5 lines)<!-- SCOPE: ... --> tag and metadata markers<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->opening_contract_fixed = True2.2 Check required sections:
references/questions.md## [Section Name] header exists## [Section Name]
{{PLACEHOLDER}}
missing_sections += 12.3 Check Maintenance section:
## Maintenance header## 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
maintenance_added = True2.4 Check POSIX file endings:
posix_fixed = True2.5 Report validation:
ā
Structure validation complete:
- SCOPE tag: [added/present]
- Missing sections: [count] sections added
- Maintenance section: [added/present]
- POSIX endings: [fixed/compliant]
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:
references/questions.md4.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:
Read section content:
Check if content answers question:
Auto-discovery (if content invalid or empty-state present):
- [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)
sections_populated += 1empty_states_kept += 1Skip external API calls:
4.3 Report content validation:
ā
Content validation complete:
- Sections checked: 4
- Populated from auto-discovery: [count]
- Placeholders kept (no files): [count]
- Already valid: [count]
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 README Template:
references/templates/reference_readme_template.md (v2.0.0) - Reference hub with:
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 formatreferences/templates/research_template.md - Research/Spike documentationJustification Rules:
references/tech_justification_rules.md - Mapping: category ā create/skip conditionsValidation Specification:
references/questions.md (v2.0) - Question-driven validation:
MANDATORY READ: Load references/research_tool_fallback.md
Guides document patterns, NOT implementations:
<!-- NO_CODE_EXAMPLES: ... --> tag - FOLLOW ITTables (Do/Don't/When) > ASCII diagrams > Lists > Text
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 hubMANDATORY READ: Load references/docs_generation_summary_contract.md
Accept optional summaryArtifactPath.
Summary kind:
docs-generationRequired payload semantics:
worker = "ln-120"statuscreated_filesskipped_filesquality_inputsvalidation_statuswarningsWrite the summary to the provided artifact path or return the same envelope in structured output.
Before completing work, verify ALL checkpoints:
ā Phase 1 - Structure Created:
docs/reference/ directory existsdocs/reference/adrs/ directory existsdocs/reference/guides/ directory existsdocs/reference/manuals/ directory existsdocs/reference/research/ directory existsdocs/reference/README.md exists (created or existing)ā Phase 2 - Smart Documents Created (if Context Store provided):
ā Phase 3 - Structure Validated:
ā Phase 4 - Content Validated:
ā Reporting:
Return normalized status to ln-100:
{
"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):
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.
Standards:
Language: English only
Version: 8.2.0 Last Updated: 2025-01-12