修复计划（Fix Plan）

fix_plan.md（Ralph 约定）与 checklist.md（非 Ralph 工作区）的 Schema 与生命周期管理。厂商无关 —— 从 Ralph 集成中抽离，可在各类环境中复用。

主题（Topics）

主题依赖关系（Topic Dependencies）

fix-plan (schema + lifecycle)
  ├─→ (default, no args) → archive-receiver dispatch (caller-supplied) — falls back to move
  ├─→ format (entry — section structure + markers)
  ├─→ priority (new convention — BLOCKED P0-P3 + reason)
  │     └─→ depends on sync (Step 0: refresh external state before classifying)
  ├─→ add (authoring act-now items)
  ├─→ draft (deferred plan stub → `## Plan Drafts`)
  │     └─→ code-workflow/steps dispatch on promote (research → plan)
  ├─→ move (completion → Completed)
  │     └─→ optional --rag=: dispatch for semantic indexing (caller-supplied)
  ├─→ sync (GitHub state polling) — depends on github-flow gh CLI conventions
  └─→ issue-drafts (lifecycle of draft files)

• 所有主题均可独立调用，除 priority 外，其必须在第 0 步强制调用 sync（HARD STOP） —— 该依赖旨在防止基于过期状态进行分类这一失败模式（详见 priority.md 中 Triage 工作流第 0 步）
• 默认调用（无参数） 将 Completed 分区分发至调用方提供的 archive-receiver（--archive=:）；若未注册接收器，则回退至 tracker 内部的 move（仅执行 Completed 清理）。参见下方“默认调用”章节
• move 主题在调用方提供 --rag=: 时，可选择性地分发至 RAG 接收器 —— 通用 skill 保持厂商无关；接收器实现由调用方负责（例如 ralph wrapper）
• sync 主题遵循 github-flow skill 所定义的 gh CLI 规范
• draft 主题在提升（promote）时分发至 code-workflow（steps），将延迟存根转化为实际的 research → plan 流程

配置（Configuration）

默认调用（无参数）

当以无参数方式调用 /fix-plan 时，将 ## Completed 分区分发至已配置的归档接收器（archive receiver），将其采集并写入外部报告，同时从源 tracker 中移除已采集条目。若未注册接收器，则回退至 move 主题（仅在 tracker 内部清理 Completed 区）。

接收器契约（Receiver contract）

fix-plan skill 保持厂商无关 —— 不硬编码接收器名称。调用方（用户环境中的 Claude）负责路由至已注册的任意接收器。

调用方自动分发启发式规则（Caller auto-dispatch heuristic）

调用方在运行时决定：

1. 检查 CLI 参数 --archive=: → 若存在，直接使用
2. 否则扫描已注册的 skills，查找声明了 Completed 归档契约的接收器（匹配 topic 名称，或在 description 中声明 fix-plan-archive 关键字）
3. 恰好一个匹配 → 自动分发
4. 多个匹配 → 提示用户选择
5. 零匹配 → 回退至 move 主题

示例接收器（示意性 —— 非内置）

以下为可能注册归档接收器的典型环境：

以上仅为示例，非依赖项。fix-plan skill 不导入其中任一接收器；接收器由调用方提供。

速查参考（Quick Reference）

默认调用

/fix-plan                            # 分发至已配置的 archive-receiver（或回退至 move）
/fix-plan --archive=:  # 显式指定接收器

参见上方“默认调用（无参数）”章节。

Schema（format）

# Fix Plan

## Progress

- [ ] {Action}
  - **Why**: {motivation}
  - **How to apply**: {procedure}
- [BLOCKED:P0:external] {Action} (awaiting X)
- [x] {Completed item — pending move}

## Completed

- 2026-06-07 12:00 — {one-line summary} (commit {sha}, PR #{N})

完整 Schema 详见 format.md。

BLOCKED 优先级 + 原因（priority — 新约定）

- [BLOCKED:P0:external] PR #45 user merge decision
- [BLOCKED:P1:selfable] consolidate Step 2.4 PR create (branch + body ready)
- [BLOCKED:P2:external] CodeRabbit re-review awaiting

• P0–P3：与 GitHub 优先级标签对齐（P0 最高）
• external：真实外部依赖
• selfable：当前即可推进（P 等级表示需立即行动）
• 分类第 0 步 — 先同步外部状态（HARD STOP）：/fix-plan priority 在分类前强制调用 sync 主题 —— 对每个引用的 PR/Issue 执行 gh pr view 和 gh issue view 。自动将已合并/关闭的条目解析为 [x]，避免陈旧条目被误判为活跃 BLOCKER

完整约定详见 priority.md。

新增条目

- [ ] {one-sentence Action}
  - **Why**: {motivation 1-2 sentences}
  - **How to apply**: {procedure / tools / commands}

长度预算与交付物分离详见 add.md。

记录延迟计划存根

## Plan Drafts

- [BLOCKED:P2:selfable] {Purpose — one line}
  - **Defer reason**: {why postponed}
  - **Resume trigger**: {what promotes it}
  - **Expected deliverable**: research | plan | checklist

通过 /fix-plan draft 调用。仅为存根（不含完整计划）→ 当触发条件满足时，提升至 code-workflow 的 research→plan 流程。

Plan Drafts 条目始终为 [BLOCKED:P*:selfable]，绝不可为 [ ] —— 否则自主循环（如 Ralph wrapper）可能误操作该条目，而提升（promote）必须经人工决策。原因恒为 :selfable（正文文件就绪，仅待用户信号，而非第三方响应）。优先级 P0–P3 表示其相对于其他存根的提升紧迫度。详见 draft.md 与 priority.md。

移入 Completed

勾选 [x] 后，将其摘要为单行并移入 Completed 分区。详见 move.md。

定期归档 Completed（维持 tracker 精简）

在周期边界，将较早的 ## Completed 条目移入本地分区文件，防止 tracker 膨胀：

/.bak/-completed-YYYY-MM.md     # monthly（默认）
/.bak/-completed-YYYY-Www.md    # weekly（--completed-archive-period=weekly）

与接收器无关（无需外部接收器）。早于当前周期的条目移出；当前周期条目保留在主 tracker 中。详见 move.md “Completed-section size management”。

同步 GitHub 状态

gh pr view  --json state,mergedAt   # PR
gh issue view  --json state,closedAt # Issue

MERGED PR 或 CLOSED Issue → 自动标记为 [x]；PR CLOSED-without-merge → 标记为 [BLOCKED:P2:external]。详见 sync.md。

Issue Drafts 生命周期

issue-drafts/.md → gh issue create → 归档至 .bak/ → 从 fix_plan 中删除。详见 issue-drafts.md。

参阅（See Also）

• github-flow（依赖项）—— sync 与 register 所依赖的 gh CLI 规范
• Ralph 集成是独立维护的工作流，不包含于本公开 skill 中。Ralph wrapper（若存在）负责 Ralph 特定逻辑：持久化条目分区 ## REPEAT、自主循环中 [BLOCKED] 的跳过语义，以及调用方侧的 --rag=: 分发（本 skill 仅暴露抽象标志契约）。Ralph wrapper 的详细信息请参阅 Ralph 项目文档