Spec Review

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

Review a pull request against the spec: block only what breaks a REQ, an AC or a constraint, and cite it. Then sort incidents into spec gaps and agent errors, and pick the layer that stops each one.

A Review That Argues About Taste

Welcome to Part 3.

The agent has built the feature. Now a person reviews the work before it is added to the main code.

Pull request (PR) = a set of code changes that waits for review before it is added.

Imagine a review with eight comments. All eight say "blocking".

Blocking = this must be fixed before the PR can be added.

But only four comments are real bugs. The other four are about taste:

• variable names
• spaces at the start of lines
• code style
• a for loop instead of map()

The author argues about style all day. The real bug stays, and users find it.

Simple lesson: a review should check the code against the spec, not against your taste.

A Real-World Example

A driving test has a checklist.

• Did the driver stop at red lights?
• Did the driver check the mirrors?
• Did the driver keep to the speed limit?

A good examiner fails a driver only for breaking a rule on the list.

A bad examiner fails a driver for playing the wrong radio station. That rule is not on the list, so the driver cannot fix it.

The checklist is your spec. A good review only blocks for things on the list.

Click the button and open the card.

• The starting review.md marks every comment as blocking.
• Press Check my spec. The checker shows the first comment that is marked wrong.

Simple lesson: a comment blocks only when it breaks a line in the spec. Taste is never a reason to block.

TL;DR

1. Review the code against the spec.
2. Blocking = the code breaks a requirement, an acceptance criterion or a constraint.
3. A blocking comment must name the line it breaks, for example REQ-1.
4. Nit = a small taste comment. The author may ignore it.
5. Formatting is a job for tools, not for reviews.

6. After release, sort each problem into one of two kinds:

   • Spec gap = nobody wrote the rule down.
   • Agent error = the rule was written, but the agent broke it.

7. Pick the fix that stops the problem from coming back:

   • Spec gap → add it to the spec or the repo docs.
   • Agent error → add a test or a lint rule.

What You Will Learn

In this lesson, you will learn:

1. How to review code against the spec.
2. How to tell a rule from a personal preference.
3. How to name the spec line a comment is about.
4. How to sort problems found after release.
5. How to pick the fix that lasts.

Review Against the Spec

Blocking Means "Breaks a Line"

Use blocking only when the code breaks something written in the spec.

That can be:

• REQ = a requirement, something the code must do
• AC = an acceptance criterion, a test of the result
• C = a constraint, a rule about how to build it

A good blocking comment names the line it breaks.

Example:

P1: blocking, REQ-1

The author can open REQ-1, see the problem and fix it.

Every blocking comment answers one question:

Which line in the spec does this break?

If you cannot answer it, the comment should not block.

Taste Is a Nit

Many comments are useful, but they are not rules.

Examples:

• "I would prefer a for loop."
• "This variable could have a better name."
• "I would build this method another way."

These are ideas, not requirements. Mark them as nits.

Nit = a small comment the author may think about, but does not have to change.

Watch a review get fixed, step by step:

Each real bug now names its rule. Each style comment is a nit. Now the real bugs stand out.

When a Nit Keeps Coming Back

Sometimes the same nit appears again and again.

For example, nine reviews all say "use 4-space indents".

That is no longer taste. It is a missing rule.

Turn it into a lint rule or a formatter setting. Then a tool checks it, and people stop arguing about it.

Simple lesson: a repeated nit is a missing rule. Let a tool enforce it.

Name the Right Line

A blocking comment only helps if it names the right line.

Example:

Blocking, REQ-9

This does not help if REQ-9 does not exist, or is about something else.

When you review a PR:

1. Read the spec.
2. Read the code changes.
3. Find the exact line the code breaks.
4. Name that line in your comment.

If no line matches, the comment is probably not blocking.

Watch what happens with the wrong line, then the right one:

The right line tells the author exactly what to fix.

Spec Gap or Agent Error

Two Kinds of Problems

Problems can still appear after release.

Most of them are one of two kinds.

Spec gap = the spec never said what should happen.

Example:

Archived orders showed up in the export.
The spec never mentioned archived orders.

The agent had no rule to follow, so it guessed.

Agent error = the spec said what to do, but the agent did something else.

Example:

REQ-2 says YYYY-MM-DD.
The agent wrote 10/1/2026.

The rule was there. The agent broke it, and nothing caught it.

This matters because each kind needs a different fix.

The Fix That Lasts

Once you know the kind, pick the fix that stops it from coming back.

For a spec gap, write the missing rule down:

• Spec → the rule is about this one feature. Example: what to do with archived orders.
• Repo docs → the rule is true for the whole project. Example: run the migration script before you deploy. Put it in AGENTS.md or CLAUDE.md.

For an agent error, add a check:

• Test → checks what the code does. Example: the date format is YYYY-MM-DD.
• Lint rule → a tool scans the code. Example: no file over 300 lines.

In simple words: missing rules go in writing. Broken rules get an automatic check.

Watch four problems get sorted, one at a time:

Each problem now has a kind and a fix that lasts.

Lab Exercise: Spec Gap or Agent Error?

Look at all eight problem cards. For each one:

1. Pick the kind: spec gap or agent error.
2. Pick the fix: spec, repo docs, test or lint.

Tech leads often do this after something goes wrong.

Press Check my spec when you finish. Every kind and every fix must be right.

What Changes per Tool

The folder changes from tool to tool. The idea stays the same: review the code against the written spec.

Common Mistakes

Exercises

These exercises help you practise reviewing against the spec.

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

What to Remember

• Review the code against the spec.
• Block only when the code breaks a REQ, an AC or a constraint.
• Always name the line a blocking comment is about.
• Taste is a nit, never a reason to block.
• Formatting is a job for tools.
• Problems after release are spec gaps or agent errors.
• Spec gaps get written down: in the spec or the repo docs.
• Agent errors get a check: a test or a lint rule.

Further Reading

• Harness engineering, by OpenAI: turning review feedback into checks.
• Understanding Spec-Driven Development, by Birgitta Böckeler: the review burden of spec-driven work.
• GitHub Spec Kit: reviewing against a constitution.

Next: Living Specs. You will learn how a spec changes after release, so it always matches what the code really does.