Problem Statements

By the Syncfusion DevTutorials team · Last updated October 21, 2026

Interview a stakeholder with a 5-question budget, pick the evidence that proves the problem is real, and write your first intent.md: user, problem, evidence, outcome with a number, and owner.

The Agent Builds for the Wrong Person

In the last lesson, one run failed in a surprising way.

The agent built a big data dump for an analyst.

But the real user was a finance lead. She only needed a short weekly report.

The code worked. The problem was who it was built for.

This lesson shows you how to stop that from happening.

You will learn how to write down who the feature is for, and why they need it.

A Real-World Example

A family asks a builder for a bigger kitchen.

A rushed builder knocks down a wall. The kitchen gets bigger, but the family is still unhappy.

They never wanted more floor space. They wanted room for five people to eat at one table.

A careful builder asks a few questions first. Who uses the kitchen? What is hard today? How will you know it worked?

AI agents are like the rushed builder. intent.md is the careful builder's notebook.

Press Run it.

In simple words:

The agent got the ticket and an empty intent.md file.

Nobody wrote down who the feature is for.

So the agent picked someone on its own.

It picked the wrong person, so the result did not match what was needed.

TL;DR

1. intent.md is a short file that says who the feature is for and why it matters.
2. The agent reads it before it plans any code.

3. It has five lines:

   • User → who it is for
   • Problem → what is hard today, and what it costs
   • Evidence → proof the problem is real
   • Outcome → what success looks like, as a number
   • Owner → who decides when there is a question
4. You get these facts by asking the stakeholder questions.
5. You have only a few questions, so ask the ones that matter most.
6. Ask about what and why, not about how to build it.
7. A good outcome has a number and a unit. "Faster" is not enough. "Under 10 minutes" can be checked.

What You Will Learn

In this lesson, you will learn:

1. What intent.md is, and why the agent needs it.
2. The five lines in intent.md.
3. How to interview a stakeholder with only five questions.
4. The difference between "what and why" questions and "how" questions.
5. How to pick evidence that fits the problem.
6. How to turn a vague goal into an outcome you can measure.

What intent.md Is

Who and Why, Before How

intent.md is the first of the three files in this course:

intent.md → spec.md → plan.md

It answers one simple question:

Who needs this feature, and why do they need it?

It does not say how to build it.

• It does not pick libraries.
• It does not choose files or functions.
• It does not describe the code.

The agent reads this file before it plans. If the file is empty, the agent guesses, just like with any other missing detail.

The Five Lines

A good intent.md has five lines:

• User = who the feature is for
• Problem = what is hard today, and what it costs
• Evidence = proof that the problem is real
• Outcome = what success looks like, as a number
• Owner = the person who decides when a question comes up

Each line removes a different guess.

A line that still says TODO counts as missing. The agent cannot follow something nobody wrote yet.

Watch the checks as each line is filled in:

Each line turns one more check green. With all five lines, nothing is left to guess.

Interview the Stakeholder

Five Questions, Four Facts

A stakeholder is the person who asked for the feature.

• In the React app, the stakeholder is Priya, a finance lead.
• In the ASP.NET Core app, the stakeholder is Marco, who also works in finance.

You can ask only five questions.

This is like real life. Stakeholders are busy, and their time is short.

Four facts matter most:

1. Who the user is.
2. What they do with the result.
3. What the problem costs them today.
4. What success looks like.

Everything else can wait.

Watch the same five questions spent in two different ways:

The first way asks about small details. It runs out of questions too early.

The second way asks about the person and the problem. It finds all four facts.

Simple lesson: spend your questions on the facts that change what gets built.

What and Why vs How

Some questions are about how to build it. For example:

Which Excel library should we use?

Most stakeholders do not know the answer. And they do not need to know it.

Choosing a library is the team's job.

Ask the stakeholder about their work, their problems and their goals.

In simple words: ask stakeholders about their world. Ask engineers about the technology.

A Question That Looks Like "How"

How will you know it worked?

This question starts with "How". But it is not about building anything.

It asks how the stakeholder measures success. That is a great question to ask.

Simple lesson: look at what a question is about, not at its first word.

Lab Exercise: Interview the Stakeholder

Open the interview and start asking questions.

Your goal: find all four facts before your five questions run out.

Each answer shows which fact it gave you, if any.

If you run out of questions, press restart and try a different order.

Choose the Evidence

Why Evidence Matters

Evidence is proof that a problem is real.

Evidence can be:

• Support tickets
• Usage numbers
• Complaints from customers
• Interviews with users
• Business numbers

Without evidence, you may build a perfect fix for a problem nobody has.

When that happens, the agent builds the wrong thing very quickly.

Pick Only What Fits

The interview gives you six evidence cards.

• Three are about the report problem.

• Three are about other problems:

  • a dark mode request
  • a slow login page
  • an app that crashes

Those other problems may be real. But they do not belong in this feature.

Adding them makes the problem look bigger. But it also points the agent at the wrong goal.

Simple lesson: link only the evidence about this exact problem.

The Outcome Must Match the Evidence

The checker also makes sure your outcome connects to your evidence.

Example evidence:

The weekly report takes two hours to clean up.

A good outcome:

The weekly report takes under 15 minutes.

This outcome improves the same thing the evidence measures: time.

A weak outcome:

More users log in every day.

This has nothing to do with the evidence, so the check fails.

In intent.md, you link evidence by its card names, like this:

Evidence: E1, E2, E3

Write a Measurable Outcome

Faster Is Not a Number

An outcome = what success looks like.

The team uses it to check if the problem is really solved.

Some outcomes sound good, but cannot be measured:

• Faster exports.
• Better reporting.
• An easier workflow.

There is no way to tell if these happened.

Good outcomes have a number and a unit:

• The weekly report takes under 10 minutes.
• The report is ready by 9 a.m. every working day.
• Zero manual fixes are needed.

Watch three outcomes go through the checker:

A number alone is not enough. The number must measure the same thing as the evidence.

Lab Exercise: Write intent.md

Now put it all together.

Open intent.md. Replace every TODO with what you learned from the interview and the evidence cards.

Press Check my intent.md.

The checker reads the lines in this order:

1. User
2. Problem
3. Evidence
4. Outcome
5. Owner

It stops at the first line that is missing or vague, and tells you what to fix.

What Changes per Tool

intent.md is plain Markdown, so every AI coding tool can read it.

The only difference is where the file is kept.

The five lines are the same in every tool.

Common Mistakes

Exercises

These exercises help you practise writing clear intent.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• intent.md says who needs the feature and why.
• It has five lines: User, Problem, Evidence, Outcome and Owner.
• You get the facts by interviewing the stakeholder.
• Ask about goals and problems, not about how to build it.
• Evidence proves the problem is real. Link only the cards that fit.
• A good outcome has a number and a unit, and matches the evidence.
• If nobody writes down the user, the agent builds for the wrong person.

Further Reading

• Pathmode: a tool built around writing intent before code.
• Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl, by Birgitta Böckeler: how much spec a change really needs.
• GitHub Spec Kit: how Spec Kit starts every feature with user stories.
• Kiro specs: how Kiro opens each spec with requirements.

Next: Scope and Non-Goals. You will learn how to remove the guesses that are still left.