goal-capture

goal-capture

Capture the goal as a machine-checkable contract at .lovable/goal.json. This file is the input to build-loop: capture a sloppy goal and the loop builds the wrong thing perfectly.

When to run

Trigger on intent, not exact wording: "set a goal", "what does done look like", "define acceptance criteria", "lock in the goal". Also implicitly: any "keep building until X is done" request with no existing .lovable/goal.json. Run this first, then hand off to build-loop.

What to produce

One file at .lovable/goal.json matching references/goal-schema.md, plus one roadmap item per criterion (status todo, linked via roadmap_id).

Do not produce prose plans, markdown todo lists, or "should feel good" criteria. The goal file is JSON because models corrupt JSON less than Markdown over long loops.

Procedure

1. Restate the goal in one sentence. Cannot do it? The goal is too vague. Ask the user to narrow scope. Halt rather than guess.
2. Draft 3-10 criteria. Each must be independently verifiable end-to-end. A passing build or unit test alone is not enough: the verify clause must exercise the real user-facing path. Read references/goal-schema.md for verify-clause patterns by criterion type.
3. Capture non-goals and guardrails. What is out of scope? Which files must the loop not touch (do_not_touch)? Which actions require asking first (ask_before: destructive DB ops, secret rotation, paid API calls)?
4. Set the budget. Default max_iterations: 12, ask_on_ambiguity: true. Raise the cap only if the user asks. The cap prevents runaway loops.
5. Create roadmap items, one per criterion, title equal to the criterion description. Capture the returned IDs.
6. Write `.lovable/goal.json` with every criterion's roadmap_id populated.
7. Confirm with the user before handoff. Show the criteria list. If they tweak anything, regenerate the file before invoking build-loop. Never silently re-interpret a criterion later.

Hard rules

• JSON only for the goal file. Markdown drift breaks the loop's evaluator.
• Every criterion has a `verify` clause. "Looks right" is not a verify clause.
• No criterion bundles two outcomes. Split them. The loop handles one at a time.
• Roadmap is the source of truth for status. passes: true mirrors roadmap done. On drift, roadmap wins and the file gets updated.
• Halt on ambiguity. If a term could mean two things ("make checkout secure", "polish the UI"), stop and ask with concrete options before writing the file.

Good vs bad

Bad criterion: "Auth works properly." Two hidden outcomes, no verify clause, "properly" undefined.

Good criteria: "C1: A new user can sign up with email and lands on /dashboard. Verify: complete signup in preview with a fresh email, expect redirect to /dashboard and a row in profiles." "C2: A signed-out visitor requesting /dashboard is redirected to /login. Verify: open /dashboard in an incognito session, expect /login."

Verification

After writing the file, validate it: parse .lovable/goal.json and check it against references/goal-schema.md (all required fields, every criterion with non-empty verify and a real roadmap_id). Expect zero missing fields and zero criteria whose verify clause contains "looks", "feels", "works properly", or "correctly" without an observable check. If any fail, rewrite that criterion before handoff.

Completion checklist

• [ ] Goal restated in one sentence the user accepted
• [ ] 3-10 criteria, each one outcome, each with an end-to-end verify clause
• [ ] Non-goals, do_not_touch, and ask_before captured
• [ ] Budget set, default 12 iterations unless the user raised it
• [ ] One roadmap item per criterion, IDs written back into the file
• [ ] File parses and matches the schema
• [ ] User confirmed the criteria list before build-loop was invoked

Any box unchecked: not done. Fix or say so.

Footguns

• Vague verify clauses. "UI is polished" gives the loop nothing to run. Fix: rewrite as an observable check (element present, request returns 200, redirect happens).
• Bundled criteria. "Signup and login work" fails as a unit and hides which half broke. Fix: one outcome per criterion.
• Guessing at ambiguity. "Secure" could mean RLS, rate limits, or 2FA. Fix: halt and offer the concrete options.
• Skipping the confirmation step. The loop then optimizes a goal the user never approved. Fix: show the list, get the yes, then hand off.

Red flags

Stop if you catch yourself saying:

• "I'll infer what done means from context"
• "One fuzzy criterion won't hurt"
• "The verify clause can just be 'build passes'"
• "I'll skip roadmap items to save time"
• "We can firm up the criteria during the loop"

Each of these moves the definition of done from the user to the loop. That is the exact failure this skill exists to prevent.