weekly-setup-improvements

/weekly-setup-improvements -- 每周自我改进审查

审查文件夹中过去 7 天的工作，并撰写一份结构化改进报告。这是状态反思，不是日记——输出应具体、可执行，并且足够简短，让忙碌的实践者愿意阅读。

核心原则

每周都会形成一些模式。大多数模式都指向一个显而易见的下一步——需要更新的上下文文件、应该添加的斜杠命令，或需要整理的目录。运行此技能只需几分钟；而不运行它的代价，则是数月间设置悄然偏离。

此技能的用途（以及非用途）

	此技能	非此技能
范围	一个文件夹	整台机器
时间范围	最近 7 天	所有时间
输出	面向未来的行动	回顾过去的日记
同类工具	/vault-audit（快照，无时间范围）、/claude-md-audit（仅审查 CLAUDE.md 偏离情况）

参数

• 参数 1（可选）： 工作文件夹的路径。默认为 pwd。

流程

阶段 1：范围

1. 确定工作文件夹：
   • 如果提供了参数，验证路径是否存在且为目录；否则以清晰的错误信息中止。
   • 否则使用 pwd。
2. 计算时间范围。仅使用可移植的 shell：

   TODAY=$(date +%Y-%m-%d)
   # 7-day boundary as ISO date (portable):
   START=$(python3 -c "from datetime import date,timedelta; print(date.today()-timedelta(days=7))")
   

   不要使用 date -v-7d（仅适用于 macOS）或 date -d（仅适用于 GNU）。
3. 继续之前，先向用户说明审查范围： Auditing <folder> for the period <START> to <TODAY>.

阶段 2：调查

收集原始信号。尽可能并行运行以下命令：

WORKING_FOLDER="$1"

# Files modified in the last 7 days (skip dotdirs and dependency dirs)
find "$WORKING_FOLDER" -type f -mtime -7 \
  -not -path '*/.*' -not -path '*/node_modules/*' \
  -not -path '*/.venv/*' -not -path '*/dist/*' -not -path '*/target/*' \
  | head -150

# Git activity if folder is a repo (use --since= flag, portable across platforms)
git -C "$WORKING_FOLDER" log --since="7 days ago" --oneline 2>/dev/null
git -C "$WORKING_FOLDER" log --since="7 days ago" --stat --no-merges 2>/dev/null | head -300
git -C "$WORKING_FOLDER" status --porcelain 2>/dev/null

# Recently touched directories (signals new work areas)
find "$WORKING_FOLDER" -type d -mtime -7 -not -path '*/.*' | head -30

# File-type distribution (signals task type: code, prose, config, data)
find "$WORKING_FOLDER" -type f -mtime -7 -not -path '*/.*' \
  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10

如果该文件夹不是 git 仓库，则静默跳过 git 命令，仅依靠 find -mtime。

阶段 3：阅读

查找并阅读以下存在的文件（缺失时正常跳过）：

• CLAUDE.md（Claude Code 项目上下文）
• MEMORY.md（记忆索引）
• AGENTS.md（Agent 上下文）
• about-me.md、voice-and-style.md、working-rules.md（Karpathy 风格的上下文锚点）
• 根目录附近 memory/、context/ 或 docs/ 子目录中的任何 *.md
• （V2）最近一份先前的 weekly-setup-improvements-*.md（归档的上一份报告）。阅读其中的行动项——这些内容将用于新的第 0 节闭环检查。
• （V3）如果存在，则检查 _drafts/ 目录。其中的每个子目录都是前几周留下的技能草稿。这些草稿的状态（是否有过修改？是否已删除？是否已转入主技能目录？）本身就是一种信号——参见下文的视角 6。

这些是第 1 节（上下文文件更新）的检查对象。

Phase 4：ANALYZE

按以下特定视角依次检查 Phase 2 中的信号。检查每个视角时，先记录发现，再继续下一个：

