help（帮助指南）

Help

Read the current repo state and recommend the next pipeline step. This skill does not do any work itself — it orients the user by pointing to the right next skill, citing the state it observed so the recommendation can be overruled.

This is the front door for users who are returning to a repo after a break, onboarding to Skill Kit for the first time, or stuck mid-pipeline and unsure which skill to invoke next.

Invocation Position

This is a side-route skill. It reconnects to the main pipeline at whichever skill the diagnosis points to.

Use /help when:

• The user is starting a session in a repo that already uses Skill Kit and wants to know where they are in the pipeline
• The user has been away from a feature for a while and needs a refresher on what state the work is in
• A new team member is learning the pipeline and wants guidance rather than reading all of references/SYSTEM-OVERVIEW.md
• The user explicitly asks "what should I do next?" or "where am I?"

Do not use /help:

• To actually run the recommended skill — /help only recommends; the user runs the next skill themselves
• When the user already knows the next step and just wants to execute
• As a substitute for reading references/SYSTEM-OVERVIEW.md when the question is conceptual rather than state-specific
• For tasks unrelated to the feature pipeline (bug fixes with no upstream artifacts, one-off cleanups)

Process

1. Gather repo state

Build a state snapshot in two phases: first detect the base branch sequentially (so downstream calls can reference it), then dispatch the read-only snapshot commands in parallel.

Phase 1a — detect the base branch (run first, sequentially):

# 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 trunk; do
    if git rev-parse --verify "$candidate" >/dev/null 2>&1; then BASE_BRANCH=$candidate; break; fi
  done
fi
echo "base=$BASE_BRANCH"

Do not hardcode main or master — not every repo uses them (Skill Kit's own repo uses prod, and many others use develop, trunk, or a team-specific name). If origin/HEAD is not set and none of the fallback candidates exist, ask the user for the base branch name before continuing.

Phase 1b — gather the snapshot (run in parallel, each call independent):

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

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

# Research archive entries for this repo (durable, per-user, outside the repo)
REPO_SLUG=$(git config --get remote.origin.url | sed -E 's|.*[:/]([^/]+)/([^/.]+)(\.git)?$|\1-\2|')
ls -t "$HOME/.claude/research/$REPO_SLUG/" 2>/dev/null

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

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

Parallel tool-use gotcha. In Claude Code, when one bash call in a parallel batch errors, the harness cancels its in-flight siblings — one bad ref takes down the whole snapshot. This is why Phase 1a must run first (and alone): if base-branch detection fails, nothing in Phase 1b will try to reference $BASE_BRANCH. Do not chain &&/|| against a guessed branch name inside a parallel batch to "save a round trip" — it will fail noisily on any repo that does not match your guess.

If gh is not authenticated or the repo is not a GitHub repo, note which signals you could not gather and work from the rest. A missing signal is not a failure — it just narrows the recommendation.

2. Classify the state

Walk through these checks in priority order. The first one that matches is the recommendation. Stop at the first match — do not try to give the user three options.

3. Present the recommendation

Present one recommendation, with the one-line reason and the state signals that triggered it. Use this format:

## 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>

Example output (for signal #6, a recent research archive entry with no matching PRD issue):

## Where you are

Current branch: main. No open PRs. Research archive has `~/.claude/research/owner-repo/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. Stop

After presenting the recommendation, stop. Do not start the recommended skill automatically, and do not ask the user if they want you to run it — the user decides. If the user wants to run it, they will invoke it themselves.

If the user responds with "that's wrong, I'm actually doing X," do not re-run the full state gather. Just answer the corrected question directly — your recommendation was based on signals, not authority.

Heuristic Rules

• One recommendation, not three. The user is asking for a next step, not a menu. Pick the best match and commit to it.
• Cite the state. Every recommendation must reference the specific signal that triggered it — a file path, an issue number, a branch name. Vague recommendations lose trust fast.
• Prefer the earliest unblocked step. If the user has both an open slice issue and an unrelated merged PR that was never compounded, recommend compounding first only if the slice work is paused. When in doubt, recommend what unblocks forward motion on the most recent work.
• Never fabricate signals. If you could not read open issues because gh is unauthenticated, say so. Do not guess.
• Never auto-run the recommendation. /help is advisory. The user runs the next skill.

What This Skill is NOT

• Not a task tracker. GitHub issues and PRs are the task tracker. This skill reads that state, it does not replace it.
• Not a replacement for the pipeline overview. If the user is asking conceptual questions about how the pipeline works, pull the relevant sections from references/SYSTEM-OVERVIEW.md and references/using-this-pack.md (bundled alongside this skill) rather than improvising. For deeper reading, point the user at the repo originals: https://github.com/chrislacey89/skills/blob/main/SYSTEM-OVERVIEW.md and https://github.com/chrislacey89/skills/blob/main/docs/using-this-pack.md.
• Not a wizard. It does not walk the user through shaping, research, or planning. It tells them which skill to start and gets out of the way.

Handoff

• Expected input: a question like "what should I do next?" or ambient uncertainty about pipeline position
• Produces: a single next-step recommendation with cited state signals and a one-line reason
• Feeds into: whichever pipeline skill the recommendation points at — /shape, /research, /write-a-prd, /prd-to-issues, /execute, /pre-merge, or /compound
• What comes next: the user runs the recommended skill themselves — /help does not invoke anything