User Pm

user-pm

Write a scannable project overview. Be terse. Bullets only, one line each, no narration.

Use one of two modes:

• Default (no flag). Four-section snapshot — see the "Default output format" section below.
• Topic-focused (one of --uat / --test / --build / --decide / --overnight / --goal / --other / --cut / --history / --outstanding). Three-part deep dive on that topic only — see the "Topic-focused mode" section below. --uat is an alias for --test.

If multiple topic flags are passed, use the first and note the others were ignored in one line. If an unknown flag is passed, fall back to default mode and note the unrecognized flag in one line.

Steps

1. Read the plan. Try in order: documentation/plan.md, plan.md, README.md. Skim the status table or equivalent.
2. Read recent git activity. git log --oneline -30. Note the most recent shipped milestone.
3. Check archived/done markers. Phases marked ✅, ARCHIVED, or COMPLETE in the plan, plus any in **/archive/.
4. Output the sections for the chosen mode. No preamble, no closing summary.

Default output format

#  — at a glance

**What it is:** 

## History (shipped)
- **Phase/milestone X** ✅  — 
- ...

## Outstanding (on the plan, not done)
- **Item** — 
- ...

## Possible next moves

Group each move under one of the five category headers below. Order moves by overall leverage; within a category, order by leverage too. Skip a category header entirely if it has no moves — don't print empty headers. Aim for 3–6 moves total across all categories.

### Test (operator runs a check)
- **** — 
  - **Setup:** 
  - **What to verify:** 

### Build (run a command to build)
- **** — 
  - **Run:** 
  - 

### Decide (need plan-level input from user)
- **** — 
  - 
  - 
  - **Once decided:** 

### Overnight (autonomous /build-phase candidate)
- **** — 
  - Plan: [``]() § 
  - Prereqs: 
  - Run: `/build-phase --plan  [--phase N] [--steps a,b,c]`

### Other (no code, no command — board hygiene, real-use, deferred decisions)
- **** — 
  - **Steps:** 

## Candidates to cut
- **** — 
- ...

How to pick the category for each move

• Test — there's existing code in master that needs a human to confirm it works. Operator-led smoke gates, iPad UAT, "verify X is wired", spot-checking real data. The deliverable is a run-doc or a PASS verdict, not a diff.
• Build — there's identified work to do, but it's not yet on a runnable plan. Includes "write the plan first then run /build-phase" cases — those go under Build, not Overnight, until the plan exists.
• Decide — the move is blocked on a plan-level choice only the user can make (hardware purchase, scope cut, threshold change, whether to deprecate X). Surface the open questions and the next action after the decision lands.
• Overnight — moves that meet ALL the rigor criteria below. If a move would qualify after a plan is written, it goes under Build now and migrates to Overnight on the next user-pm pass.
• Other — everything else. Board hygiene (close shipped-but-open issues), passive-use accumulation, "wait for X to happen", "deprecate this manually". These often shouldn't appear in the snapshot at all — only include them if the user has a real action to take.

If a single move plausibly fits two categories, pick the one that describes the user's next concrete action. Example: "ship Phase J" — the code is in master, the next action is operator UAT → that's Test, not Build.

Overnight category — qualification rubric

Check the Overnight rubric: a move qualifies only if /build-phase could run it unattended through morning without a human in the loop. Apply ALL of:

• Plan format ready. Steps already use ### Step N + **Problem:** + **Type:** + **Issue:** # + **Flags:** headers (or are trivially extendable). Table-only or bullet-only plans don't qualify until extended — surface them under Build instead.
• Issues synced. No blank **Issue:** # lines — they kill the build-phase audit trail. If missing, the prereq line in the candidate should say /repo-sync first.
• No manual gates inside the run. Operator UAT, soak observation, "operator runs M2", Type: operator, Type: wait, conditional steps — any of these halts overnight progress. Steps gated on a 4–8h soak don't fit either; surface those under Test as next-day work.
• Reviewer flags match step shape. --reviewers full requires --start-cmd + --url. Backend-only / unit-test-only steps must be code. Mismatch = build-phase aborts.
• Frontend touches need --ui. Any step changing frontend/, /api/... shapes, or WebSocket payloads must have --ui in **Flags:**. Code-only review on UI work is the known gap.
• Worktree-safe. Multiple steps editing the same shared file (routes module, central config) overwrite each other on merge. If two candidate steps both rewrite the same file end-to-end, surface ONE per night, not both in parallel.
• No external dependencies a human has to set up overnight (game client, paid API quota refresh, hardware reboot).

