prd-planner

Overview of prd-planner skill

What prd-planner does

prd-planner is a Requirements Planning skill for generating a product requirements document through a persistent, file-based workflow instead of a single long prompt. Its main value is not just “write a PRD,” but keeping research, assumptions, task progress, final requirements, and technical follow-up separated into stable files so the agent does not lose context mid-process.

Who should use prd-planner

The best fit for prd-planner is a team or solo builder who wants more than a one-shot PRD draft. It is especially useful when you need traceability across discovery, edge cases, PRD writing, and technical design. If you expect to refine requirements over several passes, this skill is more reliable than an ordinary prompt.

Job to be done

Users usually adopt prd-planner because they need a structured PRD creation flow that can survive iteration: clarify requirements, capture notes, produce a usable PRD, and often hand off into technical design. The repository explicitly positions it as a fix for context switching, lost thoughts, and inconsistent PRD output.

What makes prd-planner different

The differentiator is the 4-file pattern. Instead of dumping everything into one response, prd-planner creates separate files for plan, notes, PRD, and technical design, usually under docs/ with a shared scope prefix. That makes it better for Requirements Planning work that needs revisiting, review, and expansion.

When prd-planner is the wrong choice

Do not use prd-planner if you only want a quick feature brief, a loose brainstorming session, or a pure solution architecture document. The skill itself says architecture-only requests should go to architecting-solutions unless the user explicitly asks for a PRD.

How to Use prd-planner skill

Install context for prd-planner

This repository does not expose a universal package installer in the skill itself. The included README.md shows a local symlink-style install into a Claude skills directory:

ln -s ~/Documents/code/GitHub/agent-playbook/skills/prd-planner/SKILL.md ~/.claude/skills/prd-planner.md

If you use a different skill loader, adapt that pattern to whatever directory or registration method your agent platform expects. For GitHub browsing, the skill lives at skills/prd-planner in zhaono1/agent-playbook.

Read these files first

For a fast prd-planner install and evaluation pass, read files in this order:

1. skills/prd-planner/SKILL.md
2. skills/prd-planner/README.md
3. skills/prd-planner/references/edge-case-analysis.md

SKILL.md tells you activation rules, workflow intent, tool requirements, and the core file pattern. The reference file adds practical edge-case scanning guidance that materially improves PRD quality.

How prd-planner activates

The skill is designed to trigger when the user explicitly asks for a PRD, says “product requirements document,” or uses the equivalent Chinese phrasing. That matters because this is not a generic planning skill. If your prompt sounds like “design the architecture” rather than “create a PRD,” you may trigger the wrong workflow or get weaker results.

The 4-file pattern you should expect

A normal prd-planner usage flow creates four project files under docs/ using a short kebab-case scope:

docs/{scope}-prd-task-plan.md
docs/{scope}-prd-notes.md
docs/{scope}-prd.md
docs/{scope}-tech.md

This is the main operating model of the skill. If you do not want file creation or persistent artifacts, prd-planner is probably not your best fit.

What input prd-planner needs from you

prd-planner works best when you provide:

• a feature or product goal
• target users
• business objective or success metric
• constraints like timeline, platform, compliance, or existing stack
• known non-goals
• links to relevant code, docs, tickets, or examples

Without these, the skill can still draft a PRD, but it will rely more heavily on assumptions.

Turn a rough request into a strong prompt

Weak prompt:

Create a PRD for notifications.

Stronger prompt:

Create a PRD for in-app notifications for our B2B admin dashboard.
Users are account admins and support managers.
Goal: reduce missed follow-up tasks and improve response SLA compliance.
Constraints: web app first, existing React frontend and Node backend, no push notifications in v1.
Non-goals: email campaign tooling, mobile support.
Please use docs/notifications as the scope basis and call out edge cases, permissions, and rollout risks.

The stronger version gives prd-planner enough context to produce a PRD that is specific instead of generic.

Suggested prd-planner workflow in practice

A practical workflow is:

1. Ask for the PRD explicitly.
2. Give business context, scope, and constraints.
3. Let the skill create the file set.
4. Review the notes file first, not just the final PRD.
5. Correct assumptions early.
6. Ask for a second pass on edge cases, acceptance criteria, and technical implications.
7. Use the generated *-tech.md as a bridge into implementation planning.

This is where the skill beats a single prompt: you can iterate by editing notes and rerunning synthesis instead of restarting from scratch.

Use the edge-case reference early

The most useful support file is references/edge-case-analysis.md. It includes requirement-type classifications and codebase pattern scanning commands for things like deletion strategy, loading states, pagination, validation, and error handling. This is valuable for Requirements Planning because many weak PRDs fail on exactly those omitted behaviors.