1. 重复。 按名称对修改文件列表和 git log 排序；标记出现不止一次的基本名称模式（linkedin-*-draft.md、使用相同动词的重复提交、同级 fixture）。每处重复都可能对应一个技能。
2. 手动操作。 查找类似“修错别字 / 修错别字 / 修错别字”或“添加文件 / 删除文件 / 重新添加文件”的一系列小提交——这些工作流本该由脚本或 hook 完成。
3. 偏差。 对 Phase 3 中读取的每个上下文文件，找出其中一项声明（路径、工具、约束），并检查过去一周的工作是否与之矛盾。列出每处矛盾，并用一行说明如何修复。
4. 臃肿。 找出早于审计窗口且不再符合当前命名规范的文件；*-draft-N.md 同级文件；可归档的候选项。
5. 成效。 本周哪种模式显然奏效了？指出能证明这一点的文件或提交。先指出证据，再总结规律。
6. （V2，在 V3 中强化）后续跟进 + 清理僵尸项。 根据上一份报告（Phase 3）检查每个行动项：已完成、部分完成、已搁置，或连续第二个周期搁置。证据 = 一次提交、一个新文件、一处修改行，或者——对于草稿——一个曾被修改、删除或转正的 _drafts/<name>/ 目录。计算一行结项率（“完成 5 项中的 3 项”）。连续两次搁置的行动项必须在第 0 节中明确终止，并用一行说明理由；不得在本周的建议中再次出现。（来源：TeamRetro 2026 年回顾反模式——“僵尸行动项”是复盘无法推动改变的首要原因。）
7. （V2）先找根因，再提修复方案。 对每种反复出现的痛点，在提出修复方案前快速进行一次五个为什么分析，确保第 3 节解决的是根因，而非症状。（回顾证据：针对症状采取的行动会在每个周期中被重新提出。）
8. （V3）找出差距中的主要根因。 对每个差距进行五个为什么分析（视角 7）后，综合所有根因，指出本周造成最多痛点的那个原因——即帕累托根因。将其放在第 3 节开头，位于各个差距列表之前。如果两个原因并列，则同时列出，然后停止。（来源：运营 / Lean 中的帕累托原则。）

如果已安装 compound-engineering:ce-sessions，可以选择使用它来发现对话主题（例如：“用户本周三次停下来询问‘如何做 X’”）。如果未安装则跳过——该技能必须能够独立运行。

Phase 5：WRITE

输出文件： <WORKING_FOLDER>/weekly-setup-improvements.md

如果已有上一份报告： 写入前，先将其归档：

PRIOR="$WORKING_FOLDER/weekly-setup-improvements.md"
if [ -f "$PRIOR" ]; then
  PRIOR_DATE=$(grep -m1 '^# Weekly Setup Improvements' "$PRIOR" | sed -E 's/.*— ([A-Za-z]+ [0-9]+, [0-9]+).*/\1/' | tr ' ,' '--')
  [ -z "$PRIOR_DATE" ] && PRIOR_DATE=$(date -r "$PRIOR" +%Y-%m-%d 2>/dev/null || echo "$START")
  mv "$PRIOR" "$WORKING_FOLDER/weekly-setup-improvements-$PRIOR_DATE.md"
fi

结构（严格使用以下结构）：

# Weekly Setup Improvements — <Month Day, Year>

Based on review of <one-line scope>: files modified, git activity, and patterns from <START> to <TODAY>.

---

## 0. Last Week's Actions  *(V2 — skip if no prior report)*

Closure rate: <N of M done>. One line per prior action: ✅ done (evidence) / ◐ partial / ✗ dropped (why) / 💀 **killed** (dropped 2× — rationale). A killed action does not reappear in this week's Section 2/3 — explain why we cut it and stop re-surfacing it. *(V3: zombie-action kill rule.)*

## 1. Context File Updates

For each context file, give one of:
- **Create:** path + suggested content (in a code block)
- **Update:** path + the specific lines to add or change
- **No change:** path + one-line reason it's still accurate

## 2. New Skill Ideas

Cap at 3. Quality over quantity. For each:
- `/skill-name` — one-line description
- **What it does:** 2-3 bullets
- **Trigger phrases:** when the user would invoke it (cite the surfaced repetition)
- **Draft:** *(V3)* `_drafts/<skill-name>/SKILL.md` created (or "draft exists, last touched <date>" if it already did from a prior week)

## 3. Workflow Gaps

**Dominant root cause this week:** *(V3 — one sentence naming the Pareto cause across the gaps below; if two tie, name both.)*

Each gap is one bullet group:
- **Did manually:** what
- **Root cause:** *(V2)* the Five-Whys result — why this keeps happening, not just that it did
- **Should be:** what (a tool, a script, a skill, a hook) — addressing the cause
- **Owner / next action:** *(V2)* the single concrete next step that closes it (a solo practitioner's "owner" is a named next action carried into next week's Section 0)
- **Cost of waiting:** why this matters