Prefer substrate moves (foundational layer, not a single capability) over capability moves at equal effort — substrate compounds across future work.

Skip the Overnight header entirely if nothing in the plan currently meets the bar. Do not say "Nothing autonomous-ready" as a placeholder — just skip the section.

The "Candidates to cut" section is the point

Most overviews just regurgitate the plan. This skill earns its keep by challenging unexamined gates and scope. For each candidate, name the assumption out loud:

• Time/data gates ("≥1 month of telemetry before X") — is that number load-bearing or vibes? Could you start with what you have?
• Sub-goals already met elsewhere — a phase scoped to do A+B may have had B shipped under a different phase. Split it.
• UAT gates that got de-facto validated — if later phases exercised the same code paths and passed, the gate may be ceremony.
• Archived plan docs still referenced — once a path is dead, the archive entry shouldn't be in the doc map.
• "Polish" / "hardening" phases without a concrete failure mode — if you can't name what breaks today, the phase is preemptive.
• Eval scaffolds nobody runs — fixtures rot. If they haven't been touched in N commits, they're not load-bearing.

Default to 3–6 candidates. Each one should be specific enough that the user can say "yes cut it" or "no, here's why it stays" without asking a follow-up.

Topic-focused mode

When invoked with one of --uat / --test / --build / --decide / --overnight / --goal / --other / --cut / --history / --outstanding, replace the four-section snapshot with a deep dive on that one topic. The qualification rules and assumption-challenging stance from the default mode still apply.

Shared three-part shape

#  — 

## Context (what's already shipped that informs this)
- 

## What this unblocks
- 

## The work

Be honest in What this unblocks. If completing this topic doesn't unblock anything load-bearing, say so in one line — that's a signal the topic is itself a cut candidate, and the user should see it.

Per-topic specifics for "The work"

• --uat (alias) / --test — every operator-led validation worth running now, ordered by leverage. Per move:
• Setup: copy-paste commands in the user's shell (PowerShell on Windows).
• What to verify: pass/fail criteria in table form when there's more than 2 rows.
• If it fails: the one next action (file an issue at ` with these reproduction steps, roll back commit `, etc.).

• --build — code work that's identified but not yet on a runnable plan. Per move:
• Why now: one-line rationale tied to What this unblocks.
• Run: either a /plan-feature invocation (with the seed text to paste in) if no plan exists yet, or the slash command sequence if it does.
• Risks: anything from [code-quality.md](../../rules/code-quality.md) or [worktree-hygiene.md](../../rules/worktree-hygiene.md) that this move could trip.

• --decide — plan-level choices blocking forward motion. Per move:
• Open questions: the actual fork(s) in the road, phrased so the user can answer "A" or "B" without restating context.
• Once decided: the next concrete action — usually a doc edit + /repo-sync, or which /plan-* skill to invoke.
• Cost of waiting: what slips or stays ambiguous while the decision is open (often this is what What this unblocks points at).

• --overnight — moves that pass the Overnight qualification rubric (see earlier section). Per move:
• Plan: [path](path) § section.
• Prereqs: explicit list — /plan-review pending, /repo-sync to fill blank **Issue:** #, --ui flag needs adding, etc.
• Run: /build-phase --plan [--phase N] [--steps a,b,c].
• If nothing currently qualifies, say so in one line and point to the closest-to-ready candidate plus what it'd take to qualify (usually /plan-review + /repo-sync). Don't pad with capability moves dressed up as Overnight.

