Guess Gallery

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

Replay six failed agent runs. Sort each one into a context gap, an intent gap or a verification gap, then fix it in the layer where it lives: intent.md, a requirement, an acceptance criterion, a constraint or the repo docs.

Six Runs That Went Wrong

In the last lesson, you saw an agent make guesses.

In real projects, you usually see the problem only after the work is done.

For example:

• Someone reports a bug.
• A reviewer finds a mistake.
• A test fails.

This lesson shows six examples where the agent got it wrong.

Each mistake happened for a different reason.

Simple lesson: to fix a problem, first find out what caused it. Not all mistakes have the same solution.

A Real-World Example

A teacher says, "Make a poster."

• One student doesn't see all the instructions.
• One student gets unclear instructions and guesses.
• One student makes it correctly, but nobody checks it.

These are the same three ways AI agents fail.

Click the button and open the Gallery tab.

• Run 1: the agent shows GUESS because the spec did not mention hidden columns.
• Run 4: the agent shows FOLLOWS for every instruction, but the result is still wrong.

At first, both runs look the same because they both failed.

But the reason for the failure is different.

Simple lesson: before fixing a problem, find the real cause. If you fix the wrong cause, the same problem can happen again.

TL;DR

1. Most agent mistakes happen because of three types of gaps.
2. Context Gap = the answer exists, but the agent cannot see it.
3. Intent Gap = nobody clearly explained what should be built or why.
4. Verification Gap = the instructions are correct, but nothing checks if the result is correct.

5. Each gap is fixed in a different way:

   • Context Gap → add a constraint or update the repo documentation.
   • Intent Gap → update intent.md or add a requirement.
   • Verification Gap → add an acceptance criterion.
6. Find the gap first, then fix it.
7. A fix in a file helps every future run. A fix only in chat disappears when the chat ends.

What You Will Learn

In this lesson, you will learn:

1. The three gaps behind a failed run.
2. The five places where a fix can live.
3. How to find the first bad line in a run.
4. Why a fix in the chat does not last.
5. How to update spec.md so a mistake stays fixed.

The Three Gaps

Context Gap: The Answer Exists, but the Agent Cannot See It

Context gap = the right answer already exists, but the agent cannot read it.

Example 1: your team already has a toolbar button in this file:

src/components/Toolbar.tsx

Nobody points the agent at it. So the agent never opens it, and it builds a new button from scratch.

Example 2: your team has a rule for dates:

All dates must use YYYY-MM-DD format.

The rule lives in a wiki page. The agent cannot read the wiki.

For the agent, information it cannot read does not exist.

Ask this question:

Did somebody already know the answer?

If yes, it is probably a context gap.

Intent Gap: Nobody Wrote the Answer

Intent gap = nobody wrote down what should happen.

Examples:

• The spec never says what to do with hidden columns.
• Nobody wrote down who the real user is.

Here, the answer is not hidden somewhere. It does not exist at all.

Ask this question:

Was the answer written anywhere?

If no, it is an intent gap.

Verification Gap: Nothing Checked the Result

Verification gap = the spec was right and the agent followed it, but nothing checked the result.

Example: the spec says:

Export only filtered rows.

The agent shows FOLLOWS for that line.

But the code has a bug. The only test checks that a file downloads. That test passes, so the agent says it is done.

The result is still wrong. Nothing checked that the rows were really filtered.

Ask this question:

Did the agent follow the spec?

If yes, but the result is still wrong, it is usually a verification gap.

Press Play to see one run for each gap.

Each run failed in a different way. So each one needs a fix in a different place.

Ask the Questions in the Right Order

1. Did the agent follow the spec? If yes, it is a verification gap.
2. Did the answer exist somewhere? If yes, it is a context gap.
3. If not, it is an intent gap.

The order matters. If the agent followed the spec, more requirements will not help. You need a better check.

Simple lesson: find the gap before you write the fix.

The Five Fix Layers

Where Fixes Belong

Once you know the gap, decide where the fix should live.

Fix layer = the file, rule or check that stops the same mistake next time.

There are five layers:

• intent.md → the user, the goal, what is included and what is not. Use it when the user or the goal was wrong.
• Requirement → one decision in spec.md. Use it when one detail was missing.
• Acceptance criterion → a check in spec.md. Use it when a wrong result passed.
• Constraint → a file or pattern to follow. Use it when the agent should copy something that already exists.
• Repo docs → team rules in files like AGENTS.md. Use it for rules every feature must follow.

In simple words: put the fix where it stops the same mistake in every future run.

Which Layers Fix Which Gap

• Context gap → a constraint or the repo docs
• Intent gap → intent.md or a requirement
• Verification gap → an acceptance criterion

Choosing the Right Layer

Some gaps can be fixed in two places. One more question picks the right one.

For a context gap, ask:

Is this rule for one feature, or for every feature?

• One feature → a constraint.
• Every feature → the repo docs.

For an intent gap, ask:

Is one decision missing, or is the whole goal wrong?

• One decision → a requirement.
• The wrong user or goal → intent.md.

Examples from the gallery:

• Run 2 (wrong user) → intent.md
• Run 1 (one missing decision) → a requirement
• Run 3 (one pattern to copy) → a constraint
• Run 5 (a rule for every feature) → the repo docs

Reading a Failed Run

Find the First Bad Line

A run can have many lines. You do not need to read them all.

Find the first line where the agent did something the stakeholder would not want. That line usually shows the real problem.

• A GUESS line usually means a missing detail.
• FOLLOWS lines followed by a wrong result usually mean a missing check.

Watch run 4, one line at a time:

The agent followed both lines of the spec. The bug came later, when it built the code. Its own test was too weak to catch it.

More requirements will not fix this. A stronger acceptance criterion will.

Simple lesson: the first bad line tells you which gap you have.

Lab Exercise: Sort the Gallery

Go back to the gallery. For each failed run:

1. Pick the gap.
2. Pick the fix layer.

Press Check this run to check one run, or Check all six when you are done.

If you pick the wrong gap, the lab tells you why. If the gap is right but the layer is wrong, it tells you that too.

Your answers are saved in your browser, so you can come back later.

Fix It Where It Lives

The Fix That Stayed Only in Chat

This is one of the most common mistakes.

The agent gets something wrong. You reply in the chat:

Leave hidden columns out.

The agent fixes it. Everything looks fine.

A week later, someone starts a new chat. The same mistake comes back.

Why? Because the fix only lived in the chat.

• The repo did not change.
• The spec did not change.
• So the next chat had nothing to read.

Run it. The GUESS for hidden columns comes back.

The agent did not forget. The fix was never written where a new chat could read it.

Watch the same fix over three chats:

• Session 1 works, because the fix is in the chat.
• Session 2 fails, because that chat is gone.
• Session 3 works, because the fix is now in spec.md.

Once a fix is in the spec, every future session gets it.

Lab Exercise: Fix Run 1 in the Spec

Run 1 has an intent gap.

The spec already has two correct lines. Your task is to add the missing one.

The stakeholder's note has everything you need.

The exercise passes when:

• hidden columns show up as a FOLLOWS line, and
• the two lines you already had still work.

What Changes per Tool

The three gaps and the five fix layers are the same in every AI coding tool.

Only the file locations change.

The folders are different, but the ideas are the same.

Common Mistakes

Exercises

These exercises help you practise finding the gap and choosing where the fix goes.

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

What to Remember

• Every failure comes from a context gap, an intent gap or a verification gap.
• Context gap: the answer exists, but the agent cannot see it.
• Intent gap: nobody wrote the answer down.
• Verification gap: nothing checked the result.
• Find the gap before you choose a fix.
• A fix in the chat is gone when the chat ends. A fix in a file lasts.
• Put the fix where it stops the same mistake next time.

Further Reading

• Harness engineering, by OpenAI: why knowledge outside the repo does not exist for the agent.
• Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl, by Birgitta Böckeler: how much spec a change needs.
• GitHub Spec Kit: where the constitution and specs live in a Spec Kit repo.

Next: Problem Statements. You will interview a stakeholder, link what you write to real evidence, and create your first intent.md.