pinkroosterai/pm-plan

Plan Work from Description

Transform a natural language description into well-structured tracking entities (issues and/or feature requests). The goal is to produce entities that are detailed enough for /pm-scaffold to generate realistic work packages from — so invest in understanding the problem space before creating anything.

Step 1: Resolve Project

• Current directory: !pwd
• Call mcp__pinkrooster__get_project_status with projectPath set to the directory above
• Extract the projectId
• If no project found, offer to register it first

Step 2: Understand What Already Exists

Before asking questions or creating anything, build context from two sources:

2a: Codebase Analysis (proportional to complexity)

Calibrate the depth of exploration to the request:

Simple bug reports (clear error message, known location, reproduction steps): Quick lookup — a single Grep/Glob to confirm the affected file exists. Spend under a minute here. The goal is just to populate affectedComponent accurately, not to diagnose the root cause.

Moderate requests (CRUD addition, extend existing feature): Targeted exploration — find the existing pattern to follow, note the relevant files and conventions. A few Grep/Glob calls.

Complex features (new system, integration, cross-cutting concern): Deep exploration — understand the relevant architectural layers, existing infrastructure that can be reused, and how the feature fits into the current design. Use Grep/Glob and Read to trace through related code.

In all cases:

1. Use Grep/Glob to find files related to $ARGUMENTS
2. Identify what already exists — existing implementations inform classification and description quality
3. Note patterns, conventions, and layers involved

2b: Existing Tracked Items

Load current items to avoid duplicates and understand project context:

1. Call mcp__pinkrooster__get_issue_overview with projectId and stateFilter: "Active" + "Inactive"
2. Call mcp__pinkrooster__get_feature_requests with projectId and stateFilter: "Active" + "Inactive"
3. Compile a deduplication list of names, descriptions, and states

If a closely matching item already exists, surface it to the user before creating anything new.

Step 3: Research the Domain

For non-trivial work — especially new features, integrations, or unfamiliar domains — use online research to inform the planning. This produces better descriptions, more accurate scoping, and catches edge cases early.

When to research:

• The description mentions a technology, library, or integration you should verify (e.g., "add OAuth support", "export to Parquet", "integrate with Stripe")
• The work involves patterns or best practices worth confirming (e.g., "add rate limiting", "implement RBAC")
• The user's description is vague about implementation and external context could help clarify options

When to skip:

• Pure bug reports with clear reproduction steps
• Simple CRUD additions following existing patterns
• Work that's entirely internal to the existing codebase

How to research:

• Use WebSearch with targeted queries about the technology/pattern
• Use WebFetch to pull relevant documentation pages
• Synthesize findings into actionable context that improves the entity descriptions

Fold research findings into the entity description — mention relevant libraries, standards, common pitfalls, or architectural considerations discovered.

Step 4: Decompose into Work Items

Analyze $ARGUMENTS and determine whether this is a single item or multiple distinct items.

Signals that work should be decomposed:

• Conjunctions connecting distinct capabilities: "add X and Y", "we need A, B, and C"
• Different affected areas: "fix the login page and add export to the dashboard"
• Mixed types: description contains both bugs and features
• Large scope with natural boundaries: "add a notification system" might decompose into "notification infrastructure", "email notifications", "in-app notifications"

Signals to keep as one item:

• Tightly coupled changes that don't make sense independently
• Single capability described from multiple angles
• Small scope even if touching multiple files

If decomposing, present the breakdown to the user for confirmation before creating anything. Use the AskUserQuestion tool:

• Question: "I see {N} distinct items in this description. Here's how I'd break them down:\n\n{numbered list with type and name for each}\n\nDoes this look right?"
• Header: "Work breakdown"
• Options: [{label: "Create all", description: "Create all {N} items as described"}, {label: "Adjust", description: "Let me modify the breakdown first"}, {label: "Keep as one", description: "Create a single item instead"}]

If the user selects "Adjust", ask what they'd like to change and iterate.

Step 5: Classify Each Item

For each item (whether single or decomposed), determine the type:

Issue indicators (create an Issue):

• Bug, defect, broken, error, crash, regression, failing, wrong, incorrect
• Performance: slow, timeout, latency, memory leak, high CPU
• Security: vulnerability, CVE, injection, XSS, auth bypass
• Technical debt: refactor, cleanup, deprecated, legacy

Feature Request indicators (create a Feature Request):

• Feature, add, new, enhance, improve, support, enable, implement
• User stories: "as a...", "I want...", "we need..."
• Capabilities: dashboard, page, export, import, notification, integration

If ambiguous, use the AskUserQuestion tool:

• Question: "Is '{itemName}' a bug/issue to fix, or a new feature/enhancement?"
• Header: "Work type"
• Options: [{label: "Bug/Issue", description: "Something broken, slow, or insecure"}, {label: "Feature/Enhancement", description: "A new capability or improvement"}]

Map to specific types

Issue types:

• Bug/broken/error/crash → IssueType: Bug
• Regression/was-working → IssueType: Regression
• Slow/timeout/performance → IssueType: PerformanceIssue
• Security/vulnerability → IssueType: SecurityVulnerability
• Refactor/cleanup/debt → IssueType: TechnicalDebt

Feature categories:

• New capability → FeatureCategory: Feature
• Extends existing → FeatureCategory: Enhancement
• Makes existing better → FeatureCategory: Improvement

Map severity (issues only)

• Crash, data loss, security breach → Critical
• Broken functionality, major regression → Major
• Cosmetic, minor inconvenience → Minor
• Typo, trivial cosmetic → Trivial