• --goal — work items a fresh window can drive to a binary, checkable stop condition under /goal, each rendered as a single ready-to-paste line. Distinct from --overnight: --goal needs no plan format, no synced issues, no /build-phase rail — just a condition a fast model can verify each turn. The harness's /goal Stop hook keeps the session grinding across turns and auto-compactions until the condition resolves. Reach for it when "done" is nameable but a full build-phase plan is overkill: get a suite green, close issue #N, lift an eval score past a threshold, finish a bounded bug fix. For this mode, Context = the shipped substrate that makes these goals runnable now; What this unblocks = what each met goal clears downstream. Per candidate under The work:
• Stop condition: one binary, externally-checkable criterion — pytest exits 0, PR #N merged, `` exists, count == N. Hold it to user-draft's GOAL bar (its Step 3b): reject anything unmeasurable ("bot is better", "code is clean") and rewrite until a fast model could check it every turn. Fold in guardrails inline when the work needs them ("…without touching the public API").
• Open: if one point of the condition can't be pinned down in a single pass (which suite counts as "green", what threshold, which of two files), name it declaratively in one line — no question mark, no waiting. Omit this sub-bullet entirely when the condition is unambiguous. user-pm surfaces the gap as data, the way ### Decide does, and never blocks on it; resolving it is the one job handed to /user-draft.
• Ready to paste: exactly one line per candidate. With no Open point, emit the fresh-window pair in a fenced block — /task-handoff --resume then /goal "" (the resume line self-orients the new window; droppable for same-window use). With an Open point, emit instead /user-draft , where the seed carries the candidate + draft condition + the open point — so the new window starts by clarifying and user-draft's GOAL branch ends by emitting the finished /goal line. This is why user-pm inlines user-draft's standard rather than invoking it per candidate: it stays one-pass, and the interactive clarify happens in the window the user chooses to open.
• Skip any item blocked on operator action, hardware, or an external dependency a fresh window can't satisfy — those aren't goal-drivable; route them to --test or --decide instead.
• Close The work with a mandatory QUICK COPY (one per window) block — the single paste-line for each candidate (/goal "" for ready ones, /user-draft for ones with an Open point), one per line — so each new window either starts the goal or starts the clarify-then-goal pass.
• If nothing currently has a checkable stop condition, say so in one line and name the closest candidate plus the criterion it'd need. Don't dress a fuzzy task up as a goal.

• --other — board hygiene, deferred passive-use accumulation, real-world wait states. Per move:
• Steps: the manual flow or copy-paste commands.
• Be ruthless: if the move has no real user action (just "wait"), drop it. Same bar as default mode's Other category.

• --cut — the assumption-challenging core of the skill. Per candidate:
• The candidate: plan section/phase/gate by name.
• The unexamined assumption: name it out loud (load-bearing number? sub-goal already met? ceremony gate? preemptive hardening?).
• What survives the cut: what's left of the surrounding scope if this is dropped.
• What you'd be wrong about if you cut it: the strongest reason to keep it. If you can't articulate one, say so — that's a strong cut signal.
• What this unblocks in this mode is "focus / time / which next move becomes top-of-stack", not a downstream phase.

• --history — fuller breakdown of shipped milestones than the default's one-line bullets. Per milestone:
• Date + ✅ + name.
• Outcome: what changed in the product, not what the commits did.
• Notable surprises: anything that came in as a bonus or got descoped during execution.
• Cap at the last ~10 milestones; older items collapse to a one-line "earlier: ...".
• What this unblocks in this mode is "remind the user what foundation they're standing on" — keep it short.

• --outstanding — fuller breakdown of open plan items than the default's one-line bullets. Per item:
• Item name + status marker (planned / blocked / in-progress).
• Scope: one or two lines.
• What's blocking it now: if anything (decision, prereq, drift, just hasn't been picked up).
• Closest path forward: which mode/flag would move it next (--uat, --build, --decide).
• Skip items that are trivially done-but-unmarked — surface those under board hygiene in default mode instead.

Tone

• No emojis unless the plan uses them. ✅ for shipped status is fine since most plans use it.
• File/line references use [path](path) markdown links.
• Don't recommend skill invocations gratuitously. Exceptions: the Build and Overnight sub-categories under "Possible next moves" explicitly propose slash commands or /build-phase invocations — that's their whole job; --goal mode emits /goal, /task-handoff --resume, and /user-draft lines as its deliverable. Test and Other use shell commands when commands apply.
• Don't ask clarifying questions. If the plan is missing or ambiguous, say so in one line and proceed with what you have.

Constraints

• Read-only — never edit plan docs, issues, or code while producing the snapshot.
• Don't invent moves not derivable from the plan + git log + archive markers.
• One-pass — no follow-up iterations after emitting the snapshot.

Limitations

• Plan must exist at documentation/plan.md, plan.md, or README.md; otherwise the snapshot will be sparse.
• Stale plan docs produce stale snapshots — this skill does not re-read git log to second-guess plan-marked status.
• Overnight qualification is a heuristic, not a guarantee — the rubric catches common misroutes but cannot detect every silent precondition.

---

dev-observatory hook (additive; see [.claude/rules/descriptor-contract.md](../../rules/descriptor-contract.md))

--json output mode (additive). When invoked with --json, emit the snapshot as ONE structured JSON object instead of prose, so a tool (e.g. dev-observatory's on-demand goal-vs-reality review) can render it: each default section (history, outstanding, possible_next, cut_candidates) and any topic-mode payload becomes a top-level key; prose bullets become arrays of objects. The prose modes are unchanged when --json is absent.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aberson
• Source: aberson/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.