用途:为流水线(pipeline)系统生成技术文档,分两种模式。Stage 模式针对单个 Stage 输出实现文档(13 节,0-12),涵盖文档元信息、Stage 在流水线中的角色、职责与非目标、输入与上游依赖、输出与下游契约、核心处理流程、Prompt/规则/引用契约、校验与失败处理、可观测性与调试、兼容与迁移、已知问题、版本化变更、事实来源。Pipeline 模式针对整体系统输出架构演进文档(14 节,0-13),涵盖元信息、背景与问题、当前快照、演进目标与设计原则、关键架构变更、跨 Stage 契约变化、数据流与产物演进、系统级权衡、影响分析、评估与验证、迁移与上线计划、已知风险、版本化演进历史、参考来源。
模式选择:请求提到具体 stage/组件名、"stage 文档"、"stage 实现文档"等时用 Stage 模式;提到 "pipeline"、"架构"、"架构演进"、"跨 stage"、"系统" 等时用 Pipeline 模式;无法判断时应询问用户,不要猜测。
使用方式:先解析目标周,命令为 python <this-skill>/scripts/lode_raw.py week,可加 --date YYYY-MM-DD;不要手工推算 ISO 周。随后检查目标 docs/ 目录是否已有文档:Stage 模式匹配 lode-stage-{stage_name}-implementation-v*.md,Pipeline 模式匹配 lode-pipeline-evolution-v*.md;已存在则写增量文档(v{N+1}),只含指向基础文档的链接、更新后的第 0 节、变化章节、第 12 节版本记录与第 13 节参考,不重复未变章节。再按复杂度选择完整模式或最小模式,读取对应规范文件(references/stage-implementation-spec.md 或 references/pipeline-doc.md),以代码为事实来源逐节撰写,输入输出需给出 JSON 示例,并用 ASCII 图表达数据流、schema 与调用关系。输出默认保存到项目内 docs/{YYYY-WNN}/,若配置 arch_doc.output_dir 则优先使用(相对路径基于项目根,绝对路径原样使用)。完成后可追加变更条目:python <this-skill>/scripts/lode_raw.py append-entry --entry /tmp/lode-arch-doc-entry.json --cwd "$PWD";并可用 upsert-artifact 写入产物索引。
限制:若引用的代码、源文档或系统证据无法访问,不应生成完整文档,应说明缺失来源与所需路径,或仅在用户明确要求模板时生成带证据缺口说明的骨架,不得编造函数名、schema、prompt、字段或数据流。配置无法解析、helper 不可用或写入失败时,跳过 raw entry 与产物索引副作用,仅报告生成的文档路径。文档输出不依赖 vault 配置。