## 4. Files to Clean Up

For each: path + action (DELETE / MOVE TO / ARCHIVE / MERGE INTO).
Skip the section if nothing to clean up.

## 5. What's Working

3-5 bullets. Concrete -- name specific files, skills, or workflows that produced clear value this week.

---
*Generated by /weekly-setup-improvements on <TODAY>.*

Phase 5b：MATERIALIZE DRAFTS （V3）

写好报告后，为每个第 2 节的技能构想，按照 references/skill-draft-template.md 中的模板，在 <WORKING_FOLDER>/_drafts/<skill-name>/SKILL.md 放置一个草稿框架。草稿 description 中的触发短语必须来自已发现的重复模式，不得凭空编造。

DRAFTS="$WORKING_FOLDER/_drafts"
mkdir -p "$DRAFTS"
# For each Section 2 idea, write _drafts/<name>/SKILL.md from the template.
# If a draft of the same name already exists, skip it (the user is iterating; don't clobber).

如果上一周已存在同名 <skill-name> 草稿目录，不要覆盖。用户正在迭代该草稿，应保持原样。在第 2 节中注明现有草稿（“草稿已存在，最后修改日期为 ”）。

此步骤的存在意义：V2 的第 2 节止步于“你应该构建 /foo”。一周后，这条建议仍然只是一句话。V3 则以“/foo 的草稿框架位于 _drafts/foo/SKILL.md——打开并继续迭代”收尾。降低启动门槛，正是 V3 的核心理念。

Phase 6：PRESENT

写入后，打印：

1. 完整的输出文件路径。
2. 每个部分各一行摘要（例如：“第 2 节：2 个新技能构想；第 4 节：5 个待清理文件”）。
3. 报告开头的 15–20 行，让用户无需打开 Obsidian 就能采取行动。

质量标准

只有在所有检查项都符合时，报告才算通过。否则，重写不合格的部分。

• 第 1 节的每条内容都引用一个实际文件（现有文件或拟议文件），并给出具体差异或内容块，而不是写“考虑更新”。
• 第 2 节的每项技能都引用足以证明其必要性的具体重复情况（提交次数、文件数量、提示词数量）。
• 第 3 节的每个缺口都指出手动完成了什么，以及应由什么替代。
• 第 4 节的每条内容都包含一个动词（DELETE/MOVE/ARCHIVE/MERGE）和一个路径。
• 第 5 节列出文件或提交，而不是品质。
• (V3) 第 3 节开头先用一句话说明主要根本原因，再列出缺口。
• (V3) 第 2 节的每个想法都指向磁盘上实际存在的 _drafts/<name>/SKILL.md（或注明已存在的文件）。
• 各节不得使用“考虑”“或许”“你可能想要”“建立一个流程”或其他任何含糊措辞。每条建议都必须具体到可在接下来的 30 分钟内执行。

注意事项

• 不要写会话日志。 这是面向未来的改进，不是“你做了什么”的日记。如果某一节读起来像日记，就将其改写为行动项。
• 不要用泛泛的建议凑数。 每条内容都必须引用本周观察到的实际文件、技能或模式。
• 不要建议新增超过 3 项技能。 超过这个数量就是噪声，用户不会创建它们。
• 不要省略“做得好的地方”。 负面偏向不可取；用户既需要知道要改进什么，也需要知道要保留什么。
• 不要修改其他文件。 此技能只会写入一个文件（如果先前文件存在，也会将其重命名）。
• 不要硬编码用户路径。 使用 $WORKING_FOLDER、$HOME、$1。切勿使用 /Users/<name>/...。

更新日志

V3.1 (2026-05-30) — 收紧草稿模板

• references/skill-draft-template.md 中的 Procedure 部分现在要求使用从发现的重复操作中提取的具体动词。<Step> 占位符只是填充内容——只有让第 1 步可以直接执行，才能真正降低启动门槛。Gotchas 和 Testing 中仍允许使用 TODO（这些部分确实需要首次运行数据），但 Procedure 中现已禁止使用 TODO。此项修复了 V3 A/B 测试中遗留的问题：评审者将 Draft-fidelity 评分上限定为 4/5，因为已生成的草稿中含有占位步骤。

