Engineering journal

Engineering Journal

在 Engineering KB 根目录中创建、恢复或更新工程档案。默认 KB 根目录是 ~/Documents/Obsidian/KB/engineering；如果用户明确指定其他 KB 路径、本地知识库路径或团队约定路径，则使用用户指定路径作为本轮 KB 根目录。此 skill 只负责事实沉淀与接力，不代替规划、调试、实现、评审或验证流程。以当前仓库和可复现证据为事实源；不得把 Memories 或未经验证的历史上下文当作事实。

本文中的 <KB_ROOT> 均指上述 KB 根目录。读取或运行 skill 内脚本、内置模板时，使用本次加载到的 engineering-journal skill 所在目录。

识别项目

先运行：

cd <engineering-journal-skill-dir> && node scripts/project_identity.mjs

脚本只读 Git，输出 git_root、git_common_dir、branch、head、sanitized_remote、project_id 和 project_key。project_id 保留完整 sanitized remote；project_key 默认使用远端仓库 basename，无远端时使用 Git root basename。同一 common dir 的 worktree 属于同一项目。脚本失败表示当前目录不属于 Git 仓库：不要创建档案，先说明并确认用户意图。

搜索与路径

1. 在 KB 根目录搜索 Markdown 文件名和内容中的 project_id、project_key、安全化远端、Git root、任务关键词、issue ID、别名和相关链接。
2. 检查候选文档的项目身份、范围、更新时间和关联关系。精确匹配时原地恢复；多个候选冲突时先消歧，不得创建近似重复档案。
3. 脚本输出的 basename key 是首选。只有搜索现有档案或 registry 发现同一 project_key 对应不同 project_id 时才升级：先用 <owner>-<repo>；仍冲突时追加 project_id 的稳定短 hash。不要因“可能冲突”预先扩大 key。
4. 沿用已有项目布局。仅在无匹配文档时使用最终消歧后的 key 和以下绝对路径，不得额外拼接 engineering：
   • <KB_ROOT>/projects/<project-key>/work-items/<task-slug>.md
   • <KB_ROOT>/projects/<project-key>/topics/<topic-slug>.md
   • <KB_ROOT>/projects/<project-key>/evidence/YYYY-MM-DD-<record-slug>.md

新项目自动初始化

当脚本识别出 Git 项目，但 KB 中没有匹配项目入口时，不要求用户手动初始化。按需自动创建最小 KB 和项目容器：

1. 若 <KB_ROOT> 不存在，创建 <KB_ROOT>、<KB_ROOT>/projects 和 <KB_ROOT>/_templates。
2. 若 <KB_ROOT>/_templates 缺少必需模板，从 skill 内置 templates/ 复制缺失模板；不得覆盖用户已修改的同名 KB 模板。
3. 创建 <KB_ROOT>/projects/<project-key>/ 及 work-items/、topics/、evidence/、raw/、events/ 子目录。
4. 从 <KB_ROOT>/_templates/project-index.md 创建 index.md，填入 project_key、标题、project_id、当前 Git root、branch、HEAD、远端摘要和创建时间。
5. 若 <KB_ROOT>/projects/_registry.md 存在且尚未包含该项目链接，追加 [[engineering/projects/<project-key>/index|<project-key>]]；若 registry 不存在，先创建最小 registry。
6. 再创建本轮需要的 work-item、topic 或 evidence。项目初始化和首份档案创建应写入项目入口事件日志。

自动初始化只建立空容器和索引，不迁移、不复制、不重命名旧资料；发现可能已有同项目旧目录但身份不确定时，先记录候选并向用户确认。

选择档案类型

主类型	使用条件	默认目录
work-item	有边界的 bug、需求、重构、发布或一次性交付，需要跨会话接力	work-items
topic-ledger	长期演进的模块、机制或技术主题，需要持续累积事实与决策	topics
analysis-report	某时点的调查、事故复盘、架构或代码分析，需要形成稳定结论	evidence

默认选择 work-item。只有生命周期、复用范围或读者明显不同才拆文档，并用 related 链接关联，避免复制。

复杂或可复用分析必须从主档案拆出 evidence-record，存入 evidence。evidence record 的 frontmatter 必须包含：

• validity: current、stale、superseded 或 disputed
• observed_at: 带时区的绝对时间
• source_revision: 观察时的完整 Git commit SHA
• supersedes: 被当前记录替代的 evidence record 链接数组

当代码、配置或环境已越过 source_revision 且尚未复核时，将 validity 改为 stale。新记录替代旧记录时，新记录填写 supersedes，旧记录改为 superseded 并链接新记录。

