docs: define an atomic agent.act goal with a bad and good example

Merged
KA
13d ago
+90-21
  • The skill and the docs said "one goal per act" but never said what a goal is, and their own examples broke the rule: 'add a todo named "Buy milk" and mark it done', 'add todos ..., complete the first'.
  • An atomic goal is now defined as one outcome that one check confirms. Two parts that each leave a state worth checking are two goals, each with its own act and check. Steps toward one outcome (opening the screen that holds a control, scrolling, closing a banner, filling one form) are the path and stay with the agent.
  • docs/core-concepts.mdx#goals owns the rule and shows a titled Bad and Good block. agent-steps, quickstart, ci, and coding-agents link to it instead of restating it.
  • skills/e2e/references/agent.md carries the same rule with // BAD: and // GOOD: comments, since skills render no titles; SKILL.md Rules has the short version.
// BAD: three goals in one instruction, one recording, no check between them.
await agent.act('open the Pro plan, set the seats to {seats}, and check out', { params: { seats: 3 } });

// GOOD: three atomic goals, each pinned before the next.
await agent.act('open the Pro plan');
await expect(screen.getByRole('heading', 'Pro plan')).toBeVisible();
await agent.act('set the seats to {seats}', { params: { seats: 3 } });
await expect(screen.getByRole('status', 'Seats')).toHaveText('3 seats');
await agent.act('check out');
await expect(screen.getByText('Order confirmed')).toBeVisible();

Examples split into one act per goal, each followed by a check: core-concepts' opening test, the Cypress migration, coding-agents' cart test, and the skill's "Buy milk" act. The decision-models example drops ", and verify it is listed" from its instruction; the expect and agent.assert after it already do that.

Left as they are, on purpose:

  • tools.mdx 'seed the cart with SKU {sku}, then check out': seeding is a runner-side API call the page does not show, so it is a path step toward checkout. It gains the missing check on Order confirmed.
  • mobile.mdx 'go to General, then About', reference/runner.mdx 'open settings and turn on dark mode': navigation toward one outcome, which the path list now names.
  • The benchmark agentic suites keep their compound scenario goals; splitting them re-records the committed cache.

Verified

Ran it locally: yes

  • Docs site (pnpm docs:dev), /core-concepts#goals: the Bad and Good blocks render with their titles.
  • Built e2e and read the shipped skill with npx e2e guide agent and npx e2e guide in apps/testbed: both print the rule and the BAD/GOOD block.
  • Example APIs checked against packages/e2e/src/types.ts; pnpm check passes, including the docs example sync and typecheck.

core concepts goals