ln-120-reference-docs-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reference Documentation Creator

参考文档创建工具

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

本工具可基于项目TECH_STACK创建参考文档结构（docs/reference/）及智能文档（ADRs、指南、手册）。仅当技术选型具备合理性（存在可替代的非琐碎技术方案）时才会创建文档。

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)

本工具是L2工作组件，由ln-100-documents-pipeline编排器调用。

以下场景可直接使用本工具：

仅创建参考文档结构（docs/reference/）
为ADRs、指南和手册设置目录
无需创建完整文档结构（如需完整设置请使用ln-100-documents-pipeline）

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.

来自ln-100（通过ln-110上下文存储）：

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用于阶段2的智能文档创建。

How It Works

工作流程

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.

本工具遵循四阶段工作流：创建结构 → 智能文档生成 → 结构验证 → 内容验证。阶段2仅为具备合理性的技术选型创建文档。

Phase 1: Create Structure

阶段1：创建结构

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-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 4)
- ```
{{GUIDE_LIST}}
```
    — kept as placeholder (filled in Phase 4)
  - ```
  {{MANUAL_LIST}}
```
  — kept as placeholder (filled in Phase 4)
- 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

目标：建立参考文档目录及README枢纽。

流程：

1.1 检查并创建目录：

检查
```
docs/reference/adrs/
```
是否存在 → 不存在则创建
检查
```
docs/reference/guides/
```
是否存在 → 不存在则创建
检查
```
docs/reference/manuals/
```
是否存在 → 不存在则创建
检查
```
docs/reference/research/
```
是否存在 → 不存在则创建
为每个目录记录日志："✓ 已创建docs/reference/[name]/" 或 "✓ docs/reference/[name]/ 已存在"

1.2 检查并创建README：

检查
```
docs/reference/README.md
```
是否存在
若已存在：
- 跳过创建
- 记录日志："✓ docs/reference/README.md 已存在，继续执行验证步骤"
若不存在：
- 复制模板：
```
ln-112-reference-docs-creator/references/reference_readme_template.md
```
  →
```
docs/reference/README.md
```
- 替换占位符：
  - ```
  {{VERSION}}
```
  — "1.0.0"
- ```
{{DATE}}
```
    — 当前日期（YYYY-MM-DD）
  - ```
  {{ADR_LIST}}
```
  — 保留为占位符（阶段4填充）
- ```
{{GUIDE_LIST}}
```
    — 保留为占位符（阶段4填充）
  - ```
  {{MANUAL_LIST}}
```
  — 保留为占位符（阶段4填充）
- 记录日志："✓ 从模板创建docs/reference/README.md"

1.3 输出结构：

docs/reference/
├── README.md         # 已创建或已存在
├── adrs/            # 空目录，准备存放ADRs
├── guides/          # 空目录，准备存放指南
├── manuals/         # 空目录，准备存放手册
└── research/        # 空目录，准备存放研究文档

Phase 2: Smart Document Creation

阶段2：智能文档生成

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

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:
- 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
Create ADR if justified:
- Determine next ADR number:
```
adr-NNN-{category}.md
```
- Use template:
```
shared/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}"
Skip if not justified:
- Log: "⊘ Skipped ADR for {category}: trivial choice"

2.4 Analyze TECH_STACK for Guides:

For each technology with complex configuration:

Check if justified:
- Has config file with >20 lines
- Uses custom hooks/middleware/decorators
- Has 3+ related dependencies
Create Guide if justified:
- Determine next guide number:
```
NN-{technology-slug}-patterns.md
```
- Use template:
```
shared/templates/guide_template.md
```
- MCP Research:
```
mcp__Ref__ref_search_documentation("{technology} patterns 2025")
```
- 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}"
Skip if standard usage:
- Log: "⊘ Skipped Guide for {technology}: standard usage"

2.5 Analyze TECH_STACK for Manuals:

For each package with complex API:

Check if justified:
- Package has >10 exported methods
- Has breaking changes in current version
- NOT in trivial list: lodash, uuid, dotenv
Create Manual if justified:
- Use template:
```
shared/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}"
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]

目标：为具备合理性的技术选型创建ADRs、指南和手册。跳过琐碎/显而易见的选型。

2.1 检查上下文存储：

若未提供
```
context_store
```
→ 跳过阶段2，进入阶段3
若
```
context_store
```
中无
```
TECH_STACK
```
→ 跳过阶段2，进入阶段3
记录日志："已接收包含TECH_STACK的上下文存储：[分类数量]"

2.2 加载合理性规则：

读取
```
references/tech_justification_rules.md
```
解析分类→合理性/跳过条件

2.3 分析TECH_STACK以生成ADRs：