Repo-specific tips that improve output quality

The skill allows tools such as Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, and WebSearch. In practice, that means prd-planner is meant to inspect an actual codebase and ask clarifying questions, not just generate text from thin air. If your environment blocks file writes or shell searches, you will lose much of the intended value.

Best prompt pattern for existing products

If the feature belongs to an existing system, include codebase pointers directly in your request, for example:

Create a PRD for bulk user deactivation.
Relevant areas:
- `src/features/users/`
- existing soft delete behavior
- admin audit log requirements
Please inspect current list, detail, and permission patterns before drafting requirements.

This steers prd-planner toward grounded requirements instead of abstract product writing.

What to review before accepting the output

Before you treat the PRD as final, check whether prd-planner captured:

• user roles and permissions
• explicit non-goals
• edge cases and failure states
• rollout or migration concerns
• measurable success criteria
• dependencies on current system behavior

A polished PRD without these is still risky.

prd-planner skill FAQ

Is prd-planner good for beginners

Yes, if you already know the feature you want but need structure. The file pattern reduces blank-page anxiety. But it is not a shortcut around missing product thinking; weak inputs still produce shallow requirements.

How is prd-planner different from a normal PRD prompt

A normal prompt usually returns one document. prd-planner skill is designed around persistent planning artifacts, which helps the agent keep research, progress, output, and technical follow-up separated. That usually leads to better revision quality and less lost context.

Is prd-planner only for new products

No. It may be even more useful for existing products because the reference material encourages codebase scanning for current patterns. That helps produce PRDs aligned with real implementation constraints.

Can I use prd-planner for architecture design only

Not ideally. The skill explicitly says architecture-only requests should use architecting-solutions unless the user is actually asking for a PRD. Use prd-planner for Requirements Planning, not as a catch-all design tool.

Does prd-planner require file write access

Effectively yes, if you want the intended workflow. The skill’s core value comes from writing and iterating on files. If your environment is chat-only, you can still borrow the prompting approach, but you lose the persistence model.

When should I skip prd-planner

Skip it when you need a tiny one-paragraph brief, a user story only, or exploratory ideation with no stable scope yet. The overhead of the 4-file process is most justified when the PRD will be reviewed, revised, or handed to engineering.

How to Improve prd-planner skill

Give prd-planner better scope definitions

The biggest quality lever is scope clarity. Provide a short, unique scope name and define what is in v1 versus out of scope. This keeps file naming clean and reduces requirement sprawl.

Feed business intent, not just feature names

“Build approvals” is vague. “Build an approval flow for purchase requests over $5,000 to reduce manual finance review time by 40%” gives prd-planner something it can turn into better goals, user stories, and acceptance criteria.

Provide known constraints up front

Tell the skill about stack, compliance, timeline, org boundaries, and existing workflows early. These constraints shape the PRD more than most users realize. Missing constraints often cause attractive but unusable requirements.

Ask for assumption logging explicitly

A strong prd-planner guide pattern is to tell the agent: “List assumptions separately in the notes file and flag anything needing confirmation.” This prevents hidden guesses from slipping into the final PRD as if they were settled facts.

Use codebase-aware edge-case analysis

If you have source access, ask prd-planner to inspect current patterns for validation, pagination, loading, permissions, and delete behavior before finalizing requirements. The provided reference file is especially useful here because it converts vague “consider edge cases” advice into concrete scans.

Review the notes file before the final PRD

Many users only read *-prd.md, but the quality bottleneck is usually in *-prd-notes.md. Correcting a wrong assumption in notes is much cheaper than rewriting a polished but misaligned PRD later.

Iterate on missing decisions, not wording only

After the first output, do not just ask for “more detail.” Ask for specific improvements such as:

• sharper success metrics
• explicit permission rules
• failure and recovery cases
• dependency mapping
• rollout sequencing
• open questions for stakeholders

That type of iteration improves decision quality, not just document length.

Common failure modes to watch for

Typical weak-output patterns include:

• generic personas with no real user context
• requirements that ignore current system behavior
• missing non-goals
• no treatment of edge cases
• technical design that reads like a template
• acceptance criteria that are too vague to test

These are usually input problems, not just model problems.

Pair prd-planner with stakeholder review loops

prd-planner usage improves when the first pass is treated as a working draft. Have product, design, and engineering review different artifacts: product reviews the PRD, engineering reviews the technical design, and everyone reviews assumptions. The file-based structure supports that division well.

Improve adoption by standardizing your own template

If your team likes the workflow, define your own preferred scope naming, docs/ conventions, PRD sections, and review checklist around prd-planner. The skill already gives a solid structure; your internal standards make the output consistently shippable.