Engineering journal

Skill xylvvv/agent-skills/skills/engineering-journal

Install

npx -y skills add xylvvv/agent-skills --skill engineering-journal

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when work in a Git repository needs a persistent engineering dossier, work item, investigation record, quick handoff, topic ledger, analysis report, or reusable evidence across projects or sessions.

SKILL.md

9.5 KB, as published. Nobody here has run it

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 仓库：不要创建档案，先说明并确认用户意图。

搜索与路径

在 KB 根目录搜索 Markdown 文件名和内容中的 project_id、project_key、安全化远端、Git root、任务关键词、issue ID、别名和相关链接。
检查候选文档的项目身份、范围、更新时间和关联关系。精确匹配时原地恢复；多个候选冲突时先消歧，不得创建近似重复档案。
脚本输出的 basename key 是首选。只有搜索现有档案或 registry 发现同一 project_key 对应不同 project_id 时才升级：先用 <owner>-<repo>；仍冲突时追加 project_id 的稳定短 hash。不要因“可能冲突”预先扩大 key。
沿用已有项目布局。仅在无匹配文档时使用最终消歧后的 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 和项目容器：

若 <KB_ROOT> 不存在，创建 <KB_ROOT>、<KB_ROOT>/projects 和 <KB_ROOT>/_templates。
若 <KB_ROOT>/_templates 缺少必需模板，从 skill 内置 templates/ 复制缺失模板；不得覆盖用户已修改的同名 KB 模板。
创建 <KB_ROOT>/projects/<project-key>/ 及 work-items/、topics/、evidence/、raw/、events/ 子目录。
从 <KB_ROOT>/_templates/project-index.md 创建 index.md，填入 project_key、标题、project_id、当前 Git root、branch、HEAD、远端摘要和创建时间。
若 <KB_ROOT>/projects/_registry.md 存在且尚未包含该项目链接，追加 [[engineering/projects/<project-key>/index|<project-key>]]；若 registry 不存在，先创建最小 registry。
再创建本轮需要的 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：

Current Snapshot：最多 8 个顶层条目，使用标签维护以下信息：
- Quick Handoff：目标、当前进展、下一步、阻塞点、可直接执行的下一条命令
- Confirmed Fact：结论及文件行号、commit、命令/测试摘要或“用户明确提供”
- Hypothesis：未确认内容、验证方法和当前结果
- Decision：日期、选择、理由和替代关系
- Verification：命令、时间、PASS/FAIL 和关键摘要
- Risk：影响与缓解动作
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 均按当前任务实际情况维护。
复杂需求已维护需求矩阵、问题分层、版本化事实和收尾反哺校准；若未维护，已在风险或待验证中说明原因。
下一会话能直接继续，且文档无秘密、无无必要的大段原始输出。