针对TECH_STACK中的每个分类（前端、后端、数据库、ORM、认证、缓存）：

检查是否具备合理性（依据合理性规则）：
- ```
frontend
```
  ：若为React/Vue/Angular/Svelte则具备合理性（存在多个可选方案）
- ```
backend
```
  ：若为Express/Fastify/NestJS/Koa则具备合理性（存在多个可选方案）
- ```
database
```
  ：若为PostgreSQL/MySQL/MongoDB则具备合理性（存在多个可选方案）
- ```
auth
```
  ：若为JWT/OAuth/Session则具备合理性（需要决策）
- ```
orm
```
  ：若为Prisma/TypeORM/Sequelize则具备合理性（存在多个可选方案）
- ```
cache
```
  ：若为Redis/Memcached则具备合理性（需要决策）
若为琐碎选型则跳过：
- 仅使用jQuery的前端（无框架选择）
- 简单HTTP服务器（无框架）
- 仅用于开发环境的SQLite
- 无需认证
- 仅使用原生SQL
- 仅使用内存缓存
若具备合理性则创建ADR：
- 确定下一个ADR编号：
```
adr-NNN-{category}.md
```
- 使用模板：
```
shared/templates/adr_template.md
```
- MCP研究：
```
mcp__context7__resolve-library-id(technology)
```
- 填充模板：
  - 标题："ADR-NNN: {Category} 选型"
  - 背景：为何需要该决策
  - 决策：选定的技术及版本
  - 理由：来自研究的3个核心原因
  - 替代方案：2个其他可选方案的优缺点
- 保存至：
```
docs/reference/adrs/adr-NNN-{category}.md
```
- 记录日志："✓ 为{category}创建ADR：{technology}"
若不具备合理性则跳过：
- 记录日志："⊘ 跳过{category}的ADR创建：琐碎选型"

2.4 分析TECH_STACK以生成指南：

针对每个配置复杂的技术：

检查是否具备合理性：
- 配置文件行数超过20行
- 使用自定义钩子/中间件/装饰器
- 存在3个及以上相关依赖
若具备合理性则创建指南：
- 确定下一个指南编号：
```
NN-{technology-slug}-patterns.md
```
- 使用模板：
```
shared/templates/guide_template.md
```
- MCP研究：
```
mcp__Ref__ref_search_documentation("{technology} patterns 2025")
```
- 填充模板：
  - 原则：来自研究的行业标准
  - 我们的实现：项目如何使用该技术
  - 模式表格：3条Do/Don't/When条目
- 保存至：
```
docs/reference/guides/NN-{technology}-patterns.md
```
- 记录日志："✓ 为{technology}创建指南"
若为标准用法则跳过：
- 记录日志："⊘ 跳过{technology}的指南创建：标准用法"

2.5 分析TECH_STACK以生成手册：

针对每个API复杂的包：

检查是否具备合理性：
- 包的导出方法超过10个
- 当前版本存在破坏性变更
- 不在琐碎列表中：lodash、uuid、dotenv
若具备合理性则创建手册：
- 使用模板：
```
shared/templates/manual_template.md
```
- MCP研究：
```
mcp__context7__get-library-docs(topic: "API")
```
- 填充模板：
  - 包信息及版本
  - 2-3个最常用的方法
  - 配置章节
- 保存至：
```
docs/reference/manuals/{package}-{version}.md
```
- 记录日志："✓ 为{package}创建手册"
若API琐碎则跳过：
- 记录日志："⊘ 跳过{package}的手册创建：API琐碎"

2.6 智能生成报告：

✅ 智能文档生成完成：
  - 已创建ADRs：[数量]（具备合理性的分类：前端、后端、数据库）
  - 已跳过ADRs：[数量]（琐碎选型：缓存=内存缓存）
  - 已创建指南：[数量]
  - 已跳过指南：[数量]
  - 已创建手册：[数量]
  - 已跳过手册：[数量]

Phase 3: Validate Structure

阶段3：结构验证

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
```

```
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"
- "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"

目标：确保reference/README.md符合结构要求并自动修复违规项。

流程：

2.1 检查SCOPE标签：

读取
```
docs/reference/README.md
```
（前5行）
检查是否存在
```

```
标签

预期内容：

<!-- SCOPE: Reference documentation hub (ADRs, Guides, Manuals) with links to subdirectories -->

若缺失：
- 使用编辑工具在第1行（第一个标题后）添加SCOPE标签
- 记录违规：
```
scope_tag_added = True
```

2.2 检查必填章节：

从
```
references/questions.md
```
加载预期章节
必填章节：
- "Architecture Decision Records (ADRs)"
- "Project Guides"
- "Package Manuals"
- "Research"
针对每个章节：
- 检查是否存在
```
## [Section Name]
```
  标题
