Five Years of the Feature Alignment Document: How One Template Taught Us to Lead with the Problem

There’s a markdown template at Ambiki called the Feature Alignment Document. The first version was committed on October 27, 2021. The version we use today, almost five years later, would be unrecognizable to the founder who wrote the original — which is me. This is the story of what changed between those two versions, and what it cost us to learn each lesson the slow way.

The template on day one

The original template was called feature-alignment-template.md. I committed it as part of the very first /docs commit in our internal documentation repo, alongside the rest of the scaffolding for how we’d describe what we were building.

It had seven top-level sections:

• Name
• Team / Phase
• Feature Description
• Features
• Feature Requests
• Copy for the Website
• Related Terminology

Feature Description had subsections for who uses it, how it works, and a “Business Model” breakdown with one row per pricing tier — at the time, Free, Gliding, and Soaring. Related Terminology had subsections for synonyms, antonyms, typical population, and the kinds of therapists who would use the feature. Every field was a “TODO” placeholder. The template was a fill-in-the-blanks kit for documenting a feature you had already decided to build.

Read that list again. The word “problem” does not appear in it.

The whole template assumed you already knew what you were building. Its job was to make sure you described it consistently. Which was, in retrospect, a very revealing assumption to encode into a document we’d hand to every developer for the next several years.

Early additions and the illusion of progress

Within a few weeks I started bolting things on.

On November 30, 2021, I added something called the Innovation Framework — a section with prompts borrowed from creativity research: Associating (force new associations, metaphors, SCAMPER), Questioning (what is, why, what if), Observing (watch users), Networking (community feedback), Experimenting (try new technologies). A few months later, in February 2022, I added a wireframes section because we kept losing track of where the design files were.

Both additions felt like progress. I was making the template richer. More tools for the team. The Innovation Framework in particular felt like a meaningful upgrade — we were giving people a creative scaffold for the work, not just a documentation kit.

It took me about three years to notice the structural problem with all of it. Every tool I’d added — the wireframes section, the Innovation Framework, the personas, the SCAMPER prompts — was a tool for generating better feature ideas. None of them were tools for figuring out whether the feature should exist.

The stable years (2022–2024)

For the next three years, the template barely changed.

I touched it a few times. A typo here. A small clarification there. A new field for the Asana card link. The git log for those years is mostly cosmetic — the kind of edits you make when you believe the thing is essentially correct and you’re rounding off the corners.

In that period, we ran hundreds of features through this template. Each one got its own copy of the document, filled out, reviewed, and built. The template wasn’t failing loudly. Nobody was complaining about it in retros. Nobody was proposing replacements.

But underneath, the same pattern kept showing up in our post-launch reviews. Not always, but often enough to be a refrain. Someone would say it slightly differently each time, but it always meant the same thing:

We built the thing well, but we shouldn’t have built it.

The features were well-built. The team kept choosing the wrong ones to build well. And the worst part was that I couldn’t see the template as the source — because the template was working as designed. The fields all got filled in. The reviews happened. The work shipped on time. The thing that was broken was the assumption underneath the design, and the template, being silent on that assumption, never put it up for question.

The commit that changed everything

On October 31, 2024, I made a single commit to the template repo. The commit message is one line:

Move problem section to top of FAD.

The hash is 08aef55. The diff is small. I deleted the Problem section from near the bottom of the document and pasted it directly under the Feature Name, in position #2. That was the entire change.

The diff was small enough to look cosmetic. The impact was structural.

For the prior three years, our template had ordered its sections the way you’d write a marketing one-pager: name, team, goals, terminology, then the solution, then a long tail of rabbit holes and no-gos, and somewhere down at the bottom — almost as a postscript — a paragraph asking what problem this was supposed to solve. Here’s what that looked like, before and after:

Most teams, by the time they got to the Problem section in the old order, had already drafted the Solution. They’d been thinking in terms of features for two pages. The Problem field, when they reached it, was something they back-filled to justify what they had already designed. It was a rationalization step disguised as a discovery step.