V3（2026-05-29）— 自动生成草稿脚手架、清理僵尸项、找出主导根因

通过 skillforge optimize 优化。目标结果：让报告中的更多建议在接下来的一周内真正落地，而不只是再次列出。

• 阶段 5b：物化草稿：根据第 2 节中的每个想法，使用 references/skill-draft-template.md 创建一个 _drafts/<skill-name>/SKILL.md。弥补 V2 留下的启动门槛差距：草稿可以迭代，描述则不行。（来源：Ole Lehmann 的讨论串，以及《Atomic Habits》中关于环境设计的章节。）
• 僵尸项清理规则：在第 0 节中，明确清理连续两个周期都被搁置的行动，并说明理由，绝不重新列出。（来源：TeamRetro 2026 年回顾反模式。）
• 主导根因：在第 3 节开头，根据五问分析结果，先总结一个帕累托主导根因，再列出各项差距。（来源：精益运营中的帕累托原则。）
• 质量修复：将“What NOT to Do”重命名为“Gotchas”，以统一与 skillforge 自身检查清单的术语。新增 references/ 目录（弥补试运行中“缺少渐进式披露”的问题）。
• A/B 验证——在 5 个任务的合成基准上比较 V3 与 V2（3 个调优任务，2 个验证任务），由盲测 LLM 裁判依据 5 个维度的评分标准打分（可执行性 ×2、具体性、因果深度、闭环、技能草稿保真度）。结果：
  • 调优（F1–F3）：V3 得分 84，V2 得分 72，平均 Δ +4.00/30。
  • 验证（F4–F5）：V3 得分 53，V2 得分 47，平均 Δ +3.00/30——没有过拟合。
  • V3 在 5 个测试样例中赢了 4 个，打平 1 个（绿地案例 F4——没有先前报告，因此 V3 所弥补的启动门槛差距尚不存在）。
  • 各维度得分差：草稿保真度 +2.0（V3 的核心主张）、因果深度 +0.6、可执行性 +0.4、闭环 +0.2、具体性 ±0.0。
  • 坦诚说明仍有的问题：裁判指出，如果流程骨架仍是 TODO，生成的草稿可能沦为填充内容，因此 V3 的草稿保真度得分被限制在 4/5。下一版模板应对此作出更严格的要求。

V2（2026-05-27）

通过 skillforge optimize 优化（结果研究：2026 年回顾与持续改进实践）。

• 第 0 节——上周的行动，并检查闭环率（读取上一份报告，依据证据将每项行动标记为已完成／部分完成／已搁置）。以此形成闭环——回顾被忽视的首要原因是行动没有后续跟进。
• 第 3 节中的每项差距都列出负责人／后续行动，并延续到下一周的第 0 节。
• 提出修复方案前先进行根因分析（五问法），确保针对根因而非症状解决差距。
• 目标结果：让报告真正推动每周持续改进，而不是每次都列出一份全新的愿望清单。来源：TeamRetro 2026 年回顾反模式；持续改进实践（五问法／力场分析）。

例行安排／计划

如需每周运行，请调用 /schedule 技能，并要求它针对目标文件夹和 cron 表达式安排此技能。例如：

/schedule weekly-setup-improvements every Sunday at 9am, working folder ~/path-to-folder

schedule 技能负责处理 cron 语法和持久化；此技能本身只负责在运行时生成报告。

测试

这是一项仅包含提示词的技能，没有自动化运行时测试。随附的 tests/eval.sh 会运行结构评估，验证 SKILL.md 中的设计约定是否完整（包含所需阶段、不含禁止的硬编码路径、输出文件名正确等）。

要端到端验证行为：

1. cd 进入一个至少有 7 天近期活动的文件夹。
2. 运行 /weekly-setup-improvements。
3. 检查以下内容：
   • 输出文件位于当前工作目录中。
   • 5 个章节均已填写（或者“What's Working”少于 5 条，并说明真实原因）。
   • 每条内容都提及过去一周实际存在的文件、命令或模式。
   • 没有“考虑……”或“也许……”之类的凑字内容。
   • 如有先前报告，已归档为带日期的文件名，而非被覆盖。
4. 使用显式路径参数重新运行：/weekly-setup-improvements ~/some-other-folder。 确认报告写入该文件夹，而非当前工作目录。