Map priority (all entities)

• Urgent, ASAP, critical, blocker → Critical
• Important, should, high → High
• Would be nice, eventually → Low
• Default → Medium

Step 6: Clarify Gaps

After classification but before creation, check if anything important is missing or ambiguous. Ask concisely — combine related questions into a single AskUserQuestion call rather than asking one at a time.

Worth clarifying:

• Scope ambiguity: "improve the dashboard" → which aspect? Performance? UI? New features?
• Boundary ambiguity: "add export" → which entities? What formats? Where in the UI?
• Audience ambiguity: "make it easier to use" → for whom?
• Priority conflicts: description mixes urgency levels

Not worth asking about:

• Implementation details that /pm-scaffold will figure out from the codebase
• Fields that can be reasonably inferred from context
• Things the user clearly specified already

If the description is clear and specific, skip this step entirely.

Step 7: Confirm Before Creating

Present the full plan using the AskUserQuestion tool:

For a single item:

• Question: "Create {type} '{name}' with {priority} priority?"
• Header: "Confirm"
• Options: [{label: "Create", description: "Proceed"}, {label: "Adjust", description: "Change something first"}, {label: "Cancel", description: "Don't create"}]

For multiple items:

• Question: "Create the following {N} items?\n\n{numbered list with type, name, and priority for each}"
• Header: "Confirm ({N} items)"
• Options: [{label: "Create all", description: "Create all {N} items"}, {label: "Select", description: "Let me pick which ones to create"}, {label: "Cancel", description: "Don't create anything"}]

Step 8: Create Entities

For Issues

Call mcp__pinkrooster__create_or_update_issue with:

• projectId
• name: concise, descriptive title
• description: comprehensive description incorporating codebase context and research findings. Include: what's wrong, where it manifests, impact, and any relevant technical context discovered during analysis
• issueType: mapped type
• severity: mapped severity
• priority: mapped priority
• affectedComponent: if identifiable from codebase analysis
• stepsToReproduce: if the description includes or implies reproduction steps

For Feature Requests

Call mcp__pinkrooster__create_or_update_feature_request with:

• projectId
• name: descriptive title following pattern {Feature}: {qualifier}
• description: comprehensive specification incorporating research findings. Include: what the feature does, why it matters, how it fits with existing functionality, and any technical considerations discovered
• category: mapped category
• priority: mapped priority
• businessValue: derived from the "why" — who benefits and what becomes possible
• userStories: array of structured stories extracted from the description [{"role": "...", "goal": "...", "benefit": "..."}]. Derive 2-4 stories covering distinct user roles or capabilities. Make them concrete and specific.
• requester: "Claude Code" (or user name if known)

Duplicate and Overlap Handling

Before each create call, check against the deduplication list from Step 2.

Exact duplicate (same bug, same feature, same scope): Do not create a new entity. Surface the existing item to the user and suggest next steps (scaffold, refine, or update it).

Partial overlap (existing item covers part of the scope, or the new request expands on it): Prefer updating the existing entity over creating a new one. Call the update endpoint with projectId + the existing entity's ID + expanded fields. This avoids fragmentation — one well-maintained item is better than two overlapping ones.

Use the AskUserQuestion tool to confirm:

• Question: "Found {existingId} '{existingName}' ({state}) which overlaps with this request. How should I handle it?"
• Header: "Overlap found"
• Options: [{label: "Update existing", description: "Expand {existingId} with the new details (recommended)"}, {label: "Create new", description: "Create a separate item — the scope is different enough"}, {label: "Skip", description: "The existing item already covers this"}]

No match: Proceed silently.

Step 9: Report Results

## Created {count} Item(s)

| # | Type | ID | Name | Priority |
|---|------|----|------|----------|
| 1 | {Issue/FR} | {entityId} | {name} | {priority} |
| ... |

### Research Applied
- {key finding 1 from online research, if any}
- {key finding 2, if any}

### Next Steps
- **Refine** (FRs): `/pm-refine-fr {frId}` — add user stories and detail
- **Scaffold**: `/pm-scaffold {entityId}` — create implementation work package
- **Triage**: `/pm-triage` — review priorities across all items
- **Status**: `/pm-status` — project overview

Step 10: Offer Next Steps

Use the AskUserQuestion tool:

• Question: "What would you like to do next?"
• Header: "Next step"

Build options based on what was created:

• If single item: offer Scaffold, Refine (FR only), or Done
• If multiple items: offer "Scaffold first item", "Triage all", or Done

If Scaffold: Delegate to /pm-scaffold {entityId} If Refine: Delegate to /pm-refine-fr {frId} If Triage: Delegate to /pm-triage If Done: Close with a summary of entity IDs for future reference

Constraints

• Always confirm classification before creating entities — the user should see what's about to be created
• Derive as much structured data as possible from natural language — don't leave fields empty when they can be inferred
• Report all entity IDs prominently so the user can reference them
• When decomposing, each item should be independently meaningful — don't create items that only make sense together
• Fold research findings into entity descriptions rather than keeping them separate
• Never create entities without first checking for duplicates
• Prefer updating existing items over creating new ones when there is overlap — fragmented tracking is worse than a comprehensive single item
• Proportional effort is critical: a bug report with clear reproduction steps should take under 30 seconds of analysis (quick file lookup, create issue, done). Reserve deep codebase exploration and online research for complex features and integrations. The user should not wait 3 minutes for a simple bug to be logged.
• If the project has many open items, suggest /pm-triage after creation to help prioritize