Mechanism: Goal

Part of Mechanisms of Vibe Coding · Core · Start here.

One-sentence definition

A goal is an explicit statement of what must be true when the work is finished — symptom, boundary, and how you will check it — written before the agent starts changing code.

The problem

You open a chat and type: “Fix the auth bug.” The agent reads that as permission to improve auth. Twenty minutes later you have a refactored session module, a new dependency, and the original bug still present — or fixed in a way you cannot explain.

The model is not lazy. It is completion-oriented. Without a clear finish line, it invents one that sounds reasonable: cleaner code, broader fixes, “while I’m here” refactors. You only notice the scope creep when the diff is too large to review.

Symptoms:

• The diff touches files you did not mention and did not expect
• The agent says “done” but you cannot name what was verified
• You keep clarifying mid-session because the first prompt was a label, not a target
• Success and failure look the same until you run the app or tests

How it works

A usable goal has three parts, in order:

1. Symptom — what is wrong or missing, in observable terms (“Users with expired tokens see a blank screen instead of the login form”).
2. Boundary — what is in scope and what is explicitly out (“Change only auth/callback.ts and its tests; do not refactor the session store”).
3. Verification — how you will know the goal is met (“Existing test callback_redirects_when_token_expired passes; manual check: expired token → login page”).

Write these before the first edit. The goal is not a mood (“make auth better”); it is a contract the agent and you can both point to when scope starts to drift.

  Goal defined? (symptom + boundary + verify)
       │
       ▼
  Work pass ──► Verify ──► Matches goal? ──no──► tighten goal or loop
                      │
                     yes
                      ▼
                    Ship (or next goal)

Goals stack. A large feature becomes a sequence of small goals, each with its own boundary and verify step — decomposition in later layers. Even a single-session fix needs one goal, not a topic label.

When to use it

• Every session where the agent will edit code, config, or tests
• When you feel urgency (“just fix it”) — vague prompts hurt most under pressure
• Before agent mode, loops, or long autonomous runs
• When handing work to another person or a future chat (the goal becomes the handoff)

When not to use it

• Pure exploration (“how does this repo handle caching?”) with no intended edits
• Spike work where you want unconstrained output — rename the session so you do not merge by accident
• Unknown root cause — goal becomes “identify root cause of X” with verify “written hypothesis + one failing test that reproduces it”

Failure modes

Topic label — “Fix auth” → broad refactors. Fix: Symptom, file boundary, and test name.

Missing verify — Agent declares success without evidence. Fix: Concrete test, command, or UI check.

Goal as solution — “Use Redis for sessions” before diagnosing. Fix: State outcome; let the agent propose means unless you already decided.

Stacked goals — Five outcomes in one prompt. Fix: One goal per session; queue the rest.

Implicit boundary — You meant a small fix but never said it. Fix: State out-of-scope (“do not add dependencies”).

Minimal example

Context: A small Node API. GET /health returns 200 but the body is { "ok": false } because config.ready is never set after startup.

Steps:

1. Write the goal before prompting:

   Goal: GET /health returns { "ok": true } after the server finishes startup.
   Boundary: Only edit src/health.ts and src/bootstrap.ts; no new files or deps.
   Verify: pnpm test -- health.test.ts passes; curl localhost:3000/health shows "ok":true.

Use npm test / yarn test if that is what your repo uses — name the exact command.

1. Send the goal block first, then: “Implement only what this goal requires.”

1. Run verify yourself. If it still fails, reply with the failure output — not a new vague request.

Done when: Verify passes and the diff only touches bounded files.

Tool instances (optional deep-dive)

Portable idea above; tool-specific. Date: June 2026.

Cursor

• Paste the goal block at the top of the first message before @ file references.
• Plan mode: Ask for a plan that maps 1:1 to symptom, boundary, and verify. Reject out-of-boundary steps.
• Rules: “If the request has no verify step, ask for one before editing.”
• Before a loop, put the goal in the loop prompt template so every pass shares the same finish line.

Other tools

Same pattern in Claude Code, Copilot Chat, Aider, or terminal agents. Use the task/spec field for the goal block.

Related mechanisms

• Constraints / guardrails — pairs with goal boundaries; read next in Core
• Acceptance criteria — multiple testable conditions beyond one symptom
• Scope fence — one job per session; the goal defines the fence

Try it yourself

Exercise: Take a real backlog item. Rewrite it as a goal block (symptom, boundary, verify). Do not start the agent yet.

You need: Notes; five minutes

Done when: You can answer without hedging:

1. What will be observable when this is fixed?
2. Which files or areas are off limits?
3. What command, test, or click proves it works?

If any answer is “I’ll know when I see it,” tighten that line before prompting.