Problem, Solution, Release Note

Three fields sit at the top of every initiative and every ticket. They are the shortest things you will write and the most consequential: the Define session, the definition doc, the stories and the release all inherit whatever precision or vagueness you leave in them.

Each has one job.

A problem missing its cost is an opinion. A solution missing its capability is a feature request. A release note you can’t write means the change isn’t clear enough to build. All three sail through review, because nobody argues with a sentence that doesn’t say anything.

This is the craft page for those three fields. Discover is the phase the problem gets written in, Define is where the solution and the release note draft get built. This page is the standard each one has to meet, with an example of each.

The Shape That Says Nothing#

An invented ticket, written the way most of them arrive:

Problem: No audit trail for changes to customer accounts.

Solution: Explore and implement an audit logging system to track account changes.

The problem is the solution with “no” in front of it. Nobody has it, nothing is costing anything, and “explore and implement” admits nobody knows yet what should happen. It gets approved because there is nothing in it to disagree with, and then Define opens with forty-five minutes of reconstructing what it was for.

Two tests catch it:

• Cover the solution with your hand. If the problem still tells you something, it’s a problem. If it only describes the missing feature, you wrote one thing twice.
• Negate the problem. “No audit trail exists” negated is “an audit trail exists”. If the negation is your solution, you wrote a wish, not an observation.

Everyone files one of these eventually, usually in a hurry so the idea doesn’t get lost. The fix isn’t writing more carefully. It’s answering the questions below and coming back.

1. Problem#

The standard: what shouldn’t be happening, and what it’s costing us. A problem is an event, something that happened to someone at a time, with a consequence. Not a condition, not an absence, not a category.

Bad: “No visibility into who changed an account.”

Good: “A customer’s plan was downgraded mid-month and support couldn’t tell them who did it or when, so the escalation closed with a goodwill refund and no answer.”

The good one has a moment you can point at, someone absorbing the cost, and a decision that went the wrong way. That makes it arguable, which is the point: a statement nobody can disagree with is a statement nobody has checked.

Sharpen it#

Ask these in order. Each fails in a particular way, and the failure is the signal.

• What happens if we never do this? The most useful question and the most skipped. If the honest answer is “not much”, you found that out cheaply and there is no ticket. If it’s “support keeps closing disputes without an answer”, that answer is your cost.
• Who noticed, and when? Chase the moment. “Ops flagged it” becomes “which person, which day, looking at what?” If nobody noticed, that instrumentation gap is usually the better ticket.
• Who is absorbing it today, and how? Someone always is: reconciling by hand, giving up, apologising, answering the same question again. The workaround is your strongest evidence and it usually tells you what the solution has to do.
• What do they do instead? If the answer is “nothing, they just don’t do it”, you may have found a bigger problem than the one you started with.
• Is this the thing, or the visible part of it? “We can’t see who changed an account” may really be “three code paths write to accounts and only one records an actor”. Fix the symptom and it returns by another route.
• Why now? Usually volume, terms, a customer or a regulation changed. If nothing did and it’s been like this for two years, say so and argue it honestly rather than borrowing urgency.
• Who would object to fixing it? If nobody would, either it’s trivial or you haven’t found the tradeoff yet.

Put a number on it#

Get the number before you write the statement. Drafting first produces a number chosen to fit the story. Query the database, count the log occurrences, count the rows. Metabase and SigNoz answer most of these in one query, so don’t estimate what is one query away.

• State the window and the basis. “38 disputes in the last 90 days, 17 closed unresolved”, not “this happens a lot”.
• Be honest about direction. If a number cuts in the company’s favour, say so and state the real cost (trust, churn, liability) separately. A figure that doesn’t survive scrutiny discredits the whole ticket.
• Separate measured from extrapolated. Annualising a 90-day count is fine. Label it as such.
• If it genuinely can’t be measured, say why and what would make it measurable. That gap is usually part of the problem.
• Link the query so nobody has to ask you to reproduce it.

What isn’t a problem yet#

2. Solution#

The standard: what should happen instead, and what capability that opens up. What should happen instead is a behaviour described from the outside, not a table, a screen or a service. If the reader can’t picture what changes for the person who had the problem, it isn’t a solution yet.

Bad: “Build an audit logging system for accounts.”

Good: “Every account change records who made it, when, and the value before and after, whichever path it came through, so support can answer ‘who did this’ from the account screen. A disputed change can be reverted to its exact prior value, which is impossible today because no prior value is kept.”

Lead with the capability. A solution justified only by the pain it removes loses to one that names what becomes possible. Two framings, and good tickets carry both:

• Forward: what the team can do afterwards that it cannot do now. “Revert a disputed change to its exact prior value.” “Turn a payment method off without an engineer.”
• Backward: what it would have prevented, counted against real incidents. “A unique constraint on the reference column would have blocked all 14 known duplicate assignments.” The strongest form available, because the counterfactual is measured rather than argued.

Four rules:

• Name the mechanism, not the benefit. “An append-only table written in the same transaction as the change” beats “better data integrity”. A mechanism can be verified; a benefit can only be asserted.
• Prefer impossible over merely awkward. If it’s already possible but slow, say so. That’s an efficiency ticket, argued on the time number.
• Never write “explore”. If you don’t know what should happen, this is a spike, and its solution is “a written recommendation with a decision by <date>”. Say that instead of hiding the uncertainty in a build ticket.
• Give guardrails, not instructions. Constraints belong here (“must survive a restart”, “no new service”). File paths don’t. The how belongs to the engineer in Define.

3. Release Note#

The standard: the change made concrete, before and after. Write it before you build, in this format:

Release: [Feature name]

Before: [What happens today, including the thing that goes wrong]
After:  [What happens instead]

[Screenshot or demo video: added at Launch]

Bad: “Before: no audit trail. After: audit trail added.”

Good:

Release: Account change history

Before: A customer disputes a plan change. Support opens the account,
        sees the current plan and nothing else, and closes the ticket
        with a goodwill refund and no answer.

After:  Support opens the account, sees "pro to starter, 4 Mar, bulk
        import #4471", and either explains it or reverts to pro.

Three rules separate the two:

• Use real values. A real plan, a real date, a real job id. Invented examples hide the awkward cases; real ones surface them.
• Put the failure in the Before block. Not the happy path. The before-state should contain the thing that goes wrong today.
• Keep both blocks the same shape so the difference reads at a glance.

Match the form to what’s changing: a screen gets an ASCII mockup with real field names; a flow gets the sequence of events with times and amounts; data or an API gets the shape diff including the column or constraint being added; a capability that doesn’t exist yet gets the question someone asks today and the answer they get (“who downgraded this account?” → “unknowable”), against the answer they’d get after.

If you can’t write the Before and After clearly, the change isn’t understood well enough to build. If the After doesn’t feel worth reading, reconsider whether the problem is worth solving. Define covers the rest: deployment versus release, and what needs an announcement at all.

The Three, Written Together#

Take the invented ticket from the top of this page and put it through the questions.

What happens if we never do this? “Support keeps closing disputes without an answer.”

Who is absorbing it, and how? “An agent reconstructs the change from billing emails, then refunds as goodwill because they can’t prove it either way.”

How often, how much? 38 escalations in 90 days where a customer disputed a change they didn’t make, 17 closed “unable to determine”, 6 refunded as goodwill, around 40 minutes of agent time each.

Is this the thing, or the visible part? Three code paths write to accounts (admin screen, billing webhook, bulk importer) and only the admin screen records who acted. A log bolted onto today’s writes would come out blank for two of them. That reframes the solution.

Which gives you all three:

Problem: Two of the three paths that change an account record no actor, so when a customer disputes a change nobody can say who made it. Last 90 days: 38 disputes, 17 closed unable to determine, 6 goodwill refunds, around 40 minutes of agent time each.

Solution: Every account change carries an actor and is written with its before and after value in the same transaction, whichever path it came through, so support answers “who changed this, and when” from the account screen and can revert to the exact prior value. Neither is possible today, because no prior value is kept.

Release note: Before, support opens a disputed account, sees the current plan and nothing else, and refunds as goodwill. After, they see “pro to starter, 4 Mar, bulk import #4471” and either explain it or revert.

Same ticket, same underlying work. The entire difference is what got asked before it was written.

Before You Save It#

Problem

• Cover the solution with your hand: it still says something.
• An event, not an absence or a category, with someone specific at a specific moment.
• A number with a window and a basis, and the query linked.
• “What happens if we never do this” has an honest answer, and it isn’t “not much”.

Solution

• A behaviour someone can picture, not a component.
• Names a capability that is impossible today, forward or backward.
• The word “explore” does not appear.

Release note

• Before and After, same shape, real values, with the failure in the Before block.

Keep all three short. They’re read by someone deciding whether to care; the workings, taxonomies, phasing and open questions belong in the definition doc. If you can’t tick these, the fix isn’t more writing. Go back to the questions.

Related: Discover for the phase this happens in · Define for what happens once the problem is sharp · Structured Problem Solving and Issue Trees & MECE for breaking a large problem apart · Setting Good Metrics for turning the cost into a target.