# Scope and Non-Goals Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Foundations Source: https://www.devtutorials.ai/learn/intent-engineering/foundations/scope-and-non-goals > The agent lists every decision it would make alone. Close each one the right way: a requirement it must build, a non-goal it must leave alone, or an open question it must ask about. Then name a health metric so the agent does not break something else. ## The Agent Does Too Much Agents like to help. Ask for an Excel export, and the agent may change other things too. For example, it might: - Tidy up the CSV export - Add the button to the mobile layout - Change how dates look across the app - Rewrite code that was never part of the request Nobody asked for these changes. Every extra change is a guess. And some guesses can break things other people depend on. ### A Real-World Example You ask a painter to paint your living room blue. The painter also paints the hallway. They move your bookshelf into the kitchen. And the smell is so strong that nobody can sleep there tonight. The living room is blue. But the painter made choices you never asked for. Three extra lines would have stopped this: - "Do not paint the hallway." → a **non-goal** - "Ask before moving furniture." → an **open question** - "The room must be usable tonight." → a **health metric** **Simple lesson:** say what to do, what to leave alone, and what must stay working. Press **Run it**. The instructions only say which file type to make. Open the **Agent** tab. The agent finds six more decisions about scope, and it guesses every one. It also picks a way of building that makes the grid slower. Now open **Preview & Checks**. Seven checks fail. **In simple words:** The instructions did not say where the work stops. So the agent decided for itself. And it decided to do much more than was needed. ## TL;DR 1. **Scope** = what is part of the work, and what is not. 2. Every open decision gets closed in one of three ways: - **Requirement** → build this - **Non-goal** → leave this alone - **Open question** → stop and ask 3. Never make up an answer just to remove a question. A made-up answer is still a guess. 4. A **health metric** = something that must not get worse. 5. A health metric needs a number and a unit, like "under 1 second". ## What You Will Learn In this lesson, you will learn: 1. Why agents do extra work when the limits are missing. 2. How requirements, non-goals and open questions remove guesses. 3. How to pick the right kind for each decision. 4. What a health metric is and why it matters. 5. How to lay out these sections in `spec.md`. **About the agent in this course** - The agent here is **simulated**. It reads `spec.md` with fixed rules. - Lines under **Requirements** get built. - Lines under **Non-goals** get skipped. - Lines under **Open questions** make it stop and ask. ## Three Ways to Close a Guess ### Requirement = Build This A requirement tells the agent what to build. Example: ```text Export only the rows currently shown by the filter. ``` The agent marks it **FOLLOWS** and builds it. Without this line, the agent guesses. It may export every row instead. ### Non-Goal = Leave This Alone A non-goal tells the agent what not to change. Example: ```text Do not change the existing CSV export. ``` The agent marks it **SKIPS** and does not touch it. Without this line, the agent may rewrite both exports to share code. That may look helpful. But another team may depend on the CSV export as it is. ### Open Question = Stop and Ask An open question is a decision nobody has made yet. Example: ```text Which date format should be used? Ask Priya before building. ``` The agent marks it **ASKS** and waits for an answer. Without this line, the agent picks a date format itself. **Important:** if you pick the format yourself, without asking, that is still a guess. ### Watch All Three at Work Press **Play**. Each step adds one section to `spec.md`. The guesses turn into FOLLOWS, SKIPS and ASKS. **Simple lesson:** all three remove guesses. They just do it in different ways. ## Choosing the Right Kind ### Three Questions to Ask For each open decision, ask: 1. Has someone decided to build it? → **Requirement** 2. Has someone decided to leave it out? → **Non-goal** 3. Has nobody decided yet? → **Open question** **In simple words:** - Requirement = yes - Non-goal = no - Open question = not yet One case can be confusing: "Leave hidden columns out." It sounds like "no". But it is a **requirement**, because the agent must build the export so hidden columns are left out. A non-goal is an area the agent should not touch at all. ### Lay It Out in spec.md Give each kind its own section in `spec.md`. Example: ```text # Spec: Excel export ## Requirements - REQ-1: The file format is .xlsx. - REQ-2: Export only the rows the current filter shows. ## Non-goals - Do not change the existing CSV export. ## Open questions - Which date format does the CFO want? Ask Priya before building. ## Health metrics - Grid first render stays under 1 second. ``` Clear sections help the agent and the people who review the work. You can also start a line with `Non-goal:` or `Open question:` instead of using a section. **Important:** the section changes the meaning. "Mobile layout" under Requirements means build it. The same line under Non-goals means leave it alone. ### Lab Exercise: Close Every Guess Priya (or Marco, if you chose ASP.NET Core) has answered the six open decisions. Your task: put each one in the right section of `spec.md`. Then press **Check my spec**. Every **GUESS** should become one of these: - **FOLLOWS** - **SKIPS** - **ASKS** If a line is in the wrong section, the checker tells you which kind the stakeholder meant. Leave **Health metrics** empty for now. **Look for signal words in the note.** - "Not sure" → open question - "Do not touch" → non-goal - "Not part of this" → non-goal For each sentence in a note, ask: is this a yes, a no, or a not yet? ## Health Metrics ### Meet the Goal, Break Something Else Sometimes a feature passes every check and still makes the app worse. Example: - The export works. All the stakeholder checks pass. - But the agent builds the file every time the grid opens, so Export feels instant. - Now the grid takes 2.4 seconds to open, not 0.6 seconds. In ASP.NET Core, the same thing can happen another way. The agent changes a shared query, and every request on the Orders page gets slower. The feature works. The app gets worse. **Health metric = something that must not get worse while you build the feature.** ### A Health Metric Needs a Number This line sounds useful: ```text Keep the grid fast. ``` But nobody can test it. What does "fast" mean? A health metric needs a number and a unit. Examples: - Grid first render stays under **1 second**. - Export stays under **5 seconds**. - API p95 latency stays under **200 ms**. **p95 latency** = 95 out of 100 requests finish within this time. Watch the difference. The spec is the same each time, except for the health line. The export works in every step. Only the line with a number protects the grid. **Important:** a health metric without a number does not count. - "Keep it fast" cannot be tested. - So the lab treats it as no health metric at all. ### Lab Exercise: Name What Must Not Get Worse This spec already has its requirements, non-goals and open questions. Only the health metric is missing. Your task: add one line under **Health metrics**. ## Practice on Another Ticket Here is another feature to practise on: - **React:** saved views. Users want to save their filters and use them again later. - **ASP.NET Core:** rate limiting. The export endpoint should limit how many requests each client can send. This time the note comes from stakeholder **B**. ### The Note Changes With the Variant The lab has three stakeholder versions: A, B and C. They agree on the main feature. But they want different small details. So a spec that passes for A may fail for B. **Simple lesson:** read the note again every time you switch versions. ## What Changes per Tool Requirements, non-goals, open questions and health metrics are all plain Markdown. Each tool keeps them in a different place: | Tool | Where scope and non-goals live | |---|---| | Claude Code, Codex, Cursor | `docs/specs//spec.md` | | Spec Kit | `specs//spec.md` | | Kiro | `.kiro/specs//requirements.md` | Health metrics for the whole team can also go in shared files, like `AGENTS.md` or `CLAUDE.md`. ## Common Mistakes | Mistake | Wrong idea | Correct idea | What goes wrong | |---|---|---|---| | No non-goals | "The agent will stay inside the ticket." | Name the nearby areas it must not touch. | It rewrites the CSV export and breaks another team's work. | | Guessing an open question | "I will just pick YYYY-MM-DD." | Write it as an open question, and say who to ask. | Your guess gets built as if someone had decided it. | | Writing a non-goal as a requirement | "REQ: share code with the CSV export" is fine. | Write "Do not change the CSV export." under Non-goals. | The agent does the very thing you wanted to avoid. | | No health metric | "If the feature works, we are done." | Name what must not get worse. | The grid gets four times slower. | | A health metric with no number | "Keep the grid fast" is enough. | Write "First render under 1 second." | The agent cannot check it, so it does not count. | | One long mixed list | "A bullet list is enough." | Use the four sections: Requirements, Non-goals, Open questions, Health metrics. | Reviewers cannot see what is in and what is out. | ## Exercises These exercises help you practise closing every guess. Press **Check** when you are ready. Use **Show Hint** if you get stuck. ## What to Remember - Scope = what is part of the work, and what is not. - A requirement tells the agent what to build. - A non-goal tells the agent what to leave alone. - An open question tells the agent to stop and ask. - Every open decision belongs in one of these three. - Never make up an answer just to close a question. - A health metric says what must not get worse. - A health metric needs a number and a unit. ## Further Reading - [Intent Engineering Framework for AI Agents, by Product Compass](https://www.productcompass.pm/p/intent-engineering-framework-for-ai-agents): a product manager's view of goals, limits and decision rights for agents. - [Kiro specs](https://kiro.dev/docs/specs/index): how Kiro writes requirements and their scope. - [Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl, by Birgitta Böckeler](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html): keeping a spec the right size. - [GitHub Spec Kit](https://github.com/github/spec-kit): how Spec Kit marks questions that need clarification. Next: **EARS Requirements**. You will learn a simple pattern for writing requirements, including what happens when something goes wrong.