user-pm

name

user-pm

description

Tight PM-lens overview of a project — what shipped, what's planned, what we could do next, and what could be cut. Default mode emits a four-section snapshot; a topic flag (`--uat` / `--test` / `--build` / `--decide` / `--overnight` / `--goal` / `--other` / `--cut` / `--history` / `--outstanding`) drills into one topic with context + what-it-unblocks + the work. Use when the user asks for a project overview, status snapshot, "where are we / what's next", or wants to challenge plan assumptions.

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

# <project> — at a glance

**What it is:** <one sentence — the elevator pitch from the plan>

## History (shipped)
- **Phase/milestone X** ✅ <date> — <one-line outcome>
- ...

## Outstanding (on the plan, not done)
- **Item** — <one-line scope + why it's still open>
- ...

## 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)
- **<Move>** — <one-line rationale>
  - **Setup:** <copy-paste commands to start   ,   '  —   >
  


  — 
  
 


  — 
 
 
  


  — 
 Plan: []() § 
 Prereqs: 
 Run: 


  — 
  


  — 
 ...

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:** #<n> + **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

# <project> — <topic>

## Context (what's already shipped that informs this)
- <bullets — only the shipped work that matters to this topic, not the whole history>

## What this unblocks
- <bullets — concrete downstream effects: phases that gate on this, decisions that depend on it, candidates-to-cut that become safe-to-cut once this lands>

## The work
<topic-specific format — see below>

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 <repo> with these reproduction steps, roll back commit <sha>, 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 or 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 <path> [--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 + ). Don't pad with capability moves dressed up as Overnight.

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)

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