--- name: pm-help description: Use when the user asks for help with the pm-* skills, what a pm skill does, which pm skill to use, how the project-management workflow fits together, or what is missing or out of date in the project's PM setup. Explains the skills, checks the install and PM state for gaps, and recommends the next skill to run. Read-only. --- # pm-help Explain the `pm-*` skills and recommend which one to run now, based on what is installed and what the PM state shows. Read-only: this skill never writes files and never runs the skill it recommends without asking. Follow the Non-interruption rules, Shared definitions, Asking the user, and Communication contract in the pm-skills section of the agent instructions file (`AGENTS.md` or `CLAUDE.md`), if that section exists. PM root is its `PM state directory` setting (default `planning/`). ## Modes | Mode | When | Effect | | --- | --- | --- | | `overview` | Default: "help", "what can the pm skills do", "what should I do" | Diagnose the setup, list the skills, recommend one | | `explain ` | "What does pm-shape do?", "how do I park an idea?", "what is a brief?" | Explain one skill or concept | ## Guard - If a workflow is active, only `explain` mode may run, and only from the skill guide below, without reading PM state. Answer in at most 5 lines, then resume the step in progress. For `overview`, apply Non-interruption rule 4. - If the pm-skills section is missing from the agent instructions, still run: diagnosis check 1 reports it. ## Skill guide Use this to explain skills. Keep each explanation to its row plus, when asked, the skill's own `SKILL.md` steps. | Skill | Use it when | Say for example | Writes | | --- | --- | --- | --- | | `pm-setup` | Installing or upgrading the skills and the rules in `AGENTS.md` or `CLAUDE.md` | "set up the pm skills" | The managed section only | | `pm-init` | Starting project management in a repository, once | "initialise planning" | The PM root, `VISION.md`, a seeded roadmap | | `pm-resume` | Starting a session, or after the context was compacted | "where was I?" | Nothing, except deleting `PAUSE.md` once its pause resumes | | `pm-rejoin` | You lost the pm thread, a workflow is running that `NOW.md` does not record, or a session started mid-task | "where am I in the pm lifecycle?", "rejoin", "get back on track" | `NOW.md`, `ROADMAP.md` | | `pm-next` | Nothing is active and you want to start the next item on its own feature branch | "start R-007", "claim R-007" | `NOW.md`, `ROADMAP.md` | | `pm-park` | You or the agent have an idea, bug, question, or inspiration to remember, even mid-task | "park this: ...", "note that ..." | One inbox file | | `pm-bug` | A bug to log with the facts a fix needs: symptom, expected and actual, reproduction, severity, evidence | "add a bug", "log a defect" | One inbox file with `Kind: bug`; a roadmap item if routed | | `pm-risk` | A risk to note, even mid-task, or the risk register to see or manage: add, update, re-rate (RAG), review, mitigate, close, or remove one risk | "risk: the API may rate-limit us", "show the risks", "close RK-003" | `RISKS.md`; a roadmap item in `mitigate` | | `pm-shape` | You want to brainstorm, discuss, or challenge one idea before committing to it | "let's think through dark mode" | A brief; a roadmap item if accepted | | `pm-discover` | You want evidence from the code, history, or usage data, or an answer about how the product works today | "what should we fix next?", "is export used?" | A research report; inbox ideas | | `pm-strategy` | Setting focus, milestones, bets, or the vision, or rebuilding the roadmap | "re-plan the roadmap" | `STRATEGY.md`, `VISION.md`, `ROADMAP.md` | | `pm-purview` | A .NET project wants to know which Purview tools would help, or a new project is choosing its stack | "would Purview help here?" | A research report; roadmap items if accepted | | `pm-checkpoint` | Stopping, pausing, switching items, suspending or resuming an operation, or finishing one (a finished item ends its context) | "pause", "stack this, I need to fix the build", "pop the stacked work", "R-007 is done" | `NOW.md`, `LOG.md`, `ROADMAP.md`, `STACK.md` | | `pm-pause` | Stopping mid-task and continuing later from the exact step, with or without an active item (a shaping interview, a review, a question waiting for you) | "pause here", "save where we are, I'll pick this up tomorrow" | `PAUSE.md`; the active item's checkpoint in `NOW.md` | | `pm-revise` | Work that is already built is not what you wanted, or a `Done when` check fails, including mid-workflow | "that's not right", "change what we built for R-007" | `NOW.md`, `ROADMAP.md`, the brief's `## Revisions` | | `pm-review` | Weekly, or when `pm-resume` says a review is due | "weekly review" | Inbox, `ROADMAP.md`, `LOG.md`, `config.md` | | `pm-item` | Changing one roadmap item: add, edit, drop, block, move or insert at a position, reassign, or mark a task of yours done | "drop R-012", "put R-012 before R-008", "I've done R-009" | `ROADMAP.md`, `LOG.md` | | `pm-board` | Seeing the task board, or moving, adding, inserting, or closing one card | "show the board", "move R-012 to Next" | Nothing in view mode; `ROADMAP.md`, `LOG.md` in edit modes | | `pm-roadmap` | Seeing the full roadmap by milestone, or moving, adding, or inserting one item | "show the roadmap", "put R-012 at the top of Next" | Nothing in view mode; `ROADMAP.md` in edit modes | | `pm-status` | Seeing the one-screen summary or your own queue | "where are we?", "what do I need to do?" | Nothing | | `pm-up-next` | Seeing the ordered queue and the one next action without starting anything | "what's next?", "up next" | Nothing | | `pm-export` | A tool needs the whole plan as JSON, or you want the export refreshed or validated | "export the plan", "update the status JSON" | `/planning.json` and `planning.schema.json` | | `pm-docs-site` | You want the plan as a local web site (Board, Roadmap, Log, Risks), a module or page added to it, or to know whether it is current | "add a docs site", "is the docs site current?" | `ROADMAP.md` (plan); the site folder, inside the item's workflow (build modes) | | `pm-help` | Not sure which skill to use | "pm help" | Nothing | Concepts to explain on request, from the pm-skills section: the PM root, item IDs and fields, owners (agent, user, both), claimable items, the inbox file, briefs, the Challenge protocol, Persistence, the Non-interruption rules, PM commits and the `Commits` section in `/config.md`, the rules version and the upgrade check, drift and `pm-rejoin`, the Handoffs table in `/config.md`, the board columns, the Roadmap order and edits rules, roadmap positions (`top`, `bottom`, `before`, `after`), the up-next queue, the reference legend that questions print, the escape options (`Explain `, `Show the roadmap`, `Show the board`), bugs and severity, the risk register, risk IDs, and how RAG is derived and overridden, revisions and `Revisits`, the export file and its schema, the docs site and why its build modes run inside a workflow (rule 9), completion records and the finish order (the completion commit rides the item's branch and its pull request), feature branches (each item on its own branch, staying put when asked, during an interruption, or while a pull request is pending, and pulling before every move), the operation stack and `pm-checkpoint` push/pop, the pause file (`pm-pause` writes it, `pm-resume` continues and deletes it), `merged-unclosed` items, named references (why an ID always carries its title), the Context budget (one item per context, a fresh session between items), and the two ways a workflow may be interrupted (`pm-revise` to correct, `pm-checkpoint` push/pop to suspend). ## Steps (overview) 1. **Diagnose.** Run these checks in order. Each failure is one finding with the skill that fixes it. Read-only git commands only. | # | Check | Finding if it fails | Fix | | --- | --- | --- | --- | | 1 | `AGENTS.md` or `CLAUDE.md` contains `