Writing features and specs
When to write a PRD vs an FRD, and how to use the AI-generated drafts well.
Pencil ships with two kinds of feature documents: a PRD (product requirements) and an FRD (functional requirements). They answer different questions. The trick is knowing when each is worth writing, and treating the AI drafts as a starting point — never the finished doc.
PRD or FRD?
- Write a PRD when the question is why and for whom. New audiences, new pricing, anything where the engineering shape isn't the hard part. PRDs are short and read like a memo: the user, the problem, the bet, the rough shape of the answer, the measure of success.
- Write an FRD when the question is what exactly does this do. Auth flows, integrations, anything with state machines or edge cases. FRDs are long, exact, and read like a contract.
You almost never need both for the same feature. A small feature might need neither — a paragraph in the description and a list of iterations is enough.
Using the AI drafts
Open a feature, click Generate PRD or Generate FRD. The draft is decent but generic — it reads what's in the feature, fills the blanks with the most common answer, and stops. That's the point. The draft saves you the cold start; it doesn't save you the thinking.
Two moves that make the drafts useful:
- Read the draft and disagree with it. Where it's wrong is where you actually have an opinion. That's the part that matters.
- Strike anything you can't measure. AI drafts love phrases like "improved user experience." Replace them with "support 100 paying customers" or "p95 latency under 200ms" or delete the line.
The draft is in markdown, so you can rewrite freely. The version history is kept, so you can experiment.
Linking requirements back to features
The Requirements section on each feature is where you list the must-haves. Don't put the whole spec there — that's what the PRD/FRD is for. Requirements are the things you'd point to if someone asked "why did we mark this iteration done?"
Three to seven requirements per feature is the sweet spot. More than that and you're really describing several features.
Use a user story when the important thing is a person's outcome: “As a workspace admin, I want to invite teammates, so that onboarding is faster.” Pencil stores the actor, goal, benefit, optional Persona, and acceptance criteria together while keeping the same RQ-* identity and implementation-task links as any other Requirement.
Use an ordinary requirement for a specification or constraint that does not naturally belong to one user, such as “Invitations expire after seven days” or “The endpoint responds within 200 ms.” Stories and requirements live together because they move through the same approval, implementation, and verification lifecycle.
From Requirements, choose + User story for the guided sentence composer or + Requirement for a specification. From a feature, use + Story to inherit its Product and Feature automatically. Add implementation Tasks from the saved item's detail page; completing Tasks reports progress but never changes the story's lifecycle automatically.
What to try next
Read Iterations and shipping to turn your written feature into a stack of slices you can actually start work on.