Moving the section to the top didn’t fix that overnight. People kept writing the Solution first in their heads. But the new ordering forced them to look at the Problem field before they’d typed anything else. And once you do that often enough, eventually you notice that the Problem field — as it existed in the template at the time — wasn’t actually capable of supporting the thinking it now claimed to lead.

From reordering to rethinking

Here’s the entire Problem section, as it existed for the year after the reordering:

Explain the problem or need that this feature addresses. Be specific about the user or business pain point. Don’t include information about a solution.

One heading. One prompt. That was the whole tool.

Putting that at the top of the document, instead of the bottom, didn’t change how little the section actually asked of the author. “Be specific about the pain point” is barely an instruction. Teams stared at it. Wrote two sentences. Moved on to the Solution section, which had real structure — subheadings, fields for measurable outcomes, prompts for trade-offs.

The reordering worked as a diagnosis. It made visible something the old ordering had hidden: that we had been outsourcing the hard part of product development to a single sentence-long writing prompt.

This is roughly when I started drafting what would eventually become The Problem-First Method. I wrote it from a year of watching smart people stare at that one-line prompt and not know what to put in it.

The overhaul

On October 8, 2025, almost a year to the week after the reordering, I committed the overhaul. The commit message is unusually candid for git — four declarations, each one its own intent:

Update Feature Alignment Document template. Move solution to last. Add clarifying questions to help determine the problem. Update the name to be a problem or feature name.

Each of those lines is a structural change that, taken together, inverted what the document was for. The new template asked teams to do thinking that the old one had let them skip. Four of those changes deserve their own treatment.

Problem Discovery and the ten questions

The first section’s name changed from “Problem” to “Problem Discovery.” Small wording difference, large philosophical one — Discovery implies the work isn’t finished when you write the field; it implies the field is the record of an investigation, not a justification.

The document name itself changed too, from “Feature Name” to “Problem / Feature Name,” with this new instruction underneath:

Start with just the problem name — before you know what the feature will be. That’s not only okay, it’s preferable.

That sentence is, in many ways, the whole article. It makes it explicitly acceptable to write a FAD document for a problem you don’t yet know how to solve. The previous template would have refused to be filled in at that stage. The new one welcomes it.

And under the Problem Statement field, the template now carries a ten-question Problem Validation Checklist. Verbatim, because it’s worth quoting in full:

1. Whose problem is this, specifically? (Can you name the exact user segment or role? Not “our customers” — which ones?)
2. How painful is it (this will be helpful in prioritizing)? (What evidence do we have from support messages, calls, data, behavior?)
3. What are they doing today to cope? (Workarounds reveal pain depth; the more elaborate, the more serious.)
4. What measurable change would tell us the problem is gone? (Define the results — efficiency gains, reduced errors, lower stress — not the solution. How will we know if we’ve solved it?)
5. What are the competing constraints? (Who else is affected? What trade-offs or conflicts exist across stakeholders?)
6. What won’t we do? (Set explicit boundaries — appetite, scope, and no-gos.)
7. Where does this problem begin? (Trace it upstream. Is this problem a symptom of something earlier — process, policy, or product? Fixing the origin is almost always cheaper than fixing the symptom.)
8. What assumptions are we making? (List them openly so they can be tested, not buried.)
9. What could make this the wrong problem? (Pre-mortem the work — what would prove we’re solving the wrong thing?)
10. If we solve this, what becomes possible next? (Solving the right problem should expand what’s possible — for us and for our users.)

Question 7 is the youngest one. It was added on October 22, 2025, in commit c20a5f8, two weeks after the rest of the list landed. It replaced an earlier question that had asked how we’d know if we’d solved the problem. That earlier version is a perfectly reasonable question, but it asks about effects. The replacement asks about origins. The thesis of the replacement is one line: fixing the origin is almost always cheaper than fixing the symptom.

The confidence gate

Section 7 of the new template is the most distinctive addition in five years of editing this thing. It’s called Confidence Assessment. It asks the author to rate four numbers between one and ten — Problem Understanding, Solution Fit, Scope Accuracy, Success Metrics — and then to sum them. And then there’s this line:

Need 32+ to proceed.

That single line is a gate. Every version of the template before this one could be filled out at any level of confidence and shipped to engineering. The author could believe a 5/10 was good enough; the reviewers could disagree silently; the work would start anyway. The new version makes that disagreement impossible to suppress. If your total is 31, you are not ready. The template says so, in writing, before any code gets written.

The number 32 is mostly arbitrary. The function of the line is to make “we don’t know yet” a legitimate, even required, finding. That was the gap. We had plenty of process. What we lacked was permission to say the process hadn’t finished yet.

The pre-mortem

Section 4 of the new template is called “Pre-Mortem: What If We’re Wrong?” with three subsections: Failure Scenarios, What Would Prove Us Wrong, and Early Warning Signs.

Most of that section landed in the October 8 overhaul. But the second subsection — “What Would Prove Us Wrong” — went through a small wording change on October 22, in commit 89f4ecf. The original phrasing was “Invalidation Triggers,” which is technically correct, slightly clinical, and easy to nod along with without actually feeling. The new phrasing is harder. It asks the team to write down, in plain language, what evidence would force them to admit they were solving the wrong problem.

The pre-mortem, like the confidence gate, is doing something no field in the original 2021 template did: it asks the team to take a position they might later regret in writing. Which turns out to be very useful for preventing the regret.

Solution moves to the end

And then there is the structural inversion the October 2025 commit message announced first: “Move solution to last.”

After the 2024 reordering, Solution had still been sitting at position #6, right behind the Problem section and the standard connective tissue of the document. In the overhaul, it moved to Section 5 of an eight-section template — but more importantly, it moved behind Discovery Notes, Constraint Budget, and the Pre-Mortem. By the time a team reaches the Solution section in the new template, they have already documented what they learned in discovery, what they’ve ruled out of scope, and what would invalidate their problem framing.

The Solution section has its own subsections now: What It Is (Plain English), Problem-Solution Fit, Why This Solution, What This Doesn’t Solve. None of them can be answered coherently if Problem Discovery was skipped. The template enforces sequence. You cannot describe Problem-Solution Fit before you have written down the problem.

What the template taught me

None of this happened because I got smarter. It happened because the team built enough wrong things, over enough years, that the cost of the old template became legible. The template grew up the way scar tissue does. Each change traced back to a specific painful incident in how a feature had gone.

A few things stick with me from those five years.

The order of sections in a template is a value statement. For three years, our template said “Solution before Problem” in its structure, and the teams obediently thought that way. They were following the document faithfully. When we changed the order, we changed the thinking. There was no separate cultural intervention required — the template was the intervention.

Stability is not validation, either. The three years between 2022 and 2024 when the template barely changed felt, at the time, like a sign that we had gotten it right. In retrospect, they were a sign that nobody felt empowered to challenge it. Templates that don’t change after their author leaves the company are one thing. Templates that don’t change while their author is sitting right there, watching them produce the wrong outputs, are something else entirely.

And discovery, as the new template treats it, is a gate. The 32/40 threshold on the Confidence Assessment is the most important number in the whole document, because it makes “we don’t know yet” an acceptable answer. Every earlier version of the template implicitly required confidence. The current version requires honesty about confidence. Those are very different requirements, and we lost years to not noticing the difference.

If I’m honest about one thing, it’s that the move-problem-to-top commit was available to me by 2022. The signal was already there in our post-launch reviews. I didn’t make the connection for another two years, and the fix took five lines of diff once I did.

Where the method lives now

The FAD as it exists today is the lived backstory of The Problem-First Method. The template came first, and the book came out of it. Every chapter in the eBook — the Problem Atlas, the validation questions, the confidence framework, the discipline of writing down what would prove you wrong — is something we tried in the template first, watched it work or fail, and refined.

That’s worth saying directly because methodology books often work the other way: a framework gets invented, then sold, then teams try to retrofit it into their work. This one moves in the opposite direction. The work came first. The framework is what we ended up with after the work had revised our minds.

The next change to the template will probably be invisible for another year. Then it’ll feel obvious. That’s been the pattern every single time.