工作项状态机

status 只允许出现在 frontmatter。work-item 的状态值和转换固定为：

• backlog -> active
• active -> blocked | done | cancelled
• blocked -> active | done | cancelled
• done -> active，仅通过 reopen
• cancelled -> active，仅通过 reopen
• backlog -> cancelled

禁止其他转换。每次转换都更新时间并写一条事件；正文不得创建 Status 标题或字段。

正文约束

正文只维护两个操作区块；按需读取 templates.md：

1. Current Snapshot：最多 8 个顶层条目，使用标签维护以下信息：
   • Quick Handoff：目标、当前进展、下一步、阻塞点、可直接执行的下一条命令
   • Confirmed Fact：结论及文件行号、commit、命令/测试摘要或“用户明确提供”
   • Hypothesis：未确认内容、验证方法和当前结果
   • Decision：日期、选择、理由和替代关系
   • Verification：命令、时间、PASS/FAIL 和关键摘要
   • Risk：影响与缓解动作
2. Event Log：按时间倒序保留最近 10 条事件；每条包含绝对时间、类型、事实变化和证据。新增后立即裁剪到 10 条。

事实与假设必须分离。验证后把 hypothesis 转为 confirmed fact 或记录为否定事件。只写增量与摘要，不粘贴大段日志、代码或聊天记录。

复杂需求工作流

当需求横跨多功能点、多接口、多端入口、多轮澄清或联调反馈时，读取 complex-requirement-workflow.md。

复杂需求仍以 work-item 作为主档案，但必须额外维护：

• 事实源治理：记录 PRD/Cooper/导出文档/截图/用户澄清的优先级和覆盖关系。
• 需求矩阵：按功能点拆 原始需求 / 澄清口径 / 接口契约 / 现有链路 / 前端改动点 / 实现回填 / 验证点 / 待确认问题。
• 问题分层：区分产品需求问题、后端契约问题、前端实现问题和验证问题；PRD 已明确项不得继续列为待确认。
• 链路追踪：记录入口、接口、请求字段、响应字段、状态消费、参数出口和必要链路图。
• 实现前检查：确认需求闭环、契约足够、安全实施条件满足。
• 联调归因：按现象、接口响应、当前代码链路、根因、最小修复、回归点记录。
• 收尾分层：work-item 摘要、evidence 时点结论、topic/handbook 长期知识、raw 原始证据、模板复用起点。
• 版本化反哺：长期知识必须带观察版本、HEAD、来源 evidence/raw、失效信号；新需求结束时确认、修正或废弃旧结论。

复杂需求可使用 KB 模板： complex-requirement-matrix.md、integration-feedback-record.md、closeout-calibration.md。

Superpowers 路由

当前环境已安装 Superpowers 时，可按任务性质调用合适 skill，例如复杂 bug 使用 superpowers:systematic-debugging，实现或修复使用 superpowers:test-driven-development，完成声明前使用 superpowers:verification-before-completion。Superpowers 不是复杂需求工作流的强依赖；无对应 skill 时使用矩阵、检查清单和归因模板执行同等方法。Engineering Journal 始终只记录这些流程产生的事实、决策、验证和风险，不接管其方法或把 skill 输出自动视为已确认事实。

成本与安全

• 一次短会话即可完成、低不确定性且无接力价值的小任务，不主动新建档案；用户明确要求记录时使用最小模板。
• 优先更新已有档案；一个任务只选一个主档案。复杂证据仅在可复用或需要独立有效期时拆 record。
• 永不记录 token、cookie、密码、私钥、完整环境变量、带凭据 URL、内部个人数据或可复用认证材料。
• 写入前清理远端 URL、命令、日志和错误中的秘密，用 [REDACTED] 替代。发现疑似泄露时停止复制并提示安全处置。

完成检查

• 项目身份来自脚本的最新输出，并已搜索排重。
• <KB_ROOT> 已确定；缺失的 KB 必需模板已从 skill 内置 templates/ 补齐，且未覆盖用户已有模板。
• 路径位于 engineering/projects/<project-key>/...，且未重复拼接 KB 根目录段。
• 主类型、状态转换和 evidence record 拆分符合规则。
• frontmatter 之外没有 status 字段；snapshot 不超过 8 项，event log 不超过 10 条。
• facts、hypotheses、decisions、verification、risks 和 quick handoff 均按当前任务实际情况维护。
• 复杂需求已维护需求矩阵、问题分层、版本化事实和收尾反哺校准；若未维护，已在风险或待验证中说明原因。
• 下一会话能直接继续，且文档无秘密、无无必要的大段原始输出。