A10 / Practical guides
From a rough idea to an executable task
Turn a short request into scope, context, human and agent briefs, and observable acceptance checks. Follow an illustrative example and copy the readiness checklist.
- 01Prepare the brief
- 02Pair human + agent
- 03Verify the outcome
Consider this illustrative request:
The homepage doesn't explain the workflow clearly. Help a first-time visitor understand what we do.
It names a useful problem. It leaves important choices open: who is the reader, what should they understand, what must remain unchanged and who decides the page is ready?
A longer prompt is not automatically a better task. The goal is to make those choices explicit. This article turns the example into a bounded handoff and ends with a checklist you can copy. It is a teaching example, not a report of a completed homepage change.
Capture first, prepare second
Record the idea and its project when it comes up. Add the discussion, screenshot or file that explains the problem. A spoken explanation can be useful if the team records it through an agreed tool.
A teammate or drafting agent can prepare the first version later. An agent needs access to the relevant notes, files and code; it should list missing information rather than quietly inventing it. The requester then reads and confirms the draft before execution.
1. Outcome: what should become true?
Weak: “Improve the homepage.”
Better: “A first-time signed-out visitor understands that Wagglet helps a team prepare a task, supervise execution with AI tools and accept the result on evidence. They can read the method or sign in.”
This states the reader, the intended understanding and the next action. It does not prescribe a visual style the requester has not chosen.
2. Context: what is authoritative?
Give the executor source links and a short explanation of the decisions that matter. For this example:
- The approved homepage copy and its revision.
- The agreed layout: one hero, a method CTA and a visible Google sign-in action.
- The signed-out route and existing public-page components.
- The destination list and whether each page is actually live.
- Current routing and metadata that must be preserved unless explicitly changed.
Do not assume a linked file is accessible. Ask the drafter to report inaccessible sources and conflicting versions. A short summary helps the executor find the relevant decision; the source lets them verify it.
3. Constraints: what must stay true?
The homepage is public, but signed-in routing is a separate behavior. Say that it must remain unchanged. Require the approved copy and existing components. Keep unrelated public pages and authentication behavior out of scope.
Resolve contradictions before assignment. “Keep the old hero unchanged” and “replace its headline and primary action” cannot both be the instruction for the same element. In this example, the approved scope explicitly replaces the signed-out hero copy while retaining Google sign-in.
4. Human responsibilities: what does the executor own?
The person confirms that the copy and destinations are approved, checks clarity on a real phone and laptop, and returns unresolved product or layout decisions to the requester.
Some agents can inspect browsers and capture screenshots. That does not remove the need to decide who performs each check, whether a real device is needed and who approves the tone or outcome.
Keep the human brief short. Put detailed checks in a separate QA list.
5. Agent instructions: make the handoff executable
I want the signed-out homepage to explain Wagglet's workflow
to first-time visitors using the approved copy attached to this task.
Inspect the existing route and public-page components first.
Replace the signed-out hero copy and add the approved sections
in order. Use one hero, not the old hero plus a second new hero.
Keep a visible Google sign-in action and the method CTA.
Preserve signed-in routing and authentication behavior.
Preserve existing metadata except the explicitly approved title
and description. Use the current component and style system.
Do not edit other public pages.
If a required source is inaccessible or the copy conflicts with
the approved layout, stop and ask me. If a destination is not live,
leave its CTA unpublished and report it; do not invent a working URL.
Run the applicable existing checks and inspect the layout.
Ask me to complete the named real-device and copy checks.
Deliver a new branch, a result summary, evidence and known limits.
Do not merge or deploy.
Human brief
Confirm the approved copy, layout and available link destinations. Check the page on a real phone and laptop, and ask the requester to resolve any change of intent or tone before delivery.
6. Acceptance checks: make the verdict observable
- Signed out, the page shows the approved hero and sections in the agreed order.
- Signed in, the starting route behaves as it did before the change.
- The sign-in action and method CTA are present and usable at the agreed mobile and desktop sizes; no content overlaps or scrolls horizontally.
- Every enabled link reaches its intended live destination; unavailable destinations are listed in the delivery.
- Relevant build and regression checks pass, and the human records the agreed real-device and copy review.
Avoid an incomplete viewport check such as “visible on a 375 px screen” without specifying height or the intended behavior. Use an actual agreed device or complete viewport dimensions when placement relative to the fold matters.
Read the assembled task for contradictions
| Part | What this example now specifies |
|---|---|
| Outcome | A new visitor understands the workflow and can read the method or sign in |
| Context | Approved copy revision, layout, code location and live destination list |
| Scope | Signed-out homepage content and approved metadata changes |
| Constraints | Signed-in routing, authentication and unrelated pages stay unchanged |
| Human role | Confirm source approval, judge clarity and perform named device checks |
| Agent role | Implement within scope, run checks, report evidence and stop at unresolved decisions |
| Acceptance | Observable content, routing, link, layout and validation outcomes |
The agent and human instructions should agree about what can change, when to stop and where the result goes. Read both as a person who was not in the original conversation.
Common failures to catch early
A vague location. Name the page, panel, file or component. “Put it on the right” leaves too much to guess.
An ambiguous term. “Installs by Friday” and “installs on Friday” ask different questions. Define the metric or outcome before execution.
An unstated decision. If the owner must choose between options, make the first deliverable options with a recommendation. Do not instruct the agent to build before that choice.
A missing scope boundary. Say which neighboring work is excluded. A useful improvement can still be an unwanted change in this task.
Too much QA text. Keep checks that demonstrate a real outcome or catch a meaningful regression. Repetition does not make a check stronger.
Copyable readiness checklist
[ ] Intended outcome and reason
[ ] Current behavior and exact locations
[ ] Authoritative sources, versions and access
[ ] Constraints and out-of-scope work
[ ] Ambiguous terms defined
[ ] Unknowns listed and decision owners named
[ ] Agent brief includes its own stop conditions
[ ] Human brief names supervision and judgment
[ ] QA states who checks what and the expected result
[ ] Delivery form and publication authority specified
[ ] Three to five observable acceptance checks
[ ] Both briefs agree
[ ] Requester has confirmed the draft
The useful measure is not the length of the task. It is whether another person can start, make the decisions they are authorized to make and return a result you can judge. After delivery, record where clarification or rework was needed and improve the next brief.