Pencil / docs← Back to app

Writing features and specs

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:

  1. Read the draft and disagree with it. Where it's wrong is where you actually have an opinion. That's the part that matters.
  2. 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.

What to try next

Read Iterations and shipping to turn your written feature into a stack of slices you can actually start work on.