personal-arsenal-lifecycle-doctor

# Personal Arsenal Lifecycle Doctor

帮助个人 power user 长期维护自己的技能集合，防止时间腐烂、升级失效、外部依赖僵尸化。

## 触发场景（严格按真实用户语言）

当用户说以下任意一句话时，立即激活本技能：
- “我的技能失效了”“升级后老技能不认了”
- “技能腐烂了”“外部依赖坏了”“我的个人 Arsenal 乱了”
- “帮我检查技能健康”“技能生命周期”“长期维护技能”
- “我 1-2 年前超好用的 Skill 现在 Claude 完全不认了”
- “我的部署类技能现在执行不了了，外部项目下线了”
- “Claude Code 升级后好多技能都不触发了”

特别适合维护 1 年以上个人技能集合（Arsenal 符号链接 + 自定义 + 社区拷贝混合）的重度用户。

## 工作流程（诊断优先 + 用户门控）

### 阶段 1：只读发现（绝不擅自修改）
1. 扫描 `~/.claude/skills` 目录
2. 区分每个技能的**来源**：
   - Arsenal 官方符号链接（`ln -s` 指向本仓库）
   - 纯自定义（用户自己写的）
   - 社区拷贝 / fork（历史快照）
3. 提取 frontmatter 元数据（特别关注新增的 version、last_verified、external_deps、provenance）
4. 扫描技能内容中的硬依赖：
   - GitHub 仓库 URL（尤其是未 pin commit 的）
   - `pip install` / `npm install` 无版本锁定
   - 特定文件路径假设

### 阶段 2：多维度健康诊断
按以下 4 个维度打分 + 证据：

- **时间腐烂风险**（last_verified 距今 >6 个月 / >12 个月）
- **触发描述失效风险**（description 过时、缺少当前 Claude 真实用户痛点语言、与已知机制变化冲突）
- **外部依赖僵尸化风险**（仓库 404、API 变更、包消失）
- **结构健康风险**（缺少健康自检模块、过度复杂、无 graceful degrade、违反 progressive disclosure）

### 阶段 3：输出结构化健康报告
必须包含：
- 总体健康评分（🔴严重 / 🟡警告 / 🟢健康）
- 按风险分级的**问题清单**（每条带具体证据：文件路径 + 行号 + 最后验证时间）
- 每个问题的**最小可执行修复建议**（优先“更新元数据”而非“大改”）
- 一键可运行的命令（用户说“执行”后才真正运行）
- 与 `codex-retrospective` 的协同建议（把本次发现的模式提炼成 AGENTS.md 规则）

完整报告模板见 `references/健康报告模板.md`。

### 阶段 4：安全执行（任何写操作都必须过用户确认）
- 所有修改前必须先 dry-run + 明确展示 diff
- 提供 rollback 方案
- 绝不碰用户 CLAUDE.md / AGENTS.md（除非用户明确说“帮我写进 AGENTS.md”）
- 严重问题优先建议“先备份整个 ~/.claude/skills”

## 推荐的健康自检模块（所有长期 Skill 都应该内置）

**核心原则**（来自长期健康研究）：
- 声明当前版本 + last_verified + tested_on（claude_version + arsenal_commit）
- 列出外部依赖 + 最后验证时间 + 风险分级
- 提供 graceful_degrade 声明
- 在用户询问“健康/升级后/腐烂”时自动触发自检

**完整可复用模板** 见：
- `references/health-module.md`（嵌入式模块 + 与 retrospective 集成方式）
- `references/健康报告模板.md`（输出格式）

**建议**：你写的每一个 Skill 都在 SKILL.md 末尾复制粘贴 health-module.md 里的声明段落。这是防止自己未来腐烂的最低成本保险。

## 与现有工具的协同（个人维护闭环）

**最推荐组合**：
1. 本技能诊断出问题 → 输出证据清单
2. 把证据喂给 `codex-retrospective` → 提炼 1-2 条“长期维护规则”持久化到 AGENTS.md（证据驱动、最小变更）
3. 配合 `codex-fluent` 建立每 3-6 个月的“个人 Arsenal 健康仪式”（report-only + recurring reminder）

其他协同：
- 输出可直接喂给 trigger 相关技能优化 description
- 推荐与 `vibeguard` 结合做任务契约回归检查

## 安全契约（Safety Contract，铁律）

- **只读优先**：默认绝不修改任何文件
- 任何修改必须用户**明确说“执行”或“确认修复”**后才进行
- **永远保护** 用户现有的 CLAUDE.md、AGENTS.md、自定义配置
- 发现严重问题时**优先给出“先备份、再操作”**的建议
- 中文输出，结构清晰，便于个人归档和长期追踪
- 绝不 hardcode 任何路径、端口、个人仓库名

## 健康与版本声明

**当前版本**：v1.0
**最后人工验证**：2026-05-28（Claude Code 20250514 + Arsenal 主分支）
**设计目标**：让“个人维护 1-2 年 Arsenal 还能用”从运气变成可重复的工程实践。

## 局限说明（诚实告知）

本技能**不会**：
- 自动修复需要大量人工语义判断的“行为漂移”（例如某个 Skill 的核心逻辑因为 Claude 推理风格变化而失效）
- 扫描你没有放在 `~/.claude/skills` 里的技能（包括直接写在 CLAUDE.md 里的规则）
- 替代 `codex-retrospective` 的证据驱动规则提炼

它最擅长的是**低成本、高召回地发现“元数据 + 启发式就能检测”的问题**，并给出清晰的下一步行动建议。

## 评估用例

回归检查时使用 `evals/evals.json`，确认只读优先、备份建议、用户确认门控、健康报告格式和长期腐烂风险识别没有退化。

对于复杂语义失效，强烈建议诊断后立刻调用 `codex-retrospective` 做更深层复盘。

---

**正确使用姿势**：
用户说“我的技能好多都不认了，帮我检查一下” → 本技能扫描 + 输出带证据的健康报告 + 最小行动计划 → 用户确认后执行具体修复。

这就是个人 power user 对抗“Arsenal 升级后集体失效”的第一道防线。