Writing a good ask

After this page you'll write asks that end in a pull request worth reviewing, not a stalled run or a wrong guess. The quality of the ask is the single biggest lever you have. The contract is "No human writes code. A human always reviews", and a good ask is how you make the reviewing part cheap.

One repo, one concrete outcome

Every run works in one repo and ships toward one deliverable, usually one PR. The swarm agent can plan work across repos, but only when the change genuinely can't land in one (an iOS change that needs a new backend endpoint); it is told not to split single-repo work to look thorough. If your ask bundles three unrelated outcomes, split it into three asks; each gets its own run, its own PR, and its own reviewer attention.

Name the repo, but don't sweat the exact spelling. An explicit repo:org/name token always wins, and it's the clearest signal you can give; a shorthand name like firstaid-ios is matched against the project catalog too, and in a DM your pinned project fills in the default. If nothing resolves, you get a clarifying question ("which project?") rather than an error, so the worst case for a vague repo hint is one round-trip.

Say how you'll know it worked

For bugs, give the reproduction and the expected vs actual behaviour. For changes, give an acceptance criterion the bee can check. Its SHIP phase runs lint and tests before opening the PR, so a check it can execute is worth more than an adjective. A bug ask without a reproduction sends the bee investigating from a one-liner; it may return NO_ROOT_CAUSE_FOUND instead of a PR.

Point at what you already know

Name files, routes, and error messages when you have them. Include the Jira ticket key: the swarm agent fetches the full ticket body during planning when a key is in the ask, so it plans from the real ticket, not your summary. From the dashboard you can attach a screenshot, PDF spec, or log excerpt as input context. Scope drift is a known failure mode, and naming specific files or directories is the documented mitigation.

Right-size it

Each phase of a run has an action budget (how Swarm thinks has the numbers). A vague-huge ask burns the whole budget exploring and ships nothing; a bounded slice finishes. The team principle applies to asks too: a PR with 5 fixes and a clear report beats 20 fixes that never land. If the work would take an engineer more than a day, carve off the first slice.

Name a bee, or let routing decide

By default, don't name one. The request goes to the swarm agent, which plans the work and can ask you a clarifying question. Name a bee (support-bee, a11y-bee, tinfoil-bee, cleaner-bee in a Slack mention) only when the job matches that recipe's exact shape, because a recipe follows its fixed playbook and won't pause to check your intent. A typo in a bee name isn't an error; it falls through to the swarm agent. On an unnamed ask, add /plan to review the plan before any code runs; the run stops after planning and your next reply continues it (named-bee runs skip planning, so /plan has no effect there).

Before and after

Vague scope → bounded scope

@cube-agent repo:3sidedcube/3sc-website make the site more accessible

@cube-agent repo:3sidedcube/3sc-website a11y-bee Audit homepage accessibility only. Do not touch other pages

Symptom → reproduction with expected behaviour

@cube-agent repo:3sidedcube/some-api signup is broken for some users

@cube-agent repo:3sidedcube/some-api POST /api/users returns 422 when the email contains a + character. Expected: 201.

Bundle → one outcome (send the others separately)

@cube-agent repo:3sidedcube/some-api fix the login bug, bump the deps, and tidy the error handling

@cube-agent repo:3sidedcube/some-api Login returns 500 on cold start; logs show TypeError: Cannot read properties of undefined (reading 'status') in the /api/health handler. Fix and add a regression test.

No pointers → pointers

@cube-agent repo:3sidedcube/some-api the tests are flaky

@cube-agent repo:3sidedcube/some-api The session-refresh test in src/auth/__tests__/session.test.ts fails intermittently on CI with a timeout. Make it deterministic; the rest of the suite must stay green.

Whole-system rewrite → first slice with a checkable outcome

@cube-agent repo:3sidedcube/some-api migrate everything to TypeScript

@cube-agent repo:3sidedcube/some-api Convert src/lib/dates.js to TypeScript with exported types. tsc and the existing test suite must pass. Touch nothing outside src/lib/.

When you get a question instead of a PR

A too-ambiguous ask doesn't fail silently. The swarm agent is instructed not to invent a plan to paper over ambiguity, so it pauses and asks you in the thread, and your answer resumes the same run. That round-trip is the real cost of a thin ask. And an honest non-PR ending is a feature, not a bug: verdicts like NO_PR_OPENED or NO_ISSUES_FOUND tell you why nothing shipped. See how Swarm thinks for the full lifecycle.