pm

Project Manager

GitHub issue lifecycle: brainstorm, create, triage, audit, and review.

Sub-Skills

| Skill | Command | Description | |-------|---------|-------------| | Create | /pm or /pm -quick <desc> | Create structured issues optimized for agent execution | | Brainstorm | /pm:brainstorm | Explore problem space and design approaches before creating issues | | Next | /pm:next | Triage open issues — recommend what to work on next | | Update | /pm:update | Audit open issues — find stale, orphaned, and drift | | Review | /pm:review ISSUE_NUMBER | Deep-validate a single issue against the codebase |

Usage

/pm                       → Create a new issue (interactive flow)
/pm -quick fix the login  → Create issue with smart defaults
/pm brainstorm caching    → Explore approaches before creating issues
/pm:brainstorm            → Same (alternate syntax)
/pm next                  → Triage: recommend next issue to work on
/pm:next                  → Same (alternate syntax)
/pm update                → Audit: find stale/orphaned issues
/pm:update                → Same (alternate syntax)
/pm review 42             → Review: validate issue #42 against codebase
/pm:review 42             → Same (alternate syntax)

Routing

Parse the first argument:

| Argument | Route to | |----------|----------| | brainstorm | /pm:brainstorm sub-skill | | next | /pm:next sub-skill | | update | /pm:update sub-skill | | review | /pm:review sub-skill | | -quick [desc] | Create Issue Workflow (quick mode) below | | anything else / empty | Create Issue Workflow below |

If routed to a sub-skill, invoke it with Skill and pass remaining arguments. If the first argument is -quick, skip the Ambiguity Check and go directly to the Create Issue Workflow (quick mode is an explicit signal that the user wants fast issue creation, not brainstorming). Otherwise, continue with the Ambiguity Check below.

Ambiguity Check

Before starting the Create Issue Workflow, check for existing specs and assess readiness.

Check for existing specs. Use Glob to find specs in .dev/pm/specs/*.md, then Read the most recent candidates to check topic relevance and status. If multiple specs match, prefer the most recent by date prefix in the filename. If a spec exists that matches the user's topic and its status is Approved, use it as primary context for the Create Issue Workflow — the brainstorming was already completed. Skip the ambiguity check and proceed directly. If the matching spec's status is Draft (or missing), do not bypass ambiguity handling — the brainstorm hasn't been approved yet. Continue with the assessment below.

Assess ambiguity. If no matching Approved spec exists, check for these ambiguity signals:

| Signal | Examples | |--------|----------| | Multiple valid approaches | "we need better caching", "rethink the auth flow" | | Unclear scope | "improve the plugin system", "make it faster" | | No obvious issue type | request doesn't map clearly to bug/feature/refactor/chore | | Architecture decision needed | "should we use X or Y", "how should we structure this" | | Exploration language | "I'm thinking about...", "what if we...", "I'm not sure how to..." |

If two or more signals are present, suggest brainstorming before issue creation:

Question: "This sounds like it could benefit from brainstorming before creating issues —
there are multiple approaches and the scope isn't fully defined yet. Want to explore first?"
Options:
  - Yes, brainstorm first (/pm:brainstorm) — explore approaches and produce a spec
  - No, create the issue directly — I know what I want

If the user chooses brainstorming, invoke /pm:brainstorm with the original request as arguments; otherwise (user chose to proceed directly, or fewer than two signals present), continue with the Create Issue Workflow below.

Do NOT block on this check — it is a recommendation, not a gate. Clear requests like "fix the login crash" or "add a health check label" should flow straight through without asking.

Create Issue Workflow

Create structured GitHub issues optimized for LLM agent execution first, human readability second.

Every issue produced by this skill follows the Agent-Optimized Issue Format — structured sections with consistent headers, machine-parseable acceptance criteria, explicit file paths, verification methods, and clear scope boundaries.

Activation

This skill activates when users want to create work items for an agent team. Recognize these signals:

| Signal | Examples | |--------|----------| | Direct | "create an issue", "write a ticket", "plan this work" | | Implicit | "we need to fix...", "let's add...", "can we refactor..." | | Shorthand | "/pm", "project manager", "create task" |

Arguments

| Flag | Description | |------|-------------| | -quick | Quick mode — propose smart defaults instead of blocking on ambiguity |

Usage: /pm -quick add a delete button to user profiles

Parse the first argument for -quick. If present, activate quick mode. Everything after the flag is the task description.

Core Workflow

1. Classify → 2. Discover → 3. Challenge → 4. Explore Codebase → 5. Draft → 6. Review → 7. Create

Step 1: Classify Issue Type

Use AskUserQuestion to determine the issue type:

Question: "What type of work is this?"
Options:
  - Bug: Something is broken or behaving incorrectly
  - Feature: New functionality or enhancement to existing behavior
  - Epic: Large initiative requiring 3+ coordinated tasks
  - Refactor: Improve code structure without changing behavior
  - New Project: Build something from scratch (includes tech stack decisions)
  - Chore/Research: Maintenance, dependency updates, spikes, investigations

If the user's initial message already makes the type obvious (e.g., "there's a crash when..."), skip this step and classify automatically. State your classification and proceed.

Step 2: Type-Specific Discovery

Run the question flow for the classified type. See [references/WORKFLOWS.md](references/WORKFLOWS.md).

Key principles:

• Use AskUserQuestion for structured choices (max 4 questions per call, 2-4 options each)
• Use follow-up conversation for open-ended details
• Batch related questions together to minimize round-trips
• If user says "you decide" or similar, make a reasonable choice and note it as [AGENT-DECIDED: rationale]
• Mark gaps as [NEEDS CLARIFICATION: question] — don't guess on ambiguous requirements
• Never accept vague requirements. Before moving to the next step, critically examine every

requirement for specificity. If a user says "add a button", ask: Where? What states? What action? If a user says "fix the bug", ask: What exact behavior? What's expected vs actual? What triggers it? Treat every underspecified detail as a blocker.

Step 3: Requirements Challenge

After discovery, systematically check for underspecified requirements. See the Requirements Challenge Checklist in [references/WORKFLOWS.md](references/WORKFLOWS.md) for the full dimension list.

Default mode (critical):

1. Analyze gathered requirements against the challenge checklist dimensions
2. Identify every gap — placement, states, behavior, edge cases, error handling, accessibility
3. Use AskUserQuestion to probe each gap (batch related questions, max 4 per call)
4. Do NOT proceed to codebase exploration until all critical ambiguities are resolved
5. An agent executing the resulting issue should never need to guess intent

Quick mode (-quick):

1. Analyze gathered requirements against the same checklist dimensions
2. For each gap, propose a smart default with rationale
3. Present all assumptions in a single summary: "Here's what I'll assume: [list]. Confirm or correct?"
4. Proceed after one confirmation round — only block on truly ambiguous requirements where no

reasonable default exists