How to turn a feature request into a one-page spec

What a one-page spec is for

A one-page spec is a short document that answers one question: should we build this, and if so, what exactly? It is not a full product requirements document with diagrams and sign-off rounds. It is the step between a request in the inbox and a piece of work your team can estimate, argue about and either start or drop.

The spec works best when it is short enough to read in five minutes and specific enough that a builder can say yes, no or not yet without another meeting. That usually means one page, one problem, and a clear boundary around what is in and out.

Start with the problem, not the feature

Customers ask for features. They describe the button, the field or the report they imagine. The request is a clue to the problem, but it is not the problem. A spec that starts with "add a CSV import" gets stuck on the format. A spec that starts with "customers with more than 200 items cannot get their existing data into the product" lets the team consider several answers.

Write the problem in one or two sentences, in terms of who is affected and what they cannot do today. If you cannot write it that way, you do not understand the request well enough yet, and the next step is more questions, not more design.

Gather the evidence from feedback

Next, list the evidence. This is the part most teams skip, and it is where a one-page spec earns its keep. Search the inbox for the words customers used, and group the matching items. A short list is enough: how many people asked, what their situations had in common, and whether any of them are paying close attention to this area.

Be honest about what the evidence is. A few messages from your most engaged users are a signal, not a verdict. Write the count and the variety, not a big claim. For example, "four customers asked for an import in the last month, two of them from teams with more than one product" is useful and true. The notes on each item, which are private, are where you keep the links to those messages so the spec can point to them.

Write the scope and the non-goals

Scope is what the first version will do. Keep it small. A first version that solves the core problem for the most common case is almost always better than one that handles every edge. If you cannot describe the scope in three bullets, split the request.

Non-goals are what you are deliberately not doing. They matter more than most teams realize, because they stop the spec from growing during review. "Not doing: importing from other tools directly, editing imported records in bulk" is a sentence that saves weeks. Name the requests you heard that fall outside this version, so the next reader knows they were considered.

Keep the open questions visible

Every spec has open questions. Hiding them makes the spec look finished and then breaks the build. List them at the bottom, each with a name next to it. An open question might be "who can run the import, admins only or every member?" or "do we keep the original file after the import?" Naming an owner turns a question into a task.

If an open question blocks the scope, the spec is not ready. If it does not, note it and move on.

The one-page template

Copy this into a note, a doc or the internal note of the feedback item. Keep each heading, and fill in what you know. Delete the parts that do not apply, but keep the non-goals and the open questions, even if they are short.

Title: [short name for the change]
Problem: [who is affected and what they cannot do today, in one or two sentences]
Evidence: [number of requests, the variety of customers, links to the feedback items]
Scope: [three bullets at most, what the first version does]
Non-goals: [what we are deliberately not doing, and the requests this leaves out]
Success: [how we will know the change worked, in plain words]
Open questions: [question, owner]
Decision: [planned, closed or not yet, with the date and the reason]

The Success line is easy to skip. Write it anyway. "Customers can import a file of 500 items without writing to support" is a check you can run later. "Users are happier" is not.

Review the spec with the people who will build it

Share the spec before anyone starts work, and ask the builders one question: what would make you say no? Their answer usually reveals a hidden assumption, such as a data model you did not consider or a support cost you had not counted. Update the spec with what you learn, and mark the decision.

Keep the review short. Fifteen minutes is enough when the spec is one page. If the review takes longer, the spec is probably trying to do too much.

Where the spec lives next to the feedback in Escuta Produto

In Escuta Produto, the feedback item is the place where the request lives, and the internal notes on that item are private to your team. Put a link to the spec in the note, along with the decision and the date. Set the status to planned when the spec is approved, or closed when you decide against it, so the item and the document tell the same story. The meaning of each status is covered in how to design a feedback status workflow.

When the work ships, the spec's Success line tells you what to say to the people who asked. The steps for that message are in how to tell customers their request shipped. For the broader process of grouping requests into themes before writing specs, see how to turn customer feedback into a roadmap. The REST API is documented in the API docs, and the Slack or Discord alerts that bring new requests to your team are set up in the notifications docs.