help

帮助

读取当前仓库状态，并推荐下一步要运行的流水线步骤。此技能本身不会执行任何操作，只会指出接下来应使用哪个技能，并引用它观察到的状态，以便用户推翻该建议。

对于重返仓库的用户、首次接触 Skill Kit 的用户，或卡在流水线中途、不确定下一步该调用哪个技能的用户，这是他们的入口。

调用位置

这是一个旁路技能。它会根据诊断结果，在相应技能处重新接入主流水线。

以下情况请使用 /help：

• 用户在已使用 Skill Kit 的仓库中开始一个会话，想了解自己在流水线中的进度
• 用户离开某项功能一段时间后，需要重新了解工作进展
• 新团队成员想了解流水线的指引，而不是阅读完整的 references/SYSTEM-OVERVIEW.md
• 用户明确询问“接下来该做什么？”或“我现在到哪一步了？”

以下情况请勿使用 /help：

• 要实际运行所推荐的技能时——/help 只提供建议；用户需要自行运行下一项技能
• 用户已知道下一步，只是想执行时
• 问题涉及概念而非具体状态时，用 /help 代替阅读 references/SYSTEM-OVERVIEW.md
• 与功能流水线无关的任务（没有上游产物的缺陷修复、一次性清理）

流程

1. 收集仓库状态

分两个阶段构建状态快照：先依次检测基础分支（以便后续调用引用该分支），然后并行执行只读快照命令。

阶段 1a — 检测基础分支（首先依次运行）：

# Prefer the remote's HEAD, fall back through common names
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's@^origin/@@')
if [ -z "$BASE_BRANCH" ]; then
  for candidate in main master prod develop trunk; do
    if git rev-parse --verify "$candidate" >/dev/null 2>&1; then BASE_BRANCH=$candidate; break; fi
  done
fi
# A name is not a ref. $BASE_BRANCH names the branch (for `--base`, `git switch`);
# $BASE_REF points at it, and is the only thing safe as a range endpoint.
if git rev-parse --verify "origin/$BASE_BRANCH" >/dev/null 2>&1; then
  BASE_REF="origin/$BASE_BRANCH"
else
  BASE_REF="$BASE_BRANCH"
  echo "note: origin/$BASE_BRANCH does not resolve — measuring against the local branch, which may be stale" >&2
fi
echo "base=$BASE_BRANCH ref=$BASE_REF"

不要硬编码 main 或 master——并非所有仓库都使用它们（Skill Kit 自己的仓库使用 prod，许多其他仓库使用 develop、trunk 或团队自定义名称）。如果未设置 origin/HEAD，且不存在任何回退候选分支，请在继续之前询问用户基础分支名称。

余留风险： $BASE_REF 的新鲜度取决于上次 git fetch；在三角分叉（或远程名称不是 origin）的情况下，origin/$BASE_BRANCH 可能不存在，也可能跟踪的是你的分叉而非上游——此时 else 分支会回退到本地分支，而这正是本防护措施要避免的陈旧引用行为。该情况会输出到 stderr，而不会静默回退，因为没有任何提示的貌似合理的错误答案，正是这个缺陷存在了五个月的原因。如果计数看起来不对，请运行 git fetch 后重试，或手动设置 BASE_REF。

阶段 1b — 收集快照（并行运行，各调用彼此独立）：

# Current branch and commits ahead of the detected base branch
git branch --show-current
git log --oneline "$BASE_REF..HEAD"

# Open PR for the current branch, if any
gh pr list --head "$(git branch --show-current)" --state open --json number,title,url,reviewDecision

# Open issues with PRD or slice labels, or in open milestones
gh issue list --state open --json number,title,labels,milestone --limit 50