- 若缺失：
  - 使用编辑工具添加带占位符的章节：
    markdown
```
## [Section Name]

{{PLACEHOLDER}}
```
  - 记录违规：
```
missing_sections += 1
```

2.3 检查维护章节：

搜索
```
## Maintenance
```
标题

若缺失：

使用编辑工具在文件末尾添加：

markdown

## 维护

**最后更新时间：** [当前日期]

**更新触发条件：**
- adrs/目录中新增ADRs
- guides/目录中新增指南
- manuals/目录中新增手册

**验证项：**
- [ ] 注册表中的所有ADR链接均有效
- [ ] 注册表中的所有指南链接均有效
- [ ] 注册表中的所有手册链接均有效
- [ ] 占位符{{ADR_LIST}}、{{GUIDE_LIST}}、{{MANUAL_LIST}}与文件同步

记录违规：
```
maintenance_added = True
```

2.4 检查POSIX文件结尾：

检查文件是否以单个空行结尾
若缺失：
- 使用编辑工具添加最终换行符
- 记录修复：
```
posix_fixed = True
```

2.5 验证报告：

记录日志摘要：

✅ 结构验证完成：
  - SCOPE标签：[已添加/已存在]
  - 缺失章节：已添加[数量]个章节
  - 维护章节：[已添加/已存在]
  - POSIX结尾：[已修复/符合要求]

若发现违规项："⚠️ 自动修复了[总数]个结构违规项"

Phase 4: Validate Content

阶段4：内容验证

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/",
    "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"
    ]
  },
  {
    "name": "Research",
    "question": "Where are research/investigation documents stored?",
    "directory": "docs/reference/research/",
    "placeholder": "{{RESEARCH_LIST}}",
    "glob_pattern": "docs/reference/research/*.md",
    "heuristics": [
      "Contains link: [Research](research/) or [research](research/)",
      "Has placeholder {{RESEARCH_LIST}} or actual list",
      "Length > 20 words"
    ]
  }
]

For each section in sections:

Read section content:
- Extract section from reference/README.md
Check if content answers question:
- Apply validation heuristics
- If ANY heuristic passes → content valid, skip to next section
- If ALL fail → content invalid, continue
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
```
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]

目标：确保每个章节的内容能有效回答对应问题，并通过自动发现（包括阶段2创建的文档）填充注册表。

流程：

4.1 加载验证规范：

读取
```
references/questions.md
```
解析所有3个章节的问题及验证启发式规则

4.2 验证章节（参数化循环）：

定义章节参数：

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"
    ]
  },
  {
    "name": "Research",
    "question": "Where are research/investigation documents stored?",
    "directory": "docs/reference/research/",
    "placeholder": "{{RESEARCH_LIST}}",
    "glob_pattern": "docs/reference/research/*.md",
    "heuristics": [
      "Contains link: [Research](research/) or [research](research/)",
      "Has placeholder {{RESEARCH_LIST}} or actual list",
      "Length > 20 words"
    ]
  }
]

针对每个章节：

读取章节内容：
- 从reference/README.md中提取章节内容
检查内容是否回答对应问题：
- 应用验证启发式规则
- 若任意规则通过 → 内容有效，跳至下一章节
- 若所有规则失败 → 内容无效，继续执行
自动发现（若内容无效或存在占位符）：
- 使用Glob工具扫描目录（section.glob_pattern）
- 若发现文件：
  - 提取文件名
  - 生成动态列表：
    markdown
```
- [ADR-001: 前端框架](adrs/adr-001-frontend-framework.md)
- [02-仓库模式](guides/02-repository-pattern.md)
- [Axios 1.6](manuals/axios-1.6.md)
```
  - 使用编辑工具将占位符替换为生成的列表
  - 记录变更：
```
sections_populated += 1
```
- 若未发现文件：
  - 保留占位符不变
  - 记录：
```
placeholders_kept += 1
```
跳过外部API调用：
- 不使用MCP Ref搜索（模板已包含格式示例）

4.3 内容验证报告：

记录日志摘要：

✅ 内容验证完成：
  - 已检查章节：4个
  - 通过自动发现填充：[数量]
  - 保留占位符（无文件）：[数量]
  - 已有效：[数量]

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

docs/
└── reference/
    ├── README.md                     # 包含注册表的参考枢纽
    ├── adrs/                         # 空目录或包含ADR文件
    ├── guides/                       # 空目录或包含指南文件
    ├── manuals/                      # 空目录或包含手册文件
    └── research/                     # 空目录或包含研究文件

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

Document Templates (for Phase 2 Smart Creation):

```
shared/templates/adr_template.md
```
- Nygard ADR format (7 sections)
```
shared/templates/guide_template.md
```
- Pattern documentation (Do/Don't/When)
```
shared/templates/manual_template.md
```
- API reference format
```
shared/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

