lets-work

lets-work

工作会话的入场仪式。读取用户对这个项目的个人状态，告知他们上次访问后有哪些变化，并安排本次会话如何结束。

仪式的分量必须与变化程度成正比。 这项技能的价值在于用户离开一段时间后重新开始工作；它绝不能变成用户每次会话都要等候通过的关卡。如果上次访问后几乎没有变化或毫无变化，整个入场流程就只有一行（“从昨天到现在没什么变化——我们接下来做什么？”），然后立即开始工作。下方的完整简报适用于确实离开了一段时间的情况。

个人状态（零痕迹约定）

所有状态都存放在目标项目之外、由用户拥有的目录中。绝不要将任何状态或对此技能包的引用写入目标项目的文件、提交、PR 或 issue。

• 根目录：${XDG_DATA_HOME:-$HOME/.local/share}/identity16-skills/projects/<repo-id>/
• repo-id：将规范化的 origin 远程 URL 转换为 slug——去掉协议、凭据和 .git；将 / 和 : 替换为 __（例如 github.com__rust-lang__rust）。如果仓库没有远程地址，则以相同方式将仓库的绝对路径转换为 slug。
• 文件（首次使用时创建）：
  • state.json — { "last_visit": { "commit": "<sha>", "date": "<ISO date>", "branch": "<name>" } }
  • dossier.md — 用户对该项目的认知模型：架构说明、关键不变量、易踩的坑、项目的工具栈（讨论在哪里进行、工作在哪里跟踪、如何发布），以及指向仓库中上下文所在位置的链接。只保存那些在仓库本身没有归属的信息——它是备用资料，而不是仓库自身文档的副本。
  • journal.md — 仅追加的会话日志：日期、学到的内容、待解决的问题、WIP 状态。

步骤

1. 根据当前仓库推导出 repo-id，并查找其状态目录。
2. 再次访问（状态存在）：
   • 读取 state.json、dossier.md 和 journal.md 中最近的条目。
   • 将实际情况与已存模型进行比较：git log --oneline <last_visit.commit>..HEAD 和 git diff --stat <last_visit.commit>..HEAD。如果记录的提交已不存在（变基、gc），则回退到 git log --since=<last_visit.date>。
   • 先评估偏差程度。 偏差很小或没有偏差（最近刚访问过、其他人提交很少或没有提交，也没有改动 dossier 涵盖的区域）→ 用一行确认没有偏差，提及任何未完成的 WIP 备注，然后直接进入第 5 步。否则：
   • 结合用户的笔记，而不是泛泛地罗列变更日志，向用户简要说明：哪些 dossier 条目已过时或与现状矛盾，哪些 journal 中的未解问题已由新提交解答，哪些区域属于新领域。保持简短，并引用提交/PR 作为依据。
   • 指出 journal 中仍未解决的问题和 WIP 备注。
3. 首次访问（无状态）：
   • 说明这是首次访问，然后建立一份精简的初始 dossier：入口点、模块映射、可验证的不变量、工具栈（对于无法从仓库中发现的信息，询问用户）。只记录仓库自身文档未能清楚说明的内容。
   • 使用当前提交写入 state.json。
4. 如果用户尚未说明此行的目的，就询问。当任务已明确，且涉及 dossier 标记为不确定或未知的领域时，运行 depth-check（如果已安装；否则简要说明需要先了解什么）。如果该领域已知，就不要发表意见，直接开始。
5. 设定本次会话的原则。 在本次会话余下时间里，遵循用户的理念：
   • 只交付用户理解的决策。 在非琐碎的决策写入代码库之前，将其摆出来——说明做出的选择、舍弃的替代方案，以及选错会导致什么后果——让用户认可，而不只是接受。绝不要把判断藏在大型差异中。
   • 优先将理解放在最持久的地方，按优先级排列：首先是直观的代码和结构；代码必须保持复杂时，添加简洁的“原因”注释；其次是组织良好的提交消息和 PR 描述；个人存储只用于无法在仓库中找到合适归属的内容。工作期间持续践行，而不是只在最后处理。
   • 在恰当时机使用工具包中的工具（已安装的工具）：问题或想法需要转成工单 → 使用 make-ticket（为问题创建工单，绝不为解决方案创建工单）；用户询问现有代码为何如此 → 使用 why（挖掘记录，绝不臆测理由）；分支历史需要在审查前整理 → 建议使用 organize-commits；用户即将审查、批准或交付自己尚未理解的差异——无论是他人的 PR，还是 Agent 刚编写的大型差异 → 使用 explain（根据记录建立理解，绝不编造理由）。在自然的时机只提出一次；用户可自由拒绝。
   • 准备好结束仪式，并自行判断时机。 不要等待某些神奇的关键词；应根据会话内容判断是否已到自然的收尾点，并在此时提议使用 /checkpoint。信号大致按强弱排序：开始时说明的任务已完成，且没有接手新任务；一个工作单元刚刚交付（已创建 PR、已推送分支、已完成合并）；用户明确表示收尾（“今天就到这里”“这里完成了”）或语气接近告别。若本次会话积累了实质性经验，应优先选择刚交付后的暂停时机，而不是等待可能永远不会出现的告别——会话往往会在没有告别的情况下结束。还要权衡 checkpoint 实际能记录什么：毫无收获的会话完全不必提议。只提议一次；如果用户拒绝，就不再提——用户随时可以自行调用 /checkpoint。

防护准则

• 简报必须提升理解，而不仅仅是节省阅读时间：始终将变更与用户记录的模型联系起来。
• 会话框架是行为准则，而不是讲课内容：工作时默默应用；不要向用户复述。
• 绝不让用户因繁文缛节而等待：没有偏差就不做简报，任务已命名就不提问。