maintainer-loop

Maintainer Loop

Overview

这个 skill 把开源维护工作当成一条复利链路，而不是一次性的回复或审查。每次执行都必须同时交付两类结果：先解决当前任务，再留下让下一次维护更快的结构化资产。

When To Use

在下面这些场景触发这个 skill：

• 接管一个 issue，并完成分类、去重、补信息或首轮回复。
• 接管一个 PR，并把评审重点收敛到意图、风险和对外承诺。
• 准备一次 release，并沿统一 checklist 完成发布前检查。
• 检查 docs 是否和代码、配置、发布状态脱节。
• 把一个刚解决的问题沉淀成 FAQ、案例、规则或仓库画像更新。

如果任务只是单纯写代码、改样式或回答一个不涉及仓库维护的问题，不要使用这个 skill。

Operating Rules

这套 skill 固定遵守八条规则：

1. 每次维护都要留下资产，不能只留下聊天记录。
2. 团队品味要写进系统，不要只停留在人工 review。
3. 优先教会系统，再让系统执行。
4. 先铺安全网，再讨论人肉兜底。
5. 优先依赖机器可读入口，例如测试命令、标签定义、发布说明和贡献规范。
6. 结论、风险和例外都要可检索、可复用。
7. 允许代理先完成 80 分版本，再由人做高层判断。
8. 评估标准是维护摩擦是否下降，不是产出了多少字。

Workflow

始终按 Plan、Work、Review、Compound 四段执行。

1. Plan

• 识别任务类型：issue、pr、release、docs-drift、capture-only。
• 收集最小输入：任务对象、仓库画像、风险等级、完成定义。
• 如果缺少仓库画像，先读取 references/repo-profile.md，补齐最小画像后再继续。
• 给出一份简短执行计划，说明要检查什么、先后顺序是什么、哪些点需要人最后确认。

2. Work

• 按任务类型读取 references/playbooks.md 对应章节。
• 先跑系统检查，再形成判断，不要先写结论再找证据。
• 结论必须区分“已确认事实”“基于假设的判断”“待确认项”。
• 对外草案必须自然、清楚、无 Emoji，语言遵循仓库的主要对外语言。

3. Review

• 把常规检查交给系统，例如测试入口、文档一致性、release checklist、重复问题搜索。
• 把人类 review 留给高层问题：方向、风险接受、breaking change、对外承诺、例外策略。
• 如果当前任务不需要人确认，也要在输出里明确说明“无需额外人工拍板”的依据。

4. Compound

• 绝不跳过这一段。
• 关闭任务前，读取 references/compound-capture.md。
• 把本次新增的判断写回到 FAQ、案例、仓库画像、标签规则、检查矩阵或发布注意事项之一。
• 如果连续出现相近问题，优先升级为系统规则，而不是重复写新回复。

Stable Entry Points

这个 skill 只暴露五个稳定入口语义：

1. 接管一个 issue。
2. 接管一个 PR。
3. 准备一次 release。
4. 检查 docs 是否和代码脱节。
5. 沉淀一次刚解决的问题。

无论从哪个入口进入，都统一使用同一套最小输入和输出。

Required Inputs

• task_object：issue、PR、release 说明、文档范围或已解决问题。
• repo_profile：仓库画像。没有就先补最小版本。
• risk_level：low、medium、high。
• definition_of_done：什么状态算完成。

Fixed Output Contract

默认输出以下字段，顺序可调整，但含义不能变：

任务类型：
结论：
依据：
待确认项：
下一步动作：
建议沉淀：

其中“建议沉淀”不能留空。至少要明确写出“无需沉淀”的理由，或指出要回写到哪个位置。

Repo Profile First

仓库画像是整个 skill 的前置依赖。优先把它视作“维护版 CLAUDE.md”，而不是补充说明文档。

• 仓库画像缺失或过期时，先读取 references/repo-profile.md。
• 仓库画像要短，但必须覆盖维护决策所需的最小字段。
• 如果本次任务暴露出画像过期，例如测试入口变了、支持版本变了、发布流程变了，要在 Compound 阶段顺手更新画像。

Reference Loading Guide

• 任务分流和具体操作：读取 references/playbooks.md。
• 仓库画像不存在、太旧或太空：读取 references/repo-profile.md。
• 需要决定写回什么知识、写到哪里、字段怎么定：读取 references/compound-capture.md。
• 需要做验收、培训新成员或评估 skill 是否真的在复利：读取 references/evaluation.md。

Default Decisions

• 信息不足时不要编造，直接列入“待确认项”。
• 能从仓库、issue、PR、历史文档、测试结果里确认的事实，不要交给人回忆。
• 优先减少后续维护摩擦，而不是优化一次性的回复措辞。
• 如果同类问题已经出现两次以上，优先思考是否应升级成 FAQ、模板、标签规则或自动检查。