Behavioral conventions for this author's own shopping/classifieds automation family —
olx-polite-mcp and its siblings, which exist on this author's machine and nowhere else — distinct
from mcp-server-shipping (dev-loop/distribution mechanics for the same repos) and from whatever
always-loaded instructions file the machine carries, which holds the truly universal conventions.
These are specific to the domain: automation against a user's own live, logged-in personal accounts.
Installed elsewhere, the conventions still read; the repo names are the author's.
Confirm before the first live mutating action
Before performing the first real mutating browser action against the user's live, personal,
logged-in account in a session (e.g. a real add-to-cart click, not a dry read), stop and ask via
AskUserQuestion rather than just doing it — even when the action is narrowly scoped, low-cost, and
reversible. Frame it as a one-off scoped test (what will run, and that it'll be undone/reverted
afterward if applicable), not a generic permission request. Once approved and the shape/behavior is
confirmed, subsequent same-kind actions in the same session don't need re-confirming.
Why: this family already treats checkout/personal-account actions as a materially higher-stakes
category than plain reads — every repo's own boundary docs say so (e.g. "checkout is never
automated," no-CAPTCHA-solving). A first live mutation test against a real account fits that same
category even when the specific action itself is small. Confirmed live in freshful-polite-mcp
(2026-08-14): asking before the first add-to-cart test got a clean, low-friction "yes, test on one
cheap item" — the right default, not overcaution.
Batch interactive per-item decisions, don't ask for a typed list
When a workflow needs several small independent decisions from the user (e.g. "how many of each of
these 8 items do you want?"), use AskUserQuestion in batches of roughly 4, with a recommended
default pre-filled as the first option — don't present a big list and ask the user to type out
answers for all of them in one reply.
Why: explicit feedback during a Freshful reorder-flow session — "suggest some quantities for all those things, and ask me one by one, it needs to be interactive, if i have to type all that stuff out it kills the ux." Typing a long structured reply is worse UX than a short guided Q&A, even though both convey the same information.
How to apply: reserve a single free-text ask for decisions that aren't decomposable this way, or where there are too many items for batching to stay lightweight — at that point, consider whether the flow itself needs restructuring (e.g. splitting "items likely due" from "rarely-touched items" rather than batching everything flat).
Write spike/research findings into PLAN.md before or alongside implementing
When a research/spike phase (live CDP exploration, API probing, DOM inspection) turns up findings
that change or confirm the plan, write them into the repo's PLAN.md first — as their own section,
matching the doc's existing narrative style — before or alongside writing the actual implementation
code. Don't just carry findings in conversation and go straight to code.
Why: explicit instruction, freshful-polite-mcp (2026-08-14): "it's good to keep everything in
the plan, then implement." Matches the existing pattern across this repo family, where PLAN.md (a
single monolithic file — this family predates the plans/YYYY-MM-DD-topic.md convention documented
in the plan-docs skill, and hasn't been migrated onto it) is the durable record of why the
architecture looks the way it does; code comments point back to it rather than re-explaining.
How to apply: after any live-spike/research pass in one of these repos, update PLAN.md's
relevant section(s) — mark resolved open questions, add a dated findings section, restate/extend any
boundary decisions the findings touch — before moving on to implementation. Do this even when the
user hasn't explicitly asked for the write-up that round; treat it as the default sequencing.