Do the task once, then compose its script
A write build changes something real on the caller's account: an order, a booking,
a submitted form, a saved profile. There is no practice run. The write is the whole
task the request asks for, done once, live, with the caller's values, as a series
of act steps. When the caller's input is empty ({}), pass the request's values and
the owner's answers as exampleInput (JSON text) on each act step that needs them. When it
leaves out values the request states, pass it with them added as exampleInput, keeping every
value the caller sent as sent. The first act step that passes it fixes it: later steps repeat
it unchanged or omit it, and every step from then on runs that one input. Decide from the
request and the site which inputs are required, and keep them required. An optional
input plus a declared question the tool asks before any effect is only for a value the
request genuinely leaves open; never make a value the request states optional with
nothing that asks. It may take several write steps: filling in and advancing a
multi-step form, choosing options, saving, then submitting. Drafts, autosaves and the
saves a site makes at each step along the way are part of that one task. You never
redo the whole task, and never redo a step that finished; run a step again only when
a fresh read of the page shows it did not finish, or the task cannot complete without it. Then you compose the
published script from what those steps did and publish it. Nothing runs again.
In a build whose caller input is empty ({}), when the request names a list of same-kind targets
and the site makes the same write once for each, such as a message to each of several recipients,
build a one-target write tool: it must take one target, and its description must tell the caller
to call it once per target. Never build one that repeats the write over the list. Pass the first
target's values as exampleInput, so the session writes that target only; called once per target,
the tool carries out the whole list. A form saved over several pages for one record, one order of
several items, each added to that order before its one final submit, one action the site takes
over many targets, such as a send to a group picked in one form, and a read of many things are
each fine as one tool.
A read build may search, filter and query, but may not fill in or advance a form that saves data on the site, save or submit anything; a task that needs that is a write build. Signed out, setting the session's store, location or delivery or pickup mode is part of a read, even through a Save button, and so is entering the details the caller gave to set it, unless the step creates an account or a lasting record on the site (core skill). Signed in, setting the session's delivery or pickup location through the site's per-visit control is part of a read too, unless the step's requests save an address-book entry, a default or an account preference; that is a write. While building, a live step, the example's or a test case's, that enters a name, email or phone asks the owner first, as the execution review requires; the answer keeps the build a read. Adding to a cart, a hold on inventory, a seat or a time slot, an upload and a draft stay writes, signed out too. Never click a control that can add to a cart in an explore to see what it opens; that click is a write. Read the item's options from the page or the item's own page instead; opening an item's details or options from its own card, name or picture, not a control labelled add or plus, is a read.
When a read build finds it needs to write
When a read build's task turns out to need that (a form that saves each step, a search
that is really a booking), ask the caller with request_input whether the build may make
that change, saying in one or two plain sentences what it would change on the site and why
the task needs it. Ask as soon as exploration shows it; a live read example that already ran
is fine, though it never stands in for the write. Once they confirm, by picking your option
or in their own words, call mint_update with the change {"setting": "effect", "effect": "write"} and the answered question in confirmedBy. Guardian reviews it. An updated result
makes this a write build in place: every later step is reviewed under write authority and the
rules below, what you explored stays valid evidence, and the first act step starts on the
site origin page. If they keep it read-only, finish what a read can do, or recommend a new
write build with mint_update and recommend: "new_mint".
Before the session
Sign in first when the site needs it, and for a cart or checkout as .agents/cart/SKILL.md
says (a tool that fills a cart and returns its quote in one run may use the site's guest cart),
with the auth skill: read-only explore to find the login, then
authenticate. Before the first act step you may still explore
read-only, for example to read the first page's options, and set the session's delivery or
pickup location as a read (above), with pickValue and the site's own confirm control in one
step. Never fill, select, add, save or submit anything else there, except one made-up key in
the site's own format, with a
serial past any the site lists, per input that takes a record's own key, looked up once in the
site's own lookup to see what it shows for a key it has no record of (core skill).
Settle the whole path before the first act step, from the request and what read-only
exploration shows, such as the form's list of pages or steps: every step that saves or submits
on the site, through to the outcome the request asks for, such as the quote or decline, the
placed order or the confirmed booking; prefer not to end at a saved draft or a new account on
the way to it. When the caller's example already shows the requested change done, ask the owner
with request_input for one that does not. Publication judges the finished tool by the same rule
(reference/publication-review.md). Declare it as writePath on the first act step: in
steps, each step that saves or submits, in order, with the commit mark its helper will
enter and what it saves (does); in ends, what the last step leaves the caller with. When the
request ends before any save, steps is empty: never name a step that saves nothing. Mark
setup: true on a step that only makes state the site creates by itself as the session starts,
such as an empty cart when the menu opens, and saves nothing of the caller's, or leave that step
out.
Guardian reviews the path before anything is sent, and the host keeps it: the session is not
over until every mark on it but a setup step's is entered, so a step that confirms earlier
leaves the session open, and its receipt's writePath lists the marks not yet settled. When the page shows the
path must change, such as a page the site skips or adds for this input, declare the revised
path in writePath on the next act step, keeping every mark already entered. When no single
session can reach the outcome, such as a step that waits for another person's approval, an
emailed link or a later date, or Guardian denies the path for that, end with report_blocked
reason site_lacks_capability before the first act step, naming that step: a build has one
write session, never a second.
Read the path's options with read-only exploration where you can, and settle them before the
first act step where possible: ask with
request_input about the ones the caller's input does not settle, as AGENTS.md ("Try
hard, then ask") says: each costly choice you saw, one that changes what the caller buys or
pays or whether the action can be cancelled or refunded (each paid add-on and pre-selected paid
option within the tool's purpose, a rate, fare or plan tier, a refundable or non-refundable
option, shipping speed, how much of a balance to pay, the payment method and the delivery
address), and any other option only when
the request's purpose clearly depends on it. When the write must take one of a service's tiers
of speed, class or service level that the caller's input does not settle, take the tier the site
presents as standard instead of asking and list it in finish_build assumptions; ask only
when the site shows no standard tier. An unasked optional field keeps the page's
default and is still an optional input of the script. Prefer keeping the value the page
already shows in an optional field that adds no cost over asking the caller to confirm or
correct it, and list it in finish_build assumptions. Ask only about options the site
actually shows. A control with exactly one possible value (a select or radio group with a
single option), or one the input or an earlier answer already settles, is no choice: never ask
about it. An add-on toggle, a pre-selected paid option or a lone saved payment method or address
is still a choice to ask about. Never keep, clear, accept or decline one of those unasked. A paid upsell
outside the tool's purpose, such as a membership, subscription or trial offered during a
checkout, is not a question: the script declines it, and never accepts one without an input
the caller set for it. A safety default (core skill, "Safety defaults") is
neither: never ask about it, and the script turns it off. Credentials never go through a
question; the host's protected form owns them.
During the session:
- Finish everything that can still refuse the task or change what it commits before the
mark of the commit it guards: choose each option that changes the price, decide each add-on
from the input or an answer and decline an out-of-scope upsell, read the selected options
and total from the current page or an available read-only summary, check the total against
any limit the input sets, stop when the page shows a paid option selected that neither the
input nor an answer settles, and check the items, address and payment. Use a review page when
the site has one; a separate review page is not required, and submitting a form is never a way
to discover whether one exists. A check that can only run after an earlier
marked step, such as a total that shows only once a saved address step has run, runs before
the later step's mark; its refusal then reports a possible change, because the earlier step
may have saved something, and that is honest. Still mark that earlier step. Mark a commit
step as a setting in
write.settingswhen its click only changes a choice on the way to the final commit and cannot place, buy, book, send or charge anything by itself. AnInvalidInputor a declared refusal after only such steps, the caller's no included, ends with nothing applied. - When one of those checks rules the task out, such as a total over the caller's limit, an
item out of stock or a variant the page does not offer, the script refuses before the mark
with
InvalidInput(the caller-input skill, "Throw the error that matches what happened"), or returns a refusal its output schema declares before its first mark (below). Never return a refusal in an output shape the schema does not declare. Apart from such a declared refusal, prefer throwing over returning when a write stops before its first commit mark. After a mark, when a step's result is unclear and commit steps remain, prefer reading the site's own record of what saved, such as the cart or the saved form, then finishing the remaining requested steps and the final read-back withverified(), over throwing or returning early: publication review refuses a path that stops there. A field error the site shows after an earlier save still throwsInvalidInputwith that field and the site's message. A report of the form's fields, its validation messages or the options to pick from is a refusal (InvalidInputwithavailable) or a failure (OperationFailure), not the write's output. - While building, when the site says no to the example's valid input before any save step, as
"The session" below describes, or shows a record already past the state the action needs when
the request says to stop and report it, prefer publishing the tool with that no as the
example's answer over asking the owner to revise or stop or ending the build with
report_blocked. The act step that meets the no, the session's first when exploring already showed it, returns it right after reading it, without leaving the page and before entering any commit mark, as a refusal its output schema declares (below). Run no other act step after it. Compose the whole pathwritePathdeclares from the caller's input, returning the same refusal at each point where the site may say no. List every save step inwrite.commitsand again inwrite.commitsUnproven, and callfinish_buildwith that step'sexecutionId. Prefer keeping the caller's facts as given over changing them to get past the no. Any other limit the session meets is the owner's to settle first: ask them to revise or stop, as the cart skill's "Minimums and refusals" says. End withreport_blockedwhen they stop, when the session cannot reach the task's end, or when the site's no rules out every input the tool could take (site_declined). - When the caller's own task asks for whatever the site ends up with, such as the product a
quote ended up on, follow the site's preselected substitute and return the value the site
used instead of throwing
InvalidInput. Only the caller's task text counts this way; an output field or description you wrote does not. - When a write's form adds required fields that depend on earlier answers, prefer declaring
the site-field question and asking it for a required field that no input covers, before that
step's commit mark, over refusing. When such a field shows only after the step's click, ask it
once
blockingRequiredFieldsreturns it, which proves the click saved nothing: callnotCommittedfor the step before you ask, then fill the answer, check the step again, then callenteringCommitagain with the step's name, and click once. When a step shows several such fields at once, ask them in one round, declaring one site-field question per field. It isn't for passwords, codes or logins. WhenblockingRequiredFields(form, before, { unaskable: true })returns{ unaskable: true }after the step's first click, the click saved nothing but a field it flagged is one no site-field question may ask, such as a card or bank field: callnotCommittedfor the step, then throwInvalidInputthat names the field by its label, and don't click again. - Before the first commit mark, prefer looking up every existing entry the caller names, each item
and option included, with read-only steps, in the session and on every run of the composed
script. On a write saved across several pages, when the site's own option lists for a later page
can be read before the first save and do not depend on what an earlier page saves, such as the
form definitions or option data an earlier page loads, prefer reading them too and checking
every caller value for those fields against them. Match each value by the site's option value as
well as its label (forms skill), and count matching items by the site's own item id where the
page shows one, so an item listed in more than one place is one match, not an ambiguous one.
Refuse with
InvalidInputandavailablebefore anything is saved when a value matches nothing. A refusal after an earlier save leaves a half-made record and an outcome the caller can't know. - A pop-up, banner or interstitial on the path, such as an upsell, is conditional unless the page always opens it in answer to an action: handle it as the forms skill says, so the tool still works for a caller who never sees it.
- Before committing, read back from the page what you are about to submit and check each
value as the core skill's Confirm step says, against the option the tool picked when it
picked one, or the site's version of a typed value it rewrote (below), in the session and
on every branch of the composed script. When a structured value ("Check the read-back")
does not match, pick or type it once more, and throw
InputNotAppliedif it still differs. Prefer running this check before the step's commit mark, so a mismatch stops the step before it sends anything. A free-text value the page rewrote is kept, as the next bullet says. Never read back a field filled with a secret handle. Prefer confirming a pick from the site's own selected state, or from a shorter display read as the whole-word start of the whole option, over comparing it with a piece the script cut from the option. - Read each typed value back once its field settles, before the step's commit. When the site
rewrote it as it was typed or on leaving the field, such as an address it standardized, or
offered exactly one suggestion for it that matches it cleanly or that
pickerMatchAddressaccepted, take the site's version, as you would a picked option: later read-backs, such as a review page, summary or confirmation, compare against it, and the output returns it for that field. Ask about any other lone suggestion as about a looser match (core skill). The one suggestion counts only for a free-text value the caller typed, such as an address or a name in a text box the site completes, never for a picker that selects a record, such as a person, assignee, customer, linked record, store or account, which keeps the reference rules in "Check the read-back" and the caller-input skill's. Add an optional output field<input>_note, such asaddress_note, that reports the rewrite with what the caller sent and what the site kept. Check it once withsameText(shown, typed, { rewrite: true }), which only decides what the note says: when it holds, the site only reformatted the value, and the note says so; when it fails, the site dropped or changed part of what the caller gave, and the note says it changed. The write goes on either way: never throwInputNotAppliedfor such a rewrite. A value cut short by the field's length limit, digits an input mask dropped, or a field that cleared is a failed fill, not a rewrite: fill it again in the field's format, or refuse as today. A value the site replaces only when a step saves follows the read-back before committing, above. - On a form saved over several pages, before the final commit, read back what the site saved
for the caller's values, from a summary, a review page or each saved page, in the session
and in the composed script. Compare each value the site shows with
readBackMatches(shown, wanted)frompomerado/runtime, against the option the tool picked when it picked one, or the site's version of a typed value it rewrote (above):wantedis that option's label or that version, and the caller's value otherwise. It accepts the same value in another format or word order, such as 1,50 for 1.5, and every number must be the caller's, the same numbers in the same order. When the site kept a different structured value, save that page again once with the same entries and read it back again, but only when saving it again updates the same record or page, never when the save adds an item, such as a cart line or a row. PrefersaveAndReadBackfrompomerado/runtimefor such a page's save, with the free-text fields infreeText: it does both and returns the values that still differ. When a structured value still differs, or a page whose save adds an item kept a different structured value, stop before the final commit's mark and throwInputNotAppliedwith itsfield,requestedandapplied. Prefer keeping a free-text value the site saved differently: later read-backs compare against it, and the output lists it insaved_differences("Check the read-back"). - When the write changes state that already exists, such as a saved record or a cart
(.agents/cart/SKILL.md), read that state before the committing step and again after it,
in the session and in the composed script. Once the commit is confirmed (below), a field the
input sets that did not change as asked goes in
saved_differences, and any other difference follows "Check the read-back" below: the script still callsverified()and reports the difference in its output. Read both through the same query or view, selecting the same fields: two read paths, such as a list's row and the record's own detail view, can return the same unchanged field in different shapes, and a comparison across them then reports a change that never happened. - When a write creates something, such as an application, claim or draft, outside a cart (cart skill), and the request does not ask to continue or update one, prefer making a new one on each run, even when the account already holds an unfinished one, such as one an earlier run left, since a caller may want several. Continue an unfinished one only when the site refuses a new one, and, in a tool that can continue one, say in the output which it did.
- Continuing an unfinished one is still this run's create, not a change to state that already
exists: fill each field its pages offer from this run's input, set each field this run leaves
empty to what a new one starts with (blank or the site's default) rather than the value the
draft holds, and compare the read-back against this run's values alone, with no
before-and-after comparison, so nothing an earlier run saved stays or shows in
saved_differences. - If a step meets an option the input does not settle, stop that step before choosing
it and ask, in one round for the whole page once every value the input and earlier answers supply on it is filled (forms skill). A
request_inputquestion during the session waits in place; a choice that exists only on the page mid-flow, such as a seat on the flight just chosen, is a declaredaskin the nextactstep's script (the caller-input skill). An answered question settles the option. Check the page again before continuing. - A code the site sends during the write, signed out too, such as one confirming an email or
phone the form took, belongs to the write, not a sign-in: prefer a
secretquestion of kindone_time_codethat the nextactstep's script asks, as the caller-input skill's code example does, overauthenticate. A code screen that signs you in, such as one a checkout opens to sign in and continue, is stillauthenticate, even partway through a write (auth skill).
The session
Author each step as a Kernel script under src/ with the caller's input schema (the
core skill), and keep the flow's calls in a module the composed script will import
too. Run each step with execute purpose act, target liveBrowser.
- The first
actstep claims the build's write. It carries thewritePath(above). The host resets the browser to the site origin page first, with fresh page state that keeps the browser's cookies and site storage (a signed-in build keeps its session), so that step starts the flow there and sets every value its input controls itself. - Later steps continue on the page exactly as the previous step left it. Keep steps
small and read the actual state after each submission. On multi-step forms, a
button named Continue, Next or Save may save a draft, persist that page, or finish
the task immediately; its label does not establish that another review or final
submit follows. A step that saves or advances a form page is part of the task,
not a second write. The composed script runs the steps back to back, without the
pauses you took between them. So prefer ending a step that redraws the page, such
as a filter, a pick or a new table row, with
waitForOutcomenaming the element the next step uses. - When a step waits for the site's answer, wait for every answer the site can give, such
as results, a no-results message or an out-of-area notice, rather than waiting for
results alone. A message about a value the caller gave, such as a field error, is the
caller's input error: throw
InvalidInputnaming the field, with the options the site offers asavailablewhen it lists them. - When the site says no to a valid request, such as sold out, no availability, not
eligible, not offered for these facts or not served in this area, that no is the task's
answer. Prefer returning it as a refusal the output schema declares (below), with a
reasoncode of the tool's own, listed in the tool's description,site_message, the site's own words exactly as the page shows them, and any alternatives the site offers, exactly as shown. Return it only from what the site shows in this run, never from a rule copied into the tool's own checks, and never from a challenge, block, access-denied, error or maintenance page, which is a failure (OperationFailure). After a commit mark, return it only where the declared-refusal rule below says one returned there completes the run; otherwise prefer throwingInvalidInputwith the site's words. - When the site swaps the request for something the caller didn't ask for, such as another product, a later date or a higher amount, stop before the step that would confirm it and return the refusal as above, with the site's words and its offer, unless the caller's own task asks for whatever the site ends up with.
- Report a confirm popup to
decideDialogwith a literalstepname, and keep that literal in the helper the composed script imports. Runs accept a popup without asking only at the step the session accepted it at, so the host refuses to publish a composed script that drops one. - Place a commit mark only on the step that sends the change to the site, such as a
submit, save or confirm control, or a control whose handler sends the caller's change to
the site. Opening a form and typing into its fields change only the page's own state, so
leave them unmarked unless the site's requests show they save the caller's change, such as
an autosave; a lookup, suggestion, validation or analytics request saves nothing. A click
that only opens a checkout or review page is no commit unless that click can itself complete
the purchase. Place the first commit mark at the first step that saves on the site. Mark every such step other
than a hold that expires on its own, including an autosave, a saved form step and a
payment submission whose next screen is unknown. Call
enteringCommit("place-order")right before the execute call that can send that change, and declare the names in order aswrite.commits. Use the same marked helper in the session and the composed script. The marked call does the commit and nothing that can still refuse: it re-reads only what a change since the checks would make wrong and its page shows, such as the total and items they read, and when one moved it returns before clicking and the script throwsOperationFailurenaming the change, such astotal_changed; otherwise it clicks once and waits for the confirmation. That guard is expected. Name the in-between state the site can show after the click, beside its final answers, in that wait'spending: it holds up to 60 s from when that state shows, andconfirmCommitreports one still showing then aspending. An entered mark counts as possibly sent even when its call stopped before the click, so a check that can refuse placed there reports a possible change and sends a write that never happened to maintenance. If the call returns an unexpected page or fails while waiting for an assumed review, read back before another submission: the task may already be complete. The host cannot see a commit sent as a GET link or over a websocket, so the mark is its evidence of whether the commit step ran. - Mark the commit at the step that submits the booking or order; a hold that expires on its own, such as a reserved table or a cart timer, is not the commit.
- When the site's own answer to a commit click proves it created nothing, by a response, read
whole, that names the site's reason for refusing, such as an expired quote, a changed price or
sold out, and returns no record, call
notCommittedfor that step, then end with the site's words, preferably as a declared refusal (below): the run then reports the write not applied. Wait for that answer in the commit call, beside the confirmation. A 5xx, a timeout, a conflict or duplicate answer, or an error inside a returned record is not that proof. A save the site answers with the same form again, still holding the values the step filled, showing its own validation summary or field errors, none of them a conflict or duplicate, and no next page or confirmation, is that proof too, unlessblockingRequiredFieldsreturns fields to ask orunaskable(above): callnotCommittedfor that step with{ siteRefused: true }. Then prefer throwingInvalidInputwith the site's words when it flags one or more fields and every one holds the caller's own value, since the caller can fix it, andOperationFailurewith the site's words otherwise, since the tool filled or left one of them wrong. When the page shows the site's own refusal of that write, or the site answered the commit with an error that is not a server error and a fresh read of the same view you read before the mark shows each field whose sent value differs from that read unchanged, prefer the same put-back and ending as above; never on silence or a missing element. - In a paying commit step, name the site's alert or dialog as an outcome beside the order's response, and return the site's decline as a refusal the output schema declares, with the site's words.
- A quote the site issued earlier, such as a fare, rate, delivery time, cart price or hold, can
expire before the commit, for example while the step waits for review, and selecting it again
can send back the quote the page already holds. So have the commit step go to the checkout
page's URL again, since a reload can resend the form that loaded the page, or start the
checkout again, right before its mark, then select the fresh quote, set again any earlier
choice this may have reset, such as the tip or a declined add-on, and check the quote and those
choices against the caller's limits, such as the cap and the same item or route, before the
mark as above, all in that one step, or right before the card fill when the host fills the card.
There, and in any other re-check before a commit, match the choice the caller approved by its
kind or name and any time it shows that stays fixed, not by a time that moves with the clock,
check the price it shows against the caller's limits as above, and keep it as approved when
only that time changed, even when the page leaves out a value an earlier check read. For a choice whose shown time moves with the clock,
readBackMatchesandsameTextfrompomerado/runtimetake{ ignoreClockTimes: true }to compare its kind or name without its times. When the site answers the click by saying the quote expired or the price changed, with that proof that it created nothing, callnotCommittedfor the step with{ siteRefused: true }, refresh the quote the same way and check it again, then callenteringCommitagain and click once more. A fresh quote that breaks a limit refuses before the mark, so the run reports nothing applied. Retry only once: a step goes back once a run, so a second such answer ends the run with the site's words, returned where the declared-refusal rule below allows a refusal after a mark, else thrown asOperationFailure. Neither answer is about the caller's input, so neither isInvalidInput. - The host refuses an
actstep whose source is unchanged since it ran and sent state-changing requests: submitting it again could commit twice. - Read
stateChangingRequestson every step. It lists the commit your step caused, with each request's response status, and any autosave or draft save. That is the evidence for thehttpversion; any other write is unintended and must not be in the script. - Prefer confirming the write from its commit request. Keep the click on the final commit
control, such as Save, Send, Submit, Book or Pay, in its own step. In the same call as
that click, wait for the site's response to the request it sends, matched by the method
and path the session saw carry the commit on the site, and by its body where the body
shows the caller's values, as
references/write-readback.tsdoes: a{ response }answer ofwaitForOutcomeResult, beside every way the page can answer, listing the site's error or validation message ({ invalid: form }) first. The write went through when that response is 2xx or 3xx, a body the call can read shows no error, and the page shows no error or validation message after it. A 201 whose Location names the new record went through as soon as it arrives, with no wait for the page. A 200 whose body reports an error, as GraphQL can, did not go through. A 202, or a 2xx whose body says the work is queued, went through too; return that in the output as a status in the core notation, such asqueued, with the site's own word in astatus_labelfield. Then read what the output promises from that response or from the page the commit left, match it to the caller's values, and callverified()with no argument just before returning, also when the page shows no confirmation, since that response already confirms the write. Declarewrite: { confirmation: "readback" }. Prefer not opening another page, such as a list, a history or an account screen, only to prove the write: a commit that went through, with the new record's id, already proves it. Return the tool's whole output from the step that confirms the write, read from the commit's response or the page it left: the caller or the site may cancel, refund or delete the record soon after, and a later read-back then shows less. In the same call as the click, read a success message that disappears on its own. When a commit step returned without callingverified()and itsstateChangingRequestslist the commit request with a 2xx or 3xx status, prefer confirming it in the next step from that response, with no error in its body or on the page as it stands, over waiting for a message that may be gone. Make no execute call afterverified(): a later call reopens the effect. After the confirming step, furtheractsteps are refused. - Prefer confirming the final commit with
confirmCommit(answer, page): importconfirmCommitCodefrompomerado/runtime, paste it afterwaitCodein the commit call, once the form is filled and just before the click's wait, and pass it the{ response }answer of that click'swaitForOutcomeResultand the page. It applies the commit-response and page-error rules above in one place, so prefer it over writing your own status and body checks, and callverified()only when it reports done. - Read the site's own proof instead only when the commit request can't confirm the write:
no such request went out; it failed, got no answer or returned an error status; its body
shows an error, or can't be read on an endpoint that reports errors with a 200, such as
GraphQL or a batch call; the page shows an error; the commit went over a websocket or a GET
link; or a later stage the site can still refuse, such as sending what an earlier click
saved, sent no request of its own. Then prefer the confirmation the page shows after the
click: an order, booking or reference number, or a success message or toast that appears
after the click with no error on the page. Open the saved state, such as the orders page,
the booking list or the updated profile, only when the page shows no confirmation. Match
it to the caller's values, return the number or record in the output, and call
verified()as above. A 200 from any other request is not a confirmation. - Only if the site offers none of these, a commit response the call can check, a
confirmation or the saved state, the write is
unverifiable: do not callverified. It publishes flagged, and its runs report the write as possibly completed. A session in which any step recorded a confirmation is neverunverifiable; publish against the confirming step. - After a commit, the site may open a dialog or cover the page, such as an added-to-cart panel.
Prefer confirming the commit from its own response, and prefer waiting with
waitForOutcomefor every answer the site can give to the click, its own added page, panel or cart change included, over waiting only for the page the session saw. Prefer closing such a dialog with its own control (core skill), or going to the address in the site's own link, before clicking anything behind it. - When one run repeats a commit for several items, such as adding items to a cart, prefer
confirming each item from its own commit response and reading the saved state once after the
last item, over reloading the page after every item. When a commit answers a 429, a bot
challenge or another block of that kind, such as the site's bot protection answering 403 or an
access-denied page, prefer stopping before the next commit and returning each item's outcome:
added, refused by the site, or not tried. An item is refused only when the site answered its
own commit request with such a block and nothing got past it, and not tried only when its
commit step never entered; a block cleared afterwards, a timeout or a missing answer is
neither, so read that item back as above. An item its own commit response confirmed stays
added even when the block stops the last read. Never guess an item's outcome or return a
refused or not-tried item as added. Call
verified()only when every item is settled as added, refused or not tried and at least one was added. Otherwise, such as when the block also stops an item's read-back, throwOperationFailurelisting each item's outcome, an unsettled one as unknown, so the run reports a possible change ("What runs do with it"). - When the caller wants several of the same item, prefer setting the quantity in one commit, through the site's quantity field or option, over committing the item once per unit, which suits a site with no quantity control. Each commit is one item in the outcomes above: a quantity set in one commit is one item, and each unit committed on its own is one.
- When a read-back is needed, the first one that matches confirms the write; stop there. It
matches when it shows the written record after the write, found by something the write
produced or entered (its number, its own reference or the values entered). Compare every
field the caller asked for that the view shows (the read before the commit already checked
what you entered), and list each one that differs in
saved_differences("Check the read-back"). Sites reformat what they save, such as line breaks, spaces and dates in the viewer's format, so compare text after the commit withsameText, as before it (the core skill's Confirm step). PreferreadBackMatchesfor a number the caller gave, such as a measurement, an amount or a quantity, since sites save numbers in their own format, such as 1,50 for 1.5. Compare a chosen option's value only where the view shows that value; otherwise compare the label it shows. When the write changed state that already existed, the same read is also the after read of the before-and-after comparison, which runs afterverified()("Check the read-back"). Write each read-back step to compare the requested
…(truncated)