# The frontier — which open issues are actually takeable right now.
# `state` is the GraphQL enum here: uppercase OPEN, not REST's lowercase.
# `totalCount` counts blockers in every state, which is what distinguishes
# "blockers all closed" from "never wired" (see the note below).
gh issue list --state open --limit 100 --json number,blockedBy,assignees \
  --jq '.[]
       | {number,
          open_blockers: [.blockedBy.nodes[] | select(.state == "OPEN") | .number],
          ever_wired: .blockedBy.totalCount,
          assignee: (.assignees[0].login // null)}' 2>/dev/null

# Open milestones with remaining feature issues
gh api "repos/{owner}/{repo}/milestones?state=open" --jq '.[] | {title, open_issues, closed_issues}' 2>/dev/null

frontier 调用与此批次中的其他调用互相独立，不会因猜错引用而失败，因此应放在并行批次中。将节点筛选为 state == "OPEN" 后，如果某个切片的所有阻塞项都已关闭，就会报告空的 open_blockers，且无需进行额外记录，因此无需重新读取阻塞项即可相信此值是最新的。

切片问题早于原生依赖关系接入的仓库（参见 /prd-to-issues §7）会为所有内容报告空的 open_blockers。ever_wired 可以在不猜测的情况下区分这种情况与确实没有依赖关系的图：如果任何问题报告 ever_wired > 0，就表示该仓库已接入依赖关系，空列表属实。如果每个问题的 ever_wired: 0，且正文中包含 Blocked by #N 这类文本行，则从未写入任何依赖关系——请回退到这些文本，并在建议中说明这一点，而不要断言整个待办列表都可以开始处理。

旁路存储库也在同一并行批次中。 项目的旁路存储库是此目录树之外的私有 git 仓库，保存其研究档案（research/），并根据 solutions.write 的设置保存解决方案条目（solutions/）。请通过此技能自带的解析器 references/sidecar.sh，使用其安装后的绝对路径来解析；切勿自行计算旁路存储库路径。以下代码块为下方第 6、7、10 和 11 行提供数据：

SC="<this skill's directory>/references/sidecar.sh"
# Read-only git against the sidecar, with the project's git environment cleared.
sgit() { env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE git -C "$SIDECAR" "$@"; }
SC_ERR="$(mktemp)"
SIDE=""
if SIDECAR="$(bash "$SC" resolve 2>"$SC_ERR")"; then
  echo "Sidecar: $SIDECAR (last commit $(sgit log -1 --format=%cs))"
  RESEARCH="$(bash "$SC" path research 2>/dev/null)"
  SIDE="$(bash "$SC" path solutions 2>/dev/null)"
  echo "research entries:"; [ -n "$RESEARCH" ] && ls -t "$RESEARCH"
  echo "excavation dossier:"; [ -n "$RESEARCH" ] && ls "$RESEARCH"/excavation-*.md 2>/dev/null
else
  grep -q '^SIDECAR MISS' "$SC_ERR" && echo "SIDECAR MISS"
fi
cat "$SC_ERR" >&2; rm -f "$SC_ERR"

# Solutions entries in every directory `sidecar.sh solutions-dirs` prints (its
# header owns that policy); the sidecar's solutions/ is counted apart. Row 10
# reads the counts, row 11 the dates.
ITP="" IN_TREE_N=0 SIDE_N=0 NEWEST=0
while IFS= read -r DIR; do
  [ -n "$DIR" ] && [ "$DIR" != "$SIDE" ] || continue
  ITP="${ITP:+$ITP,}$DIR"
  [ -d "$DIR" ] || continue
  IN_TREE_N=$((IN_TREE_N + $(find "$DIR" -type f ! -name '.*' | wc -l)))
  T=$(git log -1 --format=%ct "$BASE_REF" -- "$DIR")
  [ "${T:-0}" -gt "${NEWEST:-0}" ] && NEWEST=$T
done <<< "$(bash "$SC" solutions-dirs 2>/dev/null)"
if [ -n "$SIDE" ]; then
  SIDE_N=$(find "$SIDE" -type f -name '*.md' | wc -l | tr -d ' ')
  T=$(sgit log -1 --format=%ct -- solutions)
  [ "${T:-0}" -gt "${NEWEST:-0}" ] && NEWEST=$T
fi
echo "solutions entries: in-tree (${ITP:-none})=$IN_TREE_N sidecar=$SIDE_N"
PREV_LANDING=""
[ -n "$BASE_REF" ] && PREV_LANDING=$(git log --first-parent --skip=1 -1 --format=%ct "$BASE_REF")
if [ -z "$BASE_REF" ]; then
  echo "last merge compounded: unknown (BASE_REF is not set in this call; set it from Phase 1a)"
elif [ -n "$PREV_LANDING" ] && [ "${NEWEST:-0}" -lt "$PREV_LANDING" ]; then
  echo "last merge compounded: no"
else
  echo "last merge compounded: yes"
fi

# Legacy-repo signal for /excavate: root commit date (unknown on a shallow clone)
git rev-parse --is-shallow-repository
git log --max-parents=0 --format=%cs HEAD </dev/null | sort | head -1

同时查看解析器的标准错误输出和区块的标准输出。需要关注三种结果：

• Sidecar: <path> (last commit <date>) — 在“当前情况”中同时报告两者。最后提交日期比项目自身的活动落后数月，就是停滞的 sidecar 的表现。
• SIDECAR MISS — 此项目未注册 sidecar。解析器的未命中行包含确切的 init 命令；请原样引用，并让第 6 行决定建议。若以状态码 1 退出，却没有 SIDECAR MISS 行（不是 git 仓库，或已找到 sidecar，但无法提交新别名），则不算未命中：请按原样转述解析器输出的那一行。
• ALIAS COLLISION: … — 两个 sidecar 声称拥有此工作区的一个键。这是警告，不是失败：解析器使用了它首先列出的 sidecar，区块也继续运行。无论最终给出什么建议，都要在“当前情况”中按原样打印这一行，列出两个 sidecar；一个项目被拆分到两个 sidecar，就会有两套研究档案和两套解决方案存储，而单独看任何一套都显得不完整。

当本次调用中的 $BASE_REF 为空时，“Last merge compounded”会打印 unknown（每个并行调用都会启动一个新 shell，因此必须将 Phase 1a 中的变量写入区块）；值为 unknown 时，第 11 行不会触发。否则，它会将任一位置中的最新条目与 base 分支上倒数第二次落地的提交进行比较（使用 --first-parent，因此 squash commit 和 merge commit 都各计一次）。最后一次合并的条目会在该合并落地前写入，无论是在 PR 上，还是直接写入 sidecar，因此从最近一次落地开始计量，会把每次 sidecar-compounded 合并都误判为未合并。仓库内的这一侧依据 base 分支上的提交日期，而不是文件修改时间；后者会在全新克隆时重置。

并行使用工具的注意事项。 在 Claude Code 中，如果并行批次中的一次 bash 调用出错，执行框架会取消仍在运行的其他调用——一个错误的 ref 就会拖垮整个快照。因此 Phase 1a 必须先单独运行：如果 base 分支检测失败，Phase 1b 中就不会有任何内容尝试引用 $BASE_BRANCH。不要在并行批次中对猜测的分支名串联 &&/||，试图“省一次往返”——凡是仓库与猜测不符，都会产生明显错误。

如果 gh 尚未通过身份验证，或仓库不是 GitHub 仓库，请注明无法收集哪些信号，并根据其余信息进行判断。缺少某个信号不代表失败，只会缩小建议范围。

2. 判断状态

按优先级依次检查。第一个匹配项就是建议。匹配后立即停止，不要给用户三个选项。

#	信号	建议	一句话理由
1	当前分支上有已打开的 PR	reviewDecision 为 CHANGES_REQUESTED：/respond-to-review。否则：合并 PR，然后运行 /compound	有修改请求：“队友要求你修改 PR #<n> — /respond-to-review 会在你决定要修复什么或提出异议之前，先根据代码检查每条评论。”否则：“你在 <branch> 上有一个已打开的 PR — 如果审查已完成，就合并它并记录经验。”
2	当前分支有领先于基准分支的提交，且没有已打开的 PR	/pre-merge	“你有 <N> 个提交领先于 <base>，但还没有 PR — /pre-merge 会创建 PR 并进行架构审查。”
3	有引用 PRD 的已打开切片议题，且没有已关闭的切片议题	对 open_blockers 为空的优先级最高的切片运行 /execute	“PRD #<prd> 下有 <N> 个已打开的切片议题 — /execute 是处理第一个无阻塞项的下一步。”
4	有引用 PRD 的已打开切片议题，且有些切片议题已关闭	对 open_blockers 为空的下一个切片运行 /execute	“PRD #<prd> 下有 <N> 个已打开和 <M> 个已关闭的切片 — /execute 会接手下一个无阻塞的切片。”
5	有已打开的 PRD 议题，但没有切片议题	对 PRD #<prd> 运行 /prd-to-issues	“PRD #<prd> 已完成构思，但尚未拆分 — /prd-to-issues 会将其拆分为多个切片。”
6	Phase 1b sidecar 部分显示 SIDECAR MISS	/init-pipeline（其 § 8 会创建 sidecar）	“此项目尚未注册 sidecar，因此没有地方存放其 solutions 条目 — /init-pipeline § 8 会创建一个。”
7	sidecar 的 research/ 中有近期条目（排除 excavation-*.md，它是 /excavate 的档案，不是功能），且没有已打开的 PRD 议题与其功能匹配	/write-a-prd	“有一份关于 <feature> 的近期研究文件已归档，但没有 PRD 议题 — /write-a-prd 会将其整理成一份构思完善的提案。”
8	有规划阶段的里程碑，且有一个 research-ready 功能议题	对该 research-ready 功能运行 /research	“里程碑 <name> 有一个 research-ready 功能 — 对它运行 /research。”
9	有规划阶段的里程碑，且只有 roadmap bet 功能	将一个功能提升为 research-ready，然后运行 /research	“里程碑 <name> 只有 roadmap bet 功能 — 选一个，将其提升，然后运行 /research。”
10	树内或 sidecar 的 solutions/ 中都没有 solutions 条目（solutions entries: 行上的两个计数均为 0），根提交距今超过约 6 个月，不是浅克隆，且 sidecar 的 research/ 中没有 excavation-*.md	/excavate	“此仓库有历史记录，但没有书面决策或研究档案 — /excavate 会在第一个功能开始前，从 git 中还原热点和附有引用的决策。”
11	有已交付的工作，但自上次合并后，两个 solutions 位置都没有新增条目（last merge compounded: no）	/compound	“上次合并交付的工作尚未整理沉淀 — 运行 /compound。”
12	有未解决的 QA 错误，且没有正在进行的功能工作	对优先级最高的 QA 错误运行 /execute	“你有 <N> 个未解决的 QA 错误议题 — 运行 /execute 逐个处理。”
13	以上情况均不符合 — 当前没有待处理工作，也没有正在进行的功能	/shape（或询问用户想做什么）	“目前没有正在进行的功能工作 — 通常从 /shape 开始。”

信号 #3 和 #4 中的“无阻塞”指 Phase 1b frontier 调用返回的 open_blockers 为空 — 应读取该值，不要根据议题正文中的 Blocked by 描述推断。这与 /prd-to-issues §9 和 Ralph 循环提示词采用相同规则，因此这三个选择位置的结果必然一致，而非碰巧一致。

3. 给出建议

给出一条建议，并说明一句理由和触发该建议的状态信号。使用以下格式：

## Where you are

<one paragraph: the state signals you observed, stated as facts>

## Next step

**`/<recommended-skill>`** — <one-line reason>

## Why this skill

<one short paragraph: what the skill produces and how it connects to the observed state>

## If this is wrong

<2-3 alternative next steps for common cases where the heuristic might have missed>

输出示例（针对信号 #7：sidecar 中有一条近期研究记录，但没有匹配的 PRD 问题）：

## Where you are

Current branch: main. No open PRs. Sidecar: `~/.claude/sidecars/owner-repo` (last commit 2026-04-05). Its `research/` has `nextjs-middleware-migration-2026-04-05.md`, dated 2026-04-05 and pointing at a Next.js 16 middleware migration. No open PRD issue matches it (I searched open issues for "middleware" and "Next.js" and found nothing). No open slice issues. No active milestone.

## Next step

**`/write-a-prd`** — a recent research file is present but there is no PRD issue for the work it covers.

## Why this skill

`/write-a-prd` takes a completed research document and turns it into a shaped PRD filed as a GitHub issue. It consults the archived research automatically, so the recommendations in the research will flow into the pitch without you re-summarizing them. Expect 10–15 minutes of interview, then a PRD issue ready for `/prd-to-issues`.

## If this is wrong

- If the archived research is stale and no longer matches what you intend to build, run `/correct-course` first to clean up before shaping again.
- If you want to rewrite the research for a different approach, run `/research` again (it will produce a new archive entry with today's date).

4. 停止

给出建议后就停止。不要自动启动建议的技能，也不要询问用户是否希望你运行它——由用户决定。如果用户想运行该技能，他们会自行调用。

如果用户回复“你说错了，我实际在做 X”，不要重新收集完整状态。直接回答用户纠正后的问题——你的建议是基于信号，而不是权威判断。

启发式规则

• 只给一条建议，不要给三条。 用户想知道下一步该做什么，而不是要一份选项清单。选择最合适的一项，并明确给出。
• 引用状态。 每条建议都必须指出触发建议的具体信号——文件路径、问题编号或分支名。含糊的建议很快会失去用户的信任。
• 优先选择最早且不受阻碍的步骤。 如果用户有一个未关闭的切片问题，以及一个无关但已合并且从未进行复盘的 PR，只有在切片工作暂停时，才建议先复盘。如果拿不准，就建议能推动最近工作继续前进的步骤。
• 绝不捏造信号。 如果无法读取未关闭的问题，因为 gh 未通过身份验证，请如实说明。不要猜测。
• 绝不自动运行建议的技能。 /help 只提供建议。下一项技能由用户运行。

此技能不是什么

• 不是任务跟踪器。 GitHub 问题和 PR 才是任务跟踪器。此技能读取这些状态，不会取代它们。
• 不是流程概览的替代品。 如果用户在询问流程的概念性问题，请从与此技能一同打包的 references/SYSTEM-OVERVIEW.md 和 references/using-this-pack.md 中提取相关内容，而不是自行发挥。若要深入阅读，请指引用户查看仓库中的原文：https://github.com/chrislacey89/skills/blob/main/SYSTEM-OVERVIEW.md 和 https://github.com/chrislacey89/skills/blob/main/docs/using-this-pack.md。
• 不是向导。 它不会引导用户完成需求梳理、研究或规划，而是告诉用户该启动哪项技能，然后就此退出。

交接

• 预期输入： 类似“我下一步该做什么？”的问题，或对流程进展位置感到不确定
• 生成内容： 一条引用状态信号的下一步建议，并附上一句理由
• 交接至： 建议所指向的任一流程技能——/shape、/research、/write-a-prd、/prd-to-issues、/execute、/pre-merge 或 /compound
• 接下来： 用户自行运行建议的技能——/help 不会调用任何技能