参考README模板：

```
references/reference_readme_template.md
```
（v2.0.0）- 参考枢纽，包含：
- SCOPE标签（仅参考文档）
- 三个带占位符的注册表章节
- 维护章节

文档模板（用于阶段2智能生成）：

```
shared/templates/adr_template.md
```
- Michael Nygard的ADR格式（7个章节）
```
shared/templates/guide_template.md
```
- 模式文档格式（Do/Don't/When）
```
shared/templates/manual_template.md
```
- API参考格式
```
shared/templates/research_template.md
```
- 研究/探索文档格式

合理性规则：

```
references/tech_justification_rules.md
```
- 映射：分类→创建/跳过条件

验证规范：

```
references/questions.md
```
（v2.0）- 基于问题的验证：
- Q1-Q3：注册表章节（ADRs、指南、手册）
- Q4-Q7：智能文档验证（ADR背景、替代方案、模式）
- 自动发现提示

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

避免过早验证：阶段1创建结构，阶段3才进行验证
智能生成：阶段2仅为具备合理性的选型创建文档
参数化验证：阶段4使用循环处理3个章节（无代码重复）
优先自动发现：先扫描实际文件再调用外部API
幂等性：✅ 可安全多次运行（创建前检查是否已存在）
关注点分离：创建→智能文档→结构验证→内容验证

NO_CODE_EXAMPLES Rule (MANDATORY for Guides)

NO_CODE_EXAMPLES规则（指南强制要求）

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
```

```
tag - FOLLOW IT

指南记录模式，而非实现细节：

禁止：完整函数实现、超过5行的代码块
允许：Do/Don't/When表格、方法签名（1行）、伪代码（1-3行）
替代代码的方案：引用源代码位置："参见src/hooks/usePlan.ts:15-30"
模板规则：guide_template.md包含
```

```
标签 - 请严格遵循

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)

ADRs必须引用与当前技术栈适配的替代方案（对比React与Vue，而非React与Django）
指南必须链接至对应平台的官方文档（.NET链接Microsoft文档，JS链接MDN）

Format Priority (MANDATORY)

格式优先级（强制要求）

Tables (Do/Don't/When) > ASCII diagrams > Lists > Text

表格（Do/Don't/When）> ASCII图 > 列表 > 文本

Prerequisites

前置条件

Invoked by: ln-110-documents-pipeline orchestrator

Requires:

```
docs/
```
directory (created by ln-111-project-docs-creator)

Creates:

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

调用者：ln-110-documents-pipeline编排器

依赖：

```
docs/
```
目录（由ln-111-project-docs-creator创建）

创建内容：

带README枢纽的
```
docs/reference/
```
目录结构
经过验证的结构和内容（通过自动发现现有文件填充）

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 present in first 5 lines
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
Placeholders populated from auto-discovery (including Phase 2 documents)
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)
Phase 4 logged: content updates (if any)

完成工作前，请验证所有检查点：

✅ 阶段1 - 结构已创建：

```
docs/reference/
```
目录存在
```
docs/reference/adrs/
```
目录存在
```
docs/reference/guides/
```
目录存在
```
docs/reference/manuals/
```
目录存在
```
docs/reference/research/
```
目录存在
```
docs/reference/README.md
```
存在（已创建或已存在）

✅ 阶段2 - 智能文档已生成（若提供上下文存储）：

为具备合理性的技术选型创建了ADRs（非琐碎选型）
已跳过琐碎选型的ADRs创建（已记录日志）
为配置复杂的技术创建了指南
为API复杂的包创建了手册
每个已创建的文档均包含真实内容（非占位符）

✅ 阶段3 - 结构已验证：

SCOPE标签存在于前5行
四个注册表章节均存在（ADRs、指南、手册、研究）
文件末尾存在维护章节
符合POSIX文件结尾要求

✅ 阶段4 - 内容已验证：

所有章节均已对照questions.md检查
占位符已通过自动发现填充（包括阶段2创建的文档）
无验证启发式规则失败

✅ 报告：

已记录阶段1的创建摘要
已记录阶段2的智能生成（已创建/已跳过数量）
已记录阶段3的结构修复（若有）
已记录阶段4的内容更新（若有）

Technical Details

技术细节

Standards:

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

Language: English only

Version: 8.2.0 (Added Stack Adaptation and Format Priority rules) Last Updated: 2025-01-12

标准：

Michael Nygard的ADR格式（7个章节）
ISO/IEC/IEEE 29148:2018（文档标准）

语言：仅支持英语

版本： 8.2.0（新增栈适配规则和格式优先级规则） 最后更新时间： 2025-01-12