PRP Plan

PRP Plan

Produce a plan a human can scan and an implementation agent can execute without rediscovering the design. Identify the invariant, find the existing primitives, and choose the smallest solution supported by evidence.

Plan only. Do not implement, commit, or open a PR. A spike is allowed only to settle an architectural hinge; its code remains throwaway under the prp-spike contract.

Input: $ARGUMENTS (if absent, use the conversation).

Mode

• A request to link two existing plans routes to workflows/update-references.md and stops.
• publish <existing .plan.md> publishes or refreshes that plan on its recorded source issue, updates Plan Publication, verifies the shared comment, and stops. Do not redesign the plan unless the user asks to revise it.
• A bug report, stack trace, regression, error, or unexplained current behavior adds root-cause analysis before solution design.
• Everything else creates an implementation plan.

1. Resolve the request

Accept a PRD path, issue reference or URL, another document, free-form text, or conversation context.

For a PRD:

1. Read it and select the first pending phase whose dependencies are complete.
2. Preserve its problem, user, hypothesis, scope, and success signal.
3. Note other independently actionable phases, but plan only the selected phase.
4. Tell the user which phase was selected.

For an issue from GitHub, Jira, Linear, or another tracker:

1. Retrieve the issue through whatever access is already configured in the environment. The skill does not prescribe or configure a tracker client.
2. Treat the body as the starting point, not the complete brief. Read the relevant comment history—including earlier published PRP plans and corrections after them—and follow linked issues, parent/child or blocking relationships, duplicates, PRs, specifications, and attachments that can change scope, intent, constraints, or current decisions.
3. Reconcile that context: distinguish current decisions from superseded discussion, note unresolved disagreements, and stop following links once additional material no longer affects the plan. Curate; do not dump the tracker graph.
4. Preserve the source issue in the plan while separating its required outcome from any suggested implementation.
5. If the issue, comments, or decision-relevant links cannot be retrieved, state what context is missing and ask the user to provide it or configure access. Never infer missing tracker content.

For every input, establish:

• the problem and user outcome;
• the affected user, operator, or system;
• the observable invariant that must hold;
• the success signal that would show the outcome improved after delivery;
• constraints that are genuinely fixed;
• assumptions inherited from the request;
• whether a proposed implementation is required or merely suggested.

Do not invent personas, business value, or vanity metrics. If the affected user, problem, desired outcome, or meaningful success signal is materially uncertain, stop and recommend clarifying the product intent before architecture turns assumptions into code. Ask the user only when ambiguity changes the product contract or would produce materially different plans.

2. Gather codebase evidence

Read repository guidance and discover the actual project structure. Do not assume src/, a framework, or a validation stack.

Read the project's optional sidecars when they exist: direction.md for product direction and scope, and engineering.md for the standard work is checked against, the engineering-manager sidecar. They live anywhere in the repository: follow the path repository guidance names, or find them by name with git ls-files. Absence is normal; never create them. Product direction bounds what this plan may propose, and a proposal that contradicts it needs the user's decision before it becomes tasks.

For a non-trivial code change, read references/agent-prompts.md, then launch these agents in parallel when capacity permits, or sequentially when it does not. Every listed role remains required:

• prp-core:codebase-explorer to locate relevant files, analogous behavior, tests, configuration, and existing primitives.
• prp-core:codebase-analyst to trace the current control flow, data flow, state changes, contracts, and observable behavior.
• For broken current behavior, prp-core:root-cause-analyzer to reproduce the symptom, falsify competing explanations, and prove the causal chain and smallest fix boundary.

For a small documentation, configuration, or narrowly localized change, use only the agent or direct inspection needed to remove uncertainty. The planner owns synthesis and must inspect the decisive files itself.

Collect only relevant evidence:

• precise file:line references;
• existing primitives and extension points;
• the closest useful precedent, including meaningful variations;
• authoritative project validation commands;
• conventions the change should preserve;
• awkward seams or missing primitives the requested feature would otherwise work around.

Do not preserve a known poor local convention merely because it exists. Fit the architecture while applying repository and global quality guidance.

3. Establish the cause for broken behavior

For a bug, error, regression, stack trace, or unexplained behavior, do not plan from the report's assumed cause. Give the root-cause agent the original symptom and tracker context without a preferred fix, then consume its evidence alongside the explorer and analyst results.

Require a reproducible observation when reasonably possible, a causal chain, rejected alternatives, the smallest responsible fix boundary, and a regression check. If the diagnosis is conditional or unresolved, surface the missing evidence and recommendation at the design gate. Do not disguise an unproven cause as an implementation task.

The planner does not create issues, edit issue bodies, or publish diagnosis through /prp-debug. Its only tracker write is publishing and verifying its completed plan under step 8.

For requests that do not assert broken current behavior, skip this step.

4. Reason from invariants and primitives

Read references/planning-craft.md and challenge the first plausible design before committing to it.

Apply its foundation and laziness tests to the candidate design. Establish the data shape and owner, the existing or missing primitive, where each decision belongs, what coordination the design avoids, and what can be deleted. Justify any shared state, scaffold, new abstraction, or cross-layer signal by the invariant it protects rather than by hypothetical future need.

Answer:

1. What observable outcome is actually required?
2. Which existing primitive comes closest to satisfying it?
3. Can configuration, composition, prompting, or a small extension solve it?
4. What assumption forces new state, lifecycle, abstraction, or subsystem?
5. Can that assumption be tested cheaply?
6. What machinery disappears if the simpler mechanism works?
7. Which data shape and owner make the required behavior simplest?
8. If state is shared, what happens when another actor changes it concurrently?
9. If this requirement had existed from day one, would this still be the design?

Prefer the smallest valuable vertical slice: it must deliver or directly unlock the user outcome, not merely create an elegant technical primitive. Reuse proven primitives, keep ownership clear, and avoid speculative flexibility. Simplicity is not fewer plan details; it is fewer moving parts in the proposed system.

5. Research or spike only when it can change the plan

External research is conditional. Use prp-core:web-researcher when current documentation, dependency versions, platform behavior, security guidance, or an unfamiliar tool affects the design. Ask a narrow question tied to the architectural decision and prefer primary sources.

Delegate /prp-spike to a separate agent before finalizing when an uncertain, falsifiable claim materially changes the architecture, especially when:

• a new subsystem exists only because external behavior is uncertain;
• a recent or unfamiliar tool may already expose the needed primitive;
• a configuration switch, prompt, or composition technique might remove substantial code;
• competing approaches have dramatically different complexity;
• a small behavioral experiment can prove the real integration-point behavior.

The planner chooses the question. Use the exact agent-delegation prompt under references/planning-craft.md → Decide when to spike, wait for that agent, then consume its verdict and evidence. Never build the spike in the planner context or copy spike code into the plan as production code.