A feature proposal is how an idea gets evaluated before it becomes work. The most important thing it does is force the author to articulate the problem before jumping to a solution. “We should add dark mode” is a solution. “Our users report eye strain during long sessions” is a problem. The proposal starts with the problem.
When you need this#
- Features get built because someone thought they were cool, not because they solve a real user problem.
- The team has no structured way to evaluate whether a feature is worth building before committing engineering time.
- Stakeholders propose solutions directly (“add a button that does X”) without explaining the underlying need, leaving no room for the team to suggest better alternatives.
What each section is for#
Problem to solve - The core of the proposal. What pain does the user have today? Be specific. “Users can’t do X” is better than “improve the user experience.” If you can’t clearly state the problem, the feature isn’t ready to propose.
Intended users - Who benefits from this? A specific user type, persona, or role. “Everyone” is almost never the right answer. Knowing the audience shapes every design decision that follows.
Further details - Use cases, benefits, and how this connects to the bigger picture. This is where you make the case for why this problem is worth solving now instead of later.
Proposal - Your suggested solution. This should include the user journey: what does the user do, what do they see, how does their workflow change? Keep in mind that this is a starting point, not a final design. The team may come up with a better approach. (See From Problem to Feature: Scoping Work for more on keeping proposals implementation-independent.)
Documentation - How would you explain this feature to a user? If you can’t describe it simply, the feature might be too complex. This section also serves as a reminder that documentation is part of shipping, not an afterthought.
Testing - What risks does this introduce? What could break? This forces the proposer to think about the cost of the feature, not just the benefit.
Success metrics - How will you know this worked? Define both the business outcome (“reduce support tickets by 20%”) and the acceptance criteria (“user can do X without error”). If there’s no way to measure success, that’s worth flagging now rather than after you’ve built it.
The template#
### Problem to solve
> What problem do we solve?
### Intended users
> Who will use this feature? If known, include any of the following: types of
> users (e.g. Developer), personas, or specific company roles (e.g. Release
> Manager). It's okay to write "Unknown" and fill this field in later.
### Further details
> Include use cases, benefits, and/or goals (contributes to our vision?)
### Proposal
> How are we going to solve the problem? Try to include the user journey!
### Documentation
> How would you document or explain this new feature in our documentation
### Testing
> What risks does this change pose? How might it affect the quality of the
> product? What additional test coverage or changes to tests will be needed?
> Will it require cross-browser testing?
### What does success look like, and how can we measure that?
> Define both the success metrics and acceptance criteria. Note that success
> metrics indicate the desired business outcomes, while acceptance criteria
> indicate when the solution is working correctly. If there is no way to measure
> success, link to an issue that will implement a way to measure this.
### Links / references