agent rules: first rule "Do it, don't ask" (agents-core and every adapter, README, store-pitfalls lead, first-release, declarations and console skills); the agent runs the real command after the dry run, the owner presses only final public or irreversible buttons and answers compliance facts in one batch; handoff text removed from skills; tests/do-it-dont-ask.test.ts. Pitfall 26

This commit is contained in:
CRTkafa 2026-10-12 09:28:45 +08:00
parent fc524cd2d4
commit dfc28c15f8
22 changed files with 393 additions and 105 deletions

View file

@ -1,6 +1,6 @@
---
name: store-pitfalls
description: Known pitfalls with App Store Connect, Google Play and storebound itself, learned from real releases, and what to do about each - store lists that lag right after a create, dry runs that print a count instead of a plan, App Store names taken on a storefront, keyword limits in bytes, Data safety answers without code evidence, missing font glyphs in screenshots, console sign-in and sessions, Capacitor monorepo plugins, duplicates from retries, re-runs and parallel runs, App Store search ranks that are only a trend, Play without a search API, Play's Create app form (no API, opener and submit share a name, Free is final), App Privacy purposes over-mapped (Play advertising is Third-Party Advertising only), an unknown console page, a signed-in console read as a sign-in page (Google account widget frames), console forms driven agent-first, stale Capacitor web assets, a declined flow step logged ok. Read it before any store task, and when a store command does something you did not expect.
description: Known pitfalls with App Store Connect, Google Play and storebound itself, learned from real releases, and what to do about each - first: do the work, don't ask the owner for every step; store lists that lag right after a create, dry runs that print a count instead of a plan, App Store names taken on a storefront, keyword limits in bytes, Data safety answers without code evidence, missing font glyphs in screenshots, console sign-in and sessions, Capacitor monorepo plugins, duplicates from retries and re-runs, search ranks that are only a trend, no Play search API, Play's Create app form (no API, opener and submit share a name, Free is final), App Privacy purposes over-mapped (Play advertising is Third-Party Advertising only), an unknown console page, a signed-in console read as a sign-in page, console forms driven agent-first, stale Capacitor web assets, a declined flow step logged ok. Read it before any store task, and when a store command does something you did not expect.
---
# Store pitfalls
@ -8,6 +8,14 @@ description: Known pitfalls with App Store Connect, Google Play and storebound i
Each entry: **symptom** → cause → what to do → what guards it now. The full changelog of lessons with dates is
`docs/pitfalls.md` in the storebound repository. When you hit a new one, tell the owner and add it there (and here).
## First: do it, don't ask (the costliest pitfall)
You and storebound do everything: API calls, uploads, builds, CSV / template exports, every console navigation
(open, Get Started, Edit, Next, Continue, Save draft), console forms, verification. Never hand the owner "run this" or
"click X". The owner presses only the final public or irreversible buttons (Submit for review, release or a
production rollout, App Privacy Publish, legal agreements; deleting store data, live prices, review replies,
testers) and answers, in ONE batch at the start, only the facts no file proves (compliance answers that `check` /
`validate` list). Loop: plan, drive, verify, continue. Full rule: `docs/agents-core.md` (AGENTS.md); lesson 26.
## 1. A product you just created is "not there"
- **Symptom:** `apple iap-review` uploads nothing for a product `apple iap` created a minute ago; a list looks short.
- **Cause:** App Store Connect's `/inAppPurchasesV2` list (and Play's product list) can lag for a short while after a
@ -135,7 +143,7 @@ Each entry: **symptom** → cause → what to do → what guards it now. The ful
- **Cause:** the console showed a page storebound does not recognise (a changed layout, a new question): no field it
can fill and no button it may click.
- **Do:** read the warning: it names the page ("the page after "Next""), its buttons, and where the debug dump is.
Do that part by hand (the manual steps follow), or stop. To report it, re-run with `--debug-dump` and attach the
Drive that part yourself with your browser tool from `storebound console plan <form>` (agent-first), then go on. To report it, re-run with `--debug-dump` and attach the
folder `.storebound/console-debug/<form>-<time>/` after the owner looked at `screen.jpg` (the screenshot shows what
the window showed). `page.json` / `page.html` hold labels and structure only: no values, cookies or tokens; emails,
phone numbers and the account area are replaced.
@ -291,8 +299,8 @@ that fails without the fix (see CONTRIBUTING.md).
`apple testflight wait` for a build that was never uploaded.
- **Cause:** a declined confirmation (`confirm()` in `cli/lib/ctx.ts`) returned from the command with exit 0, and
`flow run --yes` was not passed on to the steps, so a run without a terminal could never confirm.
- **Do:** read a step's output, not only its status. For a run without a terminal the owner can approve the writes
with `flow run <name> --apply --yes` (only on their word, per run); otherwise run the flow in a terminal.
- **Do:** read a step's output, not only its status. After showing the dry run, run the writes yourself with
`flow run <name> --apply --yes` (owner steps never run in a flow, they print as "YOUR CLICK").
- **Guard:** every declined or unanswerable confirmation prints `declined: <reason>` and exits 3 (`DECLINED_EXIT`);
`flow run` stops with "step N declined: <reason>" (status `declined`, never `ok`) and adds `--yes` to write steps
only with `--apply --yes` (`planStep` in `cli/lib/flow.ts`, `declinedReason` in `cli/flow.ts`).
@ -315,3 +323,20 @@ that fails without the fix (see CONTRIBUTING.md).
`sendParts` in `cli/apple/upload.ts`, `cli/lib/progress.ts` (injectable heartbeat), `waitForBuild` in
`cli/apple/testflight.ts`, a 2-minute limit per App Store Connect call (`ASC_REQUEST_TIMEOUT_MS`);
`tests/tools-path.test.ts`, `tests/build-sign.test.ts`, `tests/upload-progress.test.ts`.
## 26. Asking the owner for every step
- **Symptom:** an agent using storebound spent hours handing the owner one click, one command or one answer at a
time: "open App content", "press Next", "download the CSV template", "now run the upload", "what is your
answer for X?" in the middle of a run.
- **Cause:** skills and rules said "let the owner do it" and "by hand" for navigation, draft saves, exports and
uploads, and compliance questions were asked when the run reached them, not at the start.
- **Do:** follow the first rule (top of this file, `docs/agents-core.md`): do every API call, upload, build, export,
console navigation and form yourself, verify by reading back, go on. Collect every fact no file proves in one batch
at the start (`storebound check` / `validate` list them) and save the answers in the config. Stop only for the
owner steps (Submit for review, release / production rollout, App Privacy Publish, legal agreements, deleting store
data, live prices, review replies, testers), prepared with the dry run shown. Make `check` / `--dry` catch store
refusals so they never surface as a 400 mid-run.
- **Guard:** the rule is the first section of `docs/agents-core.md` and so of every generated adapter (AGENTS.md,
GEMINI.md, Copilot and Cursor rules), of README and of this skill; `tests/do-it-dont-ask.test.ts` checks that and
fails when a skill or the rules hand navigation, draft saves, exports, uploads or form filling to the owner
(navigation "by hand", uploads or exports left to the owner, asking the owner to click through a form).