opencode-skills-collection 4.1.2 → 4.1.3

package/bundled-skills/idea-to-blueprint/references/edge-case-catalog.md

@@ -0,0 +1,239 @@
+# Edge-case catalog
+
+How to use: for every story, walk each category below and ask the question. If it applies, either reference the global register entry (`EC-<CAT>-nn` in section 15 of the blueprint) with the story-specific expected behaviour, or add a story-level case. Then make sure at least one AC or test covers it. "Not applicable" is a valid answer; "didn't think of it" is not.
+
+Category codes: INPUT · AUTH · DATA · TIME · NET · DEV · CONC · PAY · FILE · MSG · PERM · SEARCH · BIZ · INT · OPS · L10N · SEC · A11Y · IR (Iran-specific) · BOT (messenger bots) · ADMIN
+
+## INPUT — input and validation
+- EC-INPUT-01 Empty / whitespace-only / only ZWNJ or invisible characters → treated as empty; field-level error; no request.
+- EC-INPUT-02 Maximum length reached / exceeded on paste → hard limit enforced client and server; counter shown; truncation policy explicit.
+- EC-INPUT-03 Invisible or control characters pasted (zero-width, RTL marks, tabs) → stripped or rejected before validation.
+- EC-INPUT-04 Emoji, combining marks, unusual scripts in names/text → stored and rendered correctly; length counted in graphemes.
+- EC-INPUT-05 HTML/script/SQL-looking input → escaped on output, parameterised queries; never executed; shown back verbatim as text.
+- EC-INPUT-06 Leading zeros, plus signs, spaces, dashes in numeric identifiers (phone, card, code) → normalised by one shared function; original never stored.
+- EC-INPUT-07 Persian/Arabic-Indic digits in numeric fields → normalised to Latin before validation and storage.
+- EC-INPUT-08 Arabic ي/ك vs Persian ی/ک in text → normalised for storage and search; display as Persian.
+- EC-INPUT-09 Boundary values (0, -1, max int, 1 over the limit, exactly the limit) → explicit expected results.
+- EC-INPUT-10 Duplicate submission of the same content (same title twice) → rule stated: allowed, merged, or rejected with copy.
+- EC-INPUT-11 Autofill/autocorrect altering input (browser filling email into phone) → validation catches, error names the field.
+- EC-INPUT-12 Decimal and thousands separators in money/quantity fields (Persian ٫ ٬ vs , .) → accepted and normalised.
+
+## AUTH — identity, sessions, OTP
+- EC-AUTH-01 OTP wrong code n times → attempt limit, lockout duration, copy with remaining attempts.
+- EC-AUTH-02 Double tap / double submit → single request (button disabled while pending, server idempotency).
+- EC-AUTH-03 Resend before cooldown → blocked client-side; server-enforced; copy shows seconds.
+- EC-AUTH-04 Code expired then entered → specific error, offer new code; old code invalid after new one issued.
+- EC-AUTH-05 Session expires mid-action (in a form, mid-payment) → draft preserved; re-auth then return to the same step.
+- EC-AUTH-06 Same account on two devices → policy: allowed with device list, or single-session with kick-out notice.
+- EC-AUTH-07 Phone number recycled by operator / user changes number → account recovery path and ownership rules.
+- EC-AUTH-08 Deep link opened while logged out → land on login, then continue to the target.
+- EC-AUTH-09 Role or permissions changed while logged in → effective on next request; UI refreshes; no stale privileged actions.
+- EC-AUTH-10 Account deleted then same phone/email signs up → clean new account; old data not resurrected (retention rule).
+- EC-AUTH-11 Brute force on OTP or password → rate limits per number and per IP; monitoring alert.
+- EC-AUTH-12 Sign-in via a channel the user no longer controls (old email) → recovery requires the current primary channel.
+
+## DATA — data and state
+- EC-DATA-01 First use, no data → designed empty state with one action.
+- EC-DATA-02 Exactly one item (no plural, no "others") → copy and layout handle singular.
+- EC-DATA-03 Thousands of items → pagination or virtualisation; response size limit; sort stable.
+- EC-DATA-04 Pagination boundaries (exactly page size, last page, item deleted while paging) → no duplicates/gaps; cursors preferred.
+- EC-DATA-05 Sort ties → deterministic secondary key.
+- EC-DATA-06 Soft-deleted or archived referenced items → how they display in lists, details, exports.
+- EC-DATA-07 Orphaned records after deletion → cascade or restrict policy per relation; tested.
+- EC-DATA-08 Long text in short layouts → truncation with full text on tap; no overflow breaking RTL layout.
+- EC-DATA-09 Migration on live data → backfill plan, reversible, tested against a dump.
+- EC-DATA-10 Very long lists in exports (CSV/Excel) → streaming; Persian text encoding correct (UTF-8 with BOM if Excel is a target — verify).
+- EC-DATA-11 Duplicate detection rules (same phone twice, same product name) → stated per entity.
+- EC-DATA-12 Stale data on screen after another actor changes it → refresh policy; conflict copy.
+
+## TIME — dates, calendars, time zones
+- EC-TIME-01 Jalali month lengths and Esfand leap year → library verified; tests for the current and next two years.
+- EC-TIME-02 Month/year boundaries in reports ("this month" at 23:59 on the last day) → boundaries computed in Asia/Tehran, stored UTC.
+- EC-TIME-03 Week starts Saturday; "this week", weekly reports and pickers follow it.
+- EC-TIME-04 DST policy of the target zone (verify current) → no assumptions; tests around historic transitions if any.
+- EC-TIME-05 Holidays and closed days (official calendar source verified) → scheduling and reminders respect them.
+- EC-TIME-06 Device clock wrong → server time is authoritative for expiries; relative times computed from server timestamps.
+- EC-TIME-07 Relative time wording ("۳ دقیقه پیش" vs absolute after 24 h) → one rule.
+- EC-TIME-08 Cross-year ranges and reports spanning Nowruz → correct year labels.
+- EC-TIME-09 Expiry exactly at boundary (expires_at == now) → inclusive/exclusive stated.
+
+## NET — network and connectivity
+- EC-NET-01 Offline at load → cached read view or explicit offline screen; nothing spinning forever.
+- EC-NET-02 Offline at submit → draft kept locally; clear copy; retry when back or manual retry.
+- EC-NET-03 Request timed out but server completed it → idempotency keys so retry does not duplicate; client reconciles.
+- EC-NET-04 Very slow network (2G-class) → payload budgets; skeletons; timeouts with retry; images lazy and sized.
+- EC-NET-05 Partial upload / interrupted download → resumable or restart with clear copy; no half-written records.
+- EC-NET-06 Server returns 5xx / maintenance → friendly copy, retry, status not blaming the user; error tracked.
+- EC-NET-07 API version mismatch (old client, new server) → graceful message, forced update policy for native apps.
+- EC-NET-08 Captive portal / blocked host (CDN or fonts blocked in the market) → self-hosted assets; no functional dependency on foreign CDNs.
+- EC-NET-09 Retry storms → exponential backoff with jitter; max attempts.
+
+## DEV — devices, browsers, platform
+- EC-DEV-01 Small screens (≤ 360 px) and large text settings (200 %) → no clipped primary actions.
+- EC-DEV-02 Low-memory Android → no huge lists in memory; images downscaled.
+- EC-DEV-03 Browser back/forward and refresh mid-flow → state restored or explicit restart with no data loss.
+- EC-DEV-04 Multiple tabs / app instances → last write wins or conflict notice; session shared correctly.
+- EC-DEV-05 Notification permission denied → in-app fallback; copy explains how to enable later.
+- EC-DEV-06 Dark mode / high contrast OS settings → respected or explicitly forced with reason.
+- EC-DEV-07 Keyboard covering the primary button on mobile → layout scrolls; button reachable.
+- EC-DEV-08 Old browser/webview versions common in the segment (verify) → feature detection, polyfills, or supported-browsers copy.
+- EC-DEV-09 Clipboard and share APIs unavailable → fallback UI.
+- EC-DEV-10 PWA install prompt behaviour differs per browser → tested on the segment's browsers; manual install instructions copy.
+
+## CONC — concurrency and idempotency
+- EC-CONC-01 Two actors edit the same record → optimistic locking (version field) and conflict copy.
+- EC-CONC-02 Double-click on create/pay → idempotency key; one record; UI disables while pending.
+- EC-CONC-03 Race on limited inventory/slots → transactional check-and-decrement; clear "just sold out" copy.
+- EC-CONC-04 Webhook arrives before the local record is committed → retry/queue; eventual consistency handled.
+- EC-CONC-05 Background job runs twice (scheduler overlap) → idempotent jobs; lock or unique key.
+- EC-CONC-06 Ordering of events out of sequence (status updates) → monotonic status machine; ignore stale transitions.
+
+## PAY — payments and money
+- EC-PAY-01 Gateway redirect never returns (user closes browser after paying) → server-side verification via callback/inquiry; order reconciled; receipt on next visit.
+- EC-PAY-02 Callback missing, delayed or duplicated → idempotent handler; inquiry job for pending payments; duplicate callbacks ignored.
+- EC-PAY-03 Amount mismatch between request and callback → payment rejected, flagged, alert; user copy: nothing charged / contact support.
+- EC-PAY-04 Gateway down or rejects merchant → alternative gateway policy or explicit "temporarily unavailable" with retry; order kept pending with expiry.
+- EC-PAY-05 Refunds (full, partial, failed refund) → API availability verified; manual fallback process documented; copy for each state.
+- EC-PAY-06 Currency unit and rounding (Toman vs Rial; no decimals) → one conversion function; tests on boundaries; labels always shown.
+- EC-PAY-07 Expired invoice / price changed since checkout began → re-quote with copy; no silent charge of a new amount.
+- EC-PAY-08 Partial payment / wallet + gateway combinations → state machine explicit.
+- EC-PAY-09 Fee and VAT display rules → who pays fees; shown before confirmation.
+- EC-PAY-10 Receipts and audit trail → immutable record; downloadable; matches the gateway reference ID.
+- EC-PAY-11 Test/sandbox vs production credentials mixed up → startup validation refuses sandbox keys in production.
+- EC-PAY-12 Sanctions or blocked service for the market (foreign gateways/processors) → excluded by decision record; verified at build.
+
+## FILE — files and media
+- EC-FILE-01 Oversized file → client-side pre-check and server limit; copy with the limit.
+- EC-FILE-02 Unsupported or mislabeled type (extension vs magic bytes) → server validates content; rejected with copy.
+- EC-FILE-03 Image orientation (EXIF), HEIC/HEIF from iPhones, very large dimensions → normalised, converted, resized.
+- EC-FILE-04 Persian/Unicode filenames and spaces → stored under generated keys; original name kept for display.
+- EC-FILE-05 Malware or harmful content → scanning policy or restriction of types; never executed/served inline unsafely.
+- EC-FILE-06 Storage quota reached / storage service down → clear copy; upload queued or blocked; no dangling references.
+- EC-FILE-07 Deleting a file referenced elsewhere → reference check or tombstone.
+- EC-FILE-08 Slow upload progress and cancel → progress shown; cancel leaves no partial record.
+
+## MSG — SMS, email, push, in-app messaging
+- EC-MSG-01 Provider accepts but never delivers → resend policy; alternative channel; delivery status if the provider offers it.
+- EC-MSG-02 Wrong or unreachable number → bounce handling; copy asking to check the number.
+- EC-MSG-03 Persian SMS length (Unicode segments) → templates tested against the provider's segment limit; no cut-off codes.
+- EC-MSG-04 Duplicate sends (job retried) → dedupe key per message intent.
+- EC-MSG-05 Quiet hours / night sends → schedule window per persona; urgent exceptions listed.
+- EC-MSG-06 Opt-out / unsubscribe → honoured immediately; transactional vs marketing distinction.
+- EC-MSG-07 Email in spam / not delivered → SPF/DKIM verified in ops; in-app copy of the message.
+- EC-MSG-08 Push token expired or app uninstalled → token cleanup; no error shown to other users.
+- EC-MSG-09 Template placeholders unfilled ("{name}") → render-time validation; test for every template.
+- EC-MSG-10 Rate limits at provider → queue with backoff; alert when backlog grows.
+
+## PERM — permissions, privacy, roles
+- EC-PERM-01 Role × action matrix enforced server-side, not just hidden in UI → tests per role per endpoint.
+- EC-PERM-02 Direct object access by ID (another tenant's record) → 404/403 policy; tests.
+- EC-PERM-03 Admin acting on behalf of a user → audit log entry with actor, target, reason.
+- EC-PERM-04 PII in logs, error tracking, analytics → redaction rule; tests that scan log output.
+- EC-PERM-05 Data export and deletion on request → complete, within stated time; cascades documented.
+- EC-PERM-06 Consent for notifications/analytics → recorded with timestamp; revocable.
+- EC-PERM-07 Retention limits (OTP codes, sessions, logs, backups) → stated and enforced by jobs.
+- EC-PERM-08 Screenshots/previews containing sensitive data (link previews, notification previews) → masked where the platform allows.
+
+## SEARCH — search and lists
+- EC-SEARCH-01 Persian normalisation (ی/ک, ZWNJ vs space, diacritics, Arabic vs Persian forms) → indexed and queried normalised.
+- EC-SEARCH-02 Zero results → copy with suggestion; filters visible; clear-all.
+- EC-SEARCH-03 Typos and partial words → tolerance policy stated (prefix, fuzzy) with limits.
+- EC-SEARCH-04 Numbers searched with Persian digits → normalised.
+- EC-SEARCH-05 Very common query (single letter) → minimum length or debounce; performance bound.
+- EC-SEARCH-06 Results changing while browsing → stable pagination cursors.
+
+## BIZ — business rules and lifecycle
+- EC-BIZ-01 Plan/quota limit reached mid-action → copy before the action when predictable; graceful block otherwise.
+- EC-BIZ-02 Subscription expires mid-session → grace behaviour; read-only vs blocked; copy.
+- EC-BIZ-03 Downgrade with data over the new limit → policy (read-only, archive, delete after notice).
+- EC-BIZ-04 Cancel/return after fulfilment started → state machine; who can do it; copy.
+- EC-BIZ-05 Time-based cutoffs (order before 20:00) → server time, Asia/Tehran, copy shows the deadline.
+- EC-BIZ-06 Price or catalogue changes while a cart/session is open → re-validation at checkout; copy.
+- EC-BIZ-07 Minimums and maximums (order minimum, max quantity) → shown before, enforced server-side.
+- EC-BIZ-08 Multi-tenant boundaries (a restaurant sees only its data) → tenant scoping in every query; tests.
+
+## INT — integrations and third parties
+- EC-INT-01 Service down → fallback per integration card; user copy; degraded mode.
+- EC-INT-02 API changed / deprecated endpoint → version pinned; contract tests against sandbox; alert on schema drift.
+- EC-INT-03 Rate limits → client-side limiter; backoff; queue.
+- EC-INT-04 Sandbox vs production behaviour differences → documented; staging uses sandbox; production smoke checklist.
+- EC-INT-05 Secrets rotation → config reload or restart procedure; no secrets in repo; tests that config loads.
+- EC-INT-06 Service blocked for the market or by sanctions → excluded or re-verified at build (`[VERIFY-AT-BUILD]`).
+- EC-INT-07 Webhook signature invalid or replayed → verify signature and timestamp; reject replays.
+- EC-INT-08 Partial success in batch calls → per-item status handled.
+
+## OPS — operations and deployment
+- EC-OPS-01 Missing or invalid environment variable → app refuses to start with a clear message (fail fast).
+- EC-OPS-02 Migration fails mid-deploy → transactional migrations or documented rollback; deploy aborted; health check fails loudly.
+- EC-OPS-03 Rollback to previous release with a newer schema → backward-compatible migrations for one release.
+- EC-OPS-04 Backups: taken, encrypted, restore tested → restore drill is a story in an ops epic.
+- EC-OPS-05 Disk/log growth → rotation and retention.
+- EC-OPS-06 Alerting on error rate, latency, queue backlog, failed jobs → thresholds stated.
+- EC-OPS-07 Seed data in production by mistake → guarded scripts.
+- EC-OPS-08 Time drift between servers → NTP; tokens tolerate small skew.
+- EC-OPS-09 Health endpoint reports dependencies (DB, cache, provider) → used by the platform.
+
+## L10N — localisation and RTL
+- EC-L10N-01 RTL layout: mirrored icons, logical properties, scroll direction → visual tests on key screens.
+- EC-L10N-02 Mixed-direction strings (Persian + Latin + digits) → bidi isolation; punctuation stays in place.
+- EC-L10N-03 Longer Persian strings → no truncation of primary actions; wrapping rules.
+- EC-L10N-04 Plural forms and counters → Persian pluralisation rules; "۱ مورد" vs "۵ مورد".
+- EC-L10N-05 Digit rendering (Persian vs Latin) consistent per the decision record → tests on every formatted number.
+- EC-L10N-06 Font missing/blocked → self-hosted; fallback stack; ZWNJ renders zero-width.
+- EC-L10N-07 Date/number/currency formatting through one utility → no ad-hoc formatting in components.
+- EC-L10N-08 Untranslated strings leak (English fallback) → test that every key has product-language copy from the copy table.
+
+## SEC — security baseline
+- EC-SEC-01 Injection (SQL, command, template) → parameterised/ORM, no string concatenation; tests.
+- EC-SEC-02 XSS and unsafe HTML → output encoding; CSP; sanitiser for rich text if any.
+- EC-SEC-03 CSRF for cookie-based sessions → tokens or same-site cookies; tests.
+- EC-SEC-04 Broken access control → EC-PERM-01/02 tests per endpoint.
+- EC-SEC-05 Secrets in repo/logs/client bundle → scanning in CI; env only.
+- EC-SEC-06 Dependency vulnerabilities → audit in `check` or CI; policy for updating.
+- EC-SEC-07 Brute force and enumeration (does this phone exist?) → uniform responses and timing where it matters; rate limits.
+- EC-SEC-08 Security headers and TLS → configured at the edge; verified in an ops story.
+- EC-SEC-09 File upload as attack vector → EC-FILE-02/05.
+- EC-SEC-10 Session fixation/hijack → rotate on login; secure cookie flags; short-lived tokens with refresh.
+
+## A11Y — accessibility
+- EC-A11Y-01 Screen reader: labels, roles, announcements for async changes → per screen.
+- EC-A11Y-02 Keyboard-only (web): focus order, trap in dialogs, escape closes → tests.
+- EC-A11Y-03 Colour-only meaning (status by colour) → icon or text as well.
+- EC-A11Y-04 Text scaling 200 % → layout holds.
+- EC-A11Y-05 Motion sensitivity → reduced motion respected.
+- EC-A11Y-06 Timeouts (OTP expiry, session) → warning and extension where feasible.
+- EC-A11Y-07 Error identification → associated with the field, announced.
+
+## IR — Iran-specific (load when users are Iranian; verify each at research and at build)
+- EC-IR-01 Users on VPN → IP geolocation unreliable; never gate features by IP country; language from settings, not IP.
+- EC-IR-02 Mobile prefixes and operators → validation by format (11 digits, 09…) not by a hard-coded operator list; MVNOs exist.
+- EC-IR-03 National ID check digit → validated when collected; copy explains why it is needed; not required unless a business rule demands it.
+- EC-IR-04 Postal code (10 digits) and address structure → fields and validation as the category norm.
+- EC-IR-05 Foreign CDNs, fonts, analytics, maps blocked or slow → self-hosted assets; domestic or self-hosted alternatives; no functional dependency on blocked hosts.
+- EC-IR-06 Payment through licensed gateways only; e-commerce trust seal requirement flagged as OQ → checkout copy and flows match the gateway's redirect/callback model.
+- EC-IR-07 Currency volatility → prices editable quickly by the business persona; no hard-coded prices; historical prices kept on orders.
+- EC-IR-08 Weekend Thursday/Friday and official holidays → scheduling, "next business day" logic, support-hours copy.
+- EC-IR-09 App distribution → PWA install path and/or domestic Android stores; update strategy without Play Services if unavailable.
+- EC-IR-10 Messenger channel availability (Telegram under filtering, domestic messengers) → channel chosen by research; fallback to SMS for critical messages.
+- EC-IR-11 Persian text in SMS → Unicode segment limits; codes never split across segments.
+- EC-IR-12 Hosting reachability → domain, DNS, TLS and hosting reachable without VPN; verified at build.
+- EC-IR-13 Foreign services with sanctions clauses in ToS → excluded or explicitly risk-accepted in a DR.
+- EC-IR-14 Jalali everywhere in UI, UTC in storage → single conversion utility; leap-year tests.
+
+## BOT — messenger bots (when the product is or includes a bot)
+- EC-BOT-01 Unknown command / free text → helpful fallback with the main options; never silent.
+- EC-BOT-02 Message edits/deletes, stickers, voice, forwarded messages → handled or politely declined.
+- EC-BOT-03 Group vs private chat behaviour → explicit policy.
+- EC-BOT-04 Platform rate limits and flood control → queue; backoff.
+- EC-BOT-05 Webhook downtime → missed updates recovered on restart (offset/polling policy).
+- EC-BOT-06 Long conversations and state expiry → state machine with timeouts; "start over" always available.
+- EC-BOT-07 Keyboard buttons with stale state (user taps an old button) → validate state; explain.
+- EC-BOT-08 Blocked bot / user left → cleanup; no repeated failed sends.
+- EC-BOT-09 Multiple languages in one chat → language preference per user.
+
+## ADMIN — back-office
+- EC-ADMIN-01 Bulk actions partially failing → per-row result; nothing silently skipped.
+- EC-ADMIN-02 Destructive admin actions → consequence dialog; audit; undo window where feasible.
+- EC-ADMIN-03 Impersonation / support view → read-only by default; audited.
+- EC-ADMIN-04 Exports with PII → access controlled; logged.
+- EC-ADMIN-05 Filters returning huge result sets → limits; async export.

package/bundled-skills/idea-to-blueprint/references/intake-questions.md

@@ -0,0 +1,105 @@
+# Intake — asking the right questions once
+
+The intake exists for one reason: a hundred-page blueprint built on a wrong assumption about the users, the platform, the money or the constraints is a hundred wasted pages. The intake is *not* an interview; it is one well-prepared batch of questions, each with a default, that the user can answer in two minutes or wave through with "defaults".
+
+## Rules
+
+1. **Warm up before asking.** Run 2–5 searches on the idea first (category name, "<idea> app", "<idea> Iran" if the market looks Iranian, the closest known product). You will ask sharper questions ("closest to Snapp Food's model or to a QR-menu like Menu.ir?") and you will not ask things the market already answers.
+2. **Mine the message first.** Anything stated or clearly implied is not asked again. Language, currency, city, named services, named stack, named platform, named users — all count as answered.
+3. **One batch.** All questions in a single message, grouped under short headers, numbered, each with `(default: …)`. End with one line: "Answer what you like; 'defaults' accepts all the defaults." Where a tappable-options tool exists, put the closed questions in it and the open ones in prose right below.
+4. **Only architecture-, persona- or scope-changing questions.** If the answer would only change a detail you can put in the Assumptions table, don't ask — assume and tag `[ASSUMED]`.
+5. **Size the batch to the idea.** Whole product: 10–15 questions. Feature or internal tool: 3–6. Never more than 15; if you have more, the leftovers become assumptions.
+6. **Defaults must be the choice you would actually make**, not a placeholder. If you would pick phone-OTP login for Iranian consumers, the default says so.
+7. **Ask in the user's language.** Keep each question to one line; put the reason in a half-line only when it isn't obvious.
+
+## Market detection cues (decide the working hypothesis, then confirm)
+
+Iranian users are likely when the message has any of: Persian text, تومان/ریال/IRR, Iranian place names, Iranian services (Snapp, Digikala, Tapsi, Shaparak, Zarinpal, IDPay, Kavenegar, Bale, Eitaa, Rubika, Bazaar, Myket…), `.ir`, Jalali dates (۱۴۰۴/…), کد ملی, "کاربر ایرانی", or a Persian product name. Then the question is a one-line confirmation:
+
+> کاربرهای اصلی داخل ایران هستن؟ (default: بله — RTL، تقویم جلالی، پرداخت داخلی، ورود با شماره موبایل)
+
+Do the same for any other market the message reveals (Arabic → Gulf/MENA?, Turkish → Turkey?, mentions of GDPR → EU?). If nothing reveals a market, ask.
+
+## Question bank
+
+Pick from these groups. Skip any group the message already covers. The defaults shown are the ones to use unless the warm-up research says otherwise.
+
+### A. Product and scope
+- One sentence: what outcome does the user get that they can't get today? (default: your own reading from the message — state it and ask them to correct it)
+- Which of these is in v1, which is later? List 3–6 candidate capabilities you inferred; ask them to strike/mark. (default: the smallest set that delivers the outcome)
+- Platform: web app / PWA / native iOS / native Android / Telegram (or Bale/Eitaa) bot / desktop / CLI / API only / several. (default: whatever the benchmark shows the market uses; for Iranian consumers usually PWA or Android-first web)
+- Is this a standalone product, a feature inside an existing product, or an internal tool? (default: standalone)
+
+### B. Users and market
+- Primary users in one line each — you propose 2–4 based on research; ask them to confirm/rename/remove. (default: your proposal)
+- Market/country and language(s) of the UI. (default: detected market; Persian UI with English fallback if Iranian)
+- B2C, B2B, or B2B2C? Who pays vs who uses? (default: inferred)
+- Device and network reality: low-end Android / poor connectivity / desktop office / mixed. (default: mid-range Android on unstable mobile data for Iranian consumers; desktop Chrome for internal tools)
+- Accessibility requirements beyond a sane baseline (screen readers, low vision, motor)? (default: WCAG AA baseline, no special mandate)
+- Products they admire or want to beat. (default: the benchmark leaders you found)
+
+### C. Business and compliance
+- Monetization: free / one-off / subscription / commission / ads / internal (none). (default: inferred from benchmark; "none" for internal tools)
+- Payments needed in v1? Which gateway, if they have one? (default: yes if money changes hands; Iran → a Shaparak-licensed gateway to be verified in research; abroad → to be verified)
+- Regulated domain (health, finance, minors, personal data at scale)? (default: no; if yes, a Legal/Compliance open question is created, never answered)
+
+### D. Technical constraints
+- Preferred or forbidden languages/frameworks/databases/clouds. (default: none — the stack is chosen by the agentic-engineering criteria)
+- Hosting: inside Iran (which provider?) / foreign VPS / managed cloud / on-prem / don't know. (default: Iranian users → hosting reachable without VPN from Iran, to be verified; otherwise a mainstream managed platform)
+- Existing systems or APIs to integrate (CRM, ERP, Google Workspace, Telegram, existing DB)? (default: none)
+- Login model: phone OTP / email + password / social / SSO / none (single user). (default: phone OTP for Iranian consumers; email for B2B abroad; SSO for internal tools)
+- Data sensitivity and retention needs. (default: personal data present → encryption at rest, PII in logs forbidden, deletion on request)
+- Expected scale in year one (users/day, records, media volume). (default: small — single region, single DB; note the scale ceiling in Non-goals)
+- Offline or real-time requirements? (default: neither)
+
+### E. Design
+- Do you have a design reference (Figma, screenshots, a product to mimic, brand colours/fonts)? (default: none → the skill chooses a minimal, mobile-first direction and names it in the Decision brief)
+- Dark mode required? (default: no in v1 unless the platform norm requires it)
+
+### F. Delivery and document
+- Who builds and with what: solo + Claude Code / solo + Codex / small team / mix. (default: solo with a coding agent)
+- One epic per session is the working model — are sessions short (≈1–2 h) or long (half-day)? This sets epic size. (default: half-day → epics of 3–7 stories)
+- Deadline or milestone (closed beta, public launch, demo)? (default: none — order by dependency and value)
+- Document language: prose in your language + English for stories/AC (default) / all English / all Persian.
+- Test rigour: unit + integration only / plus end-to-end for critical flows / plus performance & security gates. (default: unit + integration everywhere, e2e on the 3–5 critical flows)
+- Deployment target for v1 (staging + prod? CI/CD required?). (default: one staging, one production, CI running `check` on every push)
+
+### G. Content and data
+- Seed content or migration from an existing system? (default: none beyond fixtures)
+- Admin/back-office needs in v1 (manage users, content, refunds)? (default: a minimal admin for whatever the core loop creates)
+
+## After the answers
+
+- Restate each answer as a decision in your notes with `[STATED]`.
+- Each skipped question becomes an `[ASSUMED — <one-clause reason>]` row.
+- Anything the user said that contradicts the warm-up research is *not* silently overruled: note it, and raise it in the Decision brief with the evidence.
+- Do not ask follow-ups unless an answer is self-contradictory or blocks the architecture (e.g., "native iOS only" plus "no Apple developer account"). One follow-up message at most; then move to research.
+
+## Example intake (Persian, whole product, market detected)
+
+```
+چند سوال کوتاه قبل از ریسرچ عمیق — هر کدوم رو خواستی رد کن، «پیش‌فرض» یعنی همه‌ی پیش‌فرض‌ها قبول.
+
+**محصول**
+1. خروجی اصلی برای کاربر رو این‌طور فهمیدم: «…». درسته؟ (پیش‌فرض: بله)
+2. کدوم‌ها توی نسخه‌ی اول باشه؟ الف) … ب) … ج) … د) … (پیش‌فرض: الف، ب، ج)
+3. پلتفرم: PWA وب / اپ اندروید / بات بله‌–تلگرام / همه (پیش‌فرض: PWA موبایل‌محور)
+
+**کاربرها**
+4. کاربرها داخل ایران هستن؟ (پیش‌فرض: بله → RTL، تقویم جلالی، پرداخت داخلی، ورود با شماره موبایل)
+5. دو پرسونای اصلی که پیدا کردم: «…» و «…». پرسونای دیگه‌ای هست؟ (پیش‌فرض: همین دو)
+
+**کسب‌وکار**
+6. مدل درآمد: … (پیش‌فرض: کمیسیون)
+7. درگاه پرداخت مشخصی دارید؟ (پیش‌فرض: یکی از درگاه‌های دارای مجوز شاپرک — در ریسرچ بررسی می‌شه)
+
+**فنی**
+8. زبان/فریم‌ورک/دیتابیس ترجیحی یا ممنوع؟ (پیش‌فرض: هیچ — انتخاب با معیارهای Agentic Engineering)
+9. هاست داخل ایران یا خارج؟ (پیش‌فرض: داخل ایران / قابل‌دسترس بدون VPN)
+10. سیستم موجودی هست که باید وصل بشیم؟ (پیش‌فرض: خیر)
+
+**دیزاین و تحویل**
+11. رفرنس دیزاین (فیگما، اسکرین‌شات، محصول نمونه)؟ (پیش‌فرض: هیچ → خودم مینیمال و موبایل‌فرست انتخاب می‌کنم)
+12. هر سشن Claude Code/Codex چقدر طول می‌کشه؟ کوتاه (۱–۲ ساعت) یا نیم‌روز؟ (پیش‌فرض: نیم‌روز → اپیک‌های ۳–۷ استوری)
+13. زبان سند: نثر فارسی + استوری/AC انگلیسی (پیش‌فرض) / همه انگلیسی / همه فارسی
+```

package/bundled-skills/idea-to-blueprint/references/research-protocol.md

@@ -0,0 +1,196 @@
+# Deep research protocol
+
+Contents: 1 Setup · 2 Evidence tagging · 3 Source tiers · 4 Track A understand · 5 Track B benchmark · 6 Track C architecture drivers and shape · 7 Track D stack for agentic engineering · 8 Track E quality bar and tooling · 9 Track F integrations & locale · 10 Track G UX benchmarks · 11 When research fails · 12 Research summary format · 13 Iran verification list
+
+Run the tracks in order. C before D is not cosmetic: the shape of the system constrains which technologies can serve it, and choosing the technology first means the architecture gets reverse-engineered to fit a decision that was never tested against the product's requirements. D before E for the same reason — the quality tooling that exists depends on the language you picked.
+
+## 1. Setup
+
+- Confirm web search and page-fetch tools exist. Without them, stop and tell the user (see SKILL.md, Phase 1).
+- Start a **source log** immediately: `S-01 | title | URL | accessed YYYY-MM-DD | what it supports`. Append as you go. The Sources section of the blueprint is this log, cleaned. Reconstructing sources afterwards is how fabricated citations happen.
+- Budget: breadth first (short queries, 1–4 words, scan many results), then depth (fetch the 10–20 pages that matter: official docs, changelogs, pricing pages, store listings). A whole product typically needs 20–60 searches and 10–25 fetches; a feature needs a third of that. Stop a track when new searches stop changing decisions.
+- Use the current year in queries about "latest", "current", "best" — stale year terms return stale pages.
+- Read pages, don't trust snippets. A snippet that says "v3 recommended" may sit above a banner saying the project is archived.
+
+## 2. Evidence tagging (used everywhere in the blueprint)
+
+| Tag | Meaning | Example |
+|---|---|---|
+| `[VERIFIED — S-07, 2026-09-05]` | You read a primary or strong secondary source that states it | "Framework X current stable is 15.2 [VERIFIED — S-07, 2026-09-05]" |
+| `[STATED]` | The user said it | "Users are Tehran restaurants [STATED]" |
+| `[ASSUMED — reason]` | Your choice where nothing was stated or found; reason in one clause | "Single currency (Toman) [ASSUMED — all benchmarked local competitors price in Toman]" |
+| `[UNKNOWN → OQ-04]` | Could not verify; routed to Open Questions with an owner | "Whether gateway Y supports refunds via API [UNKNOWN → OQ-04]" |
+| `[VERIFY-AT-BUILD]` | True now but volatile (service availability, sanctions, prices); the building session must re-check | "SMS provider Z reachable from EU hosting [VERIFIED — S-12, 2026-09-05] [VERIFY-AT-BUILD]" |
+| `[UNVERIFIED]` | Only when web tools were unavailable for the whole run: a claim from memory that could not be checked. The cover carries a warning and the first build session re-verifies every such tag | "ORM X supports composite keys [UNVERIFIED]" |
+
+Rules: every version number, every "X supports Y", every competitor claim, every market or price figure, every "available in Iran" carries one of these. Numbers with no source are not written. A claim you *remember* but did not read this session is `[ASSUMED]` at best.
+
+## 3. Source tiers
+
+1. Official documentation, changelogs, release pages, standards bodies, regulators, the vendor's own pricing/status pages.
+2. Primary product pages and store listings of competitors (for what they do and charge), GitHub repos (for activity, license, archived status).
+3. Reputable independent reports and well-known technical publications — corroborate with a tier-1 source when the claim drives a decision.
+4. Reviews, forums, app-store comments — only for *user pain and expectations*, paraphrased, never quoted, never as fact about features.
+5. Blogs and listicles — leads only; never cite as the sole support for a decision.
+
+Prefer the newest tier-1 source. When sources conflict, record both and pick with a stated reason.
+
+## 4. Track A — Understand the idea
+
+Goal: describe the problem space better than the user did, in their vocabulary and the market's.
+
+- Domain concepts and terms → start the **Glossary** (term, plain definition, Persian/English equivalents when bilingual, notes on ambiguity).
+- How the job is done today without this product (manual, spreadsheets, competitor, workaround). This becomes the "today vs with product" framing in the executive summary and the personas' current pains.
+- Adjacent regulation or platform policy that shapes scope (payments licensing, data protection, app-store rules, messaging platform bot policies, content rules). Flag as Open Questions for a professional; never write legal conclusions.
+- Analogous products in other domains whose flows solve the same shape of problem (a queue-ticketing pattern, a two-sided marketplace pattern). Note the pattern, not the brand, unless benchmarking it.
+- Outcome definition: write the single sentence "After using this, <persona> can <outcome> in <time/effort> instead of <today>". Every goal and metric derives from it.
+
+## 5. Track B — Benchmark
+
+Goal: know who exists, what the best of them do per flow, where they fail, and where this product wins.
+
+1. **Identify 5–10 players**: direct competitors, indirect substitutes (including "spreadsheet + WhatsApp"), and 1–2 best-in-class products from adjacent categories. For an Iranian market include local players found via Persian queries; global players still matter as UX references even if unavailable locally.
+2. **Feature matrix** (Competitor × capability): ✔ / partial / ✘ / unknown, each cell traceable to a source. Only capabilities relevant to the idea's outcome.
+3. **Per-competitor card**: what it is; platforms; pricing model (figures only if sourced); onboarding shape; the 2–3 things it does best; the 2–3 recurring complaints (paraphrased from reviews, tier 4); what we adopt, what we avoid.
+4. **Best-in-class per key flow**: for each core flow of *our* product (e.g., onboarding, first-order, payment, recovery), name which benchmarked product handles it best and what exactly they do (steps, defaults, copy behaviour). This feeds the flows and UX writing sections directly.
+5. **Gap and positioning**: one paragraph — the unmet need or under-served persona, and the positioning statement: "For <persona> who <need>, <product> is a <category> that <benefit>, unlike <alternative> which <limitation>."
+6. **What not to copy**: anti-patterns observed (dark patterns, 6-screen tours, mandatory sign-up before value) with one line why.
+
+Never quote review text or marketing copy; describe it. Keep pricing figures to what a pricing page states, with the date.
+
+## 6. Track C — Architecture drivers and shape
+
+Full procedure in `architecture-decisions.md`; read it before starting this track. What the research phase owes it:
+
+1. **Drivers, not adjectives.** Derive 5–8 ranked architecture drivers `AD-n` with measurable targets from the personas, the stated scale ceiling, the failure cost of the core loop, the regulatory flags and the hosting reality. Then write the explicit non-drivers. A driver without a number is not a driver.
+2. **Shape before technology.** Score 2–3 candidate architecture styles against those drivers. Record the scoring table; it becomes a DR. The default for this skill's output is a modular monolith with enforced boundaries — but "default" means it must still be argued against the drivers and given explicit exit triggers, not asserted.
+3. **Verify the architectural claims you rely on.** The framework's officially recommended project structure; whether the data-access layer supports the relation shape your model needs; whether the chosen runtime can do the concurrency model you assumed; whether the host supports the deploy unit you chose. Read the docs page, tag it.
+4. **Verify fitness-function tooling** for the candidate languages — a maintained architecture-testing library, or the lint mechanism that stands in for one. This determines whether boundaries can be enforced or only described, which is a real input to the style decision.
+5. **Category-specific architectural requirements** — payment callback and reconciliation models, webhook vs polling for messaging platforms, audit-trail requirements, anything the domain forces on the shape.
+6. **Any "most teams" or "industry standard" claim** the blueprint will make about architecture gets a source and a year, or gets cut.
+
+Output of this track: the ranked drivers, the scoring table, the style decision with exit triggers, the module map, the cross-cutting decision list from `architecture-decisions.md` §7 walked and answered, and the fitness-function list.
+
+## 7. Track D — Stack for agentic engineering
+
+The stack is chosen for one reader: a coding agent working alone in a fresh session, who must produce correct code with no one watching. That changes the usual criteria. Score candidates against the weighted table below **and** against the architecture drivers from Track C — a stack that wins generically but cannot meet a rank-1 driver loses.
+
+### Weighted criteria (score each candidate stack 0–3 per row; weights in brackets)
+
+| Criterion | Why it matters for an agent | Weight |
+|---|---|---|
+| Mainstream adoption + volume of high-quality documentation and examples | More training data and more current docs → fewer invented APIs | 5 |
+| Strict static typing available and enforceable (compiler/typechecker in `check`) | Catches an agent's wrong assumptions before runtime | 5 |
+| One-command deterministic quality gate (`check` = format + lint + typecheck + tests) with fast feedback (< 2 min for unit) | The session protocol depends on a green/red signal the agent can't argue with | 5 |
+| Mature, standard testing tooling (unit, integration, e2e) with good error output | Acceptance criteria must be provable | 4 |
+| Convention-heavy framework (file structure, routing, data layer conventions) | Fewer free choices → fewer inconsistencies across sessions | 4 |
+| Stable/LTS release, low churn, clear deprecation policy | A version pinned today still has docs in six months | 4 |
+| Small dependency surface; batteries included | Every extra package is another thing to hallucinate about | 3 |
+| Fits the market's hosting reality (self-hostable, no dependence on services blocked or sanctioned for the target country) | A stack that can't deploy is a stack that doesn't ship | 4 (5 for Iran) |
+| Native or first-class i18n/RTL/locale support where needed | Retrofitting RTL is a whole epic | 3 (5 for RTL markets) |
+| Permissive license compatible with the business | Legal blocker | 3 |
+| Team familiarity (if a team exists) | Review capacity | 2 |
+
+### Process
+
+1. From the platform decision (web/PWA/mobile/bot/CLI), list 2–4 realistic candidate stacks (language + framework + ORM/DB + test tools + UI layer).
+2. For every component of every candidate, verify **this session**: current stable version and release date, LTS/maintenance status, not archived/deprecated, license, RTL/i18n support if needed, and the exact install/init command from official docs. Tag each `[VERIFIED — S-nn, date]`.
+3. Score the matrix, pick, and write the **decision record**: chosen stack with pinned versions; the runner-up and why it lost; explicitly **forbidden choices** with reason (e.g., "no ORM X — archived [VERIFIED]", "no service Y — requires foreign card / blocked for Iranian IPs [VERIFIED] [VERIFY-AT-BUILD]").
+4. Define the **agentic engineering conventions** that go into the blueprint and Epic 0: repo layout, `check` command and what it runs, formatter and linter configs (strict), typechecker strictness flags, test layout and naming, fixtures/factories, environment variables and `.env.example`, secrets handling, commit message convention (`type(scope): message [E03-S02]`), branch strategy (trunk + short-lived epic branches), CI running `check` on push, migration policy, logging/observability baseline, error-handling conventions (typed errors, no swallowed exceptions), API contract format (OpenAPI/JSON schema) as a source of truth for both sides.
+5. Verify the **hosting and deployment** path end to end: platform/provider, build command, runtime version, database hosting, object storage, domain/TLS, backups. For Iran see §13.
+
+### Heuristics (not rules — verify every time)
+
+- Strongly typed mainstream languages with huge ecosystems and strict modes tend to win for agents; dynamic languages without type checking tend to lose points on row 2 even when adoption is high.
+- Prefer the framework's "blessed" path over clever architecture; agents do best where the docs have one recommended way.
+- Prefer a relational database with migrations over schemaless stores unless the data model truly demands otherwise; schema is executable documentation.
+- Prefer boring, stable UI component libraries with documented RTL behaviour over visually impressive ones with thin docs.
+- Prefer a monorepo with one `check` over multiple repos for a solo builder.
+
+## 8. Track E — Quality bar and tooling
+
+Full procedure in `code-quality-and-review.md`; read it before starting this track. The purpose is to make the quality gate real rather than aspirational: an agent cannot run a `check` command built from a library that does not exist for its language.
+
+Verify, for the stack chosen in Track D, each with version and maintenance status:
+
+1. **The gate components** — formatter, linter and the community-standard strict rule set, typechecker and its strict flags, test runner, coverage tool, mutation-testing tool (does a maintained one exist for this language, or not?), SAST/dependency audit, secret scanning, duplication detector, accessibility checker, architecture-rule library. Get the exact commands from official docs, not from memory.
+2. **The official style guide** for the language and framework, so conventions are cited rather than invented.
+3. **CI reality on the chosen host** — runners, cache, secret storage, required-check/branch-protection capability, and what the plan the user can actually buy includes.
+4. **The security baseline for the category** — the current OWASP Top 10 (or API/mobile equivalent), plus anything the domain adds (payments, health, minors, personal data).
+5. **Current delivery-metric definitions** if the blueprint will name any — the present DORA formulation and its performance bands. The framework has changed more than once; do not quote a version from memory.
+6. **Current evidence on AI-authored code quality** if the blueprint will assert anything about it (security pass rates, duplication and churn trends, review-bottleneck findings). State the figure with its year and source, or state none. These numbers move every few months and a stale one in a rationale is worse than no number.
+
+Output of this track: the concrete `check` command with its components and expected runtime, the test-quality rules, the named critical e2e paths, and the metric table with definitions and data sources.
+
+## 9. Track F — Integrations and locale realities
+
+For every external dependency the product needs (payment gateway, SMS/OTP, email delivery, maps, push notifications, object storage, CDN, app stores, messenger bot APIs, analytics, error tracking), verify:
+
+- Exists and is active today; official docs URL; pricing model (state figures only if on a pricing page, with date).
+- Reachability from the target market and from the chosen hosting (blocked? needs foreign card? sanctions clause in ToS? requires local company registration?).
+- Sandbox/test mode availability — the acceptance criteria will require testable integrations.
+- Webhook/callback model, idempotency guarantees, rate limits, error codes — these become edge cases and AC.
+- Fallback: what the product does when the service is down (queued, degraded, blocked).
+
+Record each as an **Integration card**: name, purpose, docs `S-nn`, status `[VERIFIED …] [VERIFY-AT-BUILD]`, sandbox yes/no, fallback, owner of credentials (OQ if unknown).
+
+## 10. Track G — UX benchmarks
+
+From the benchmarked products and 2–3 best-in-class references: how they onboard (steps to first value), how they handle empty states, errors and recovery, how they confirm destructive actions, how they do phone/OTP login (for Iran), how they present prices/dates, and what accessibility features are standard. Capture as short observations tied to sources; they justify the flow and copy decisions ("we adopt A's 2-step onboarding because…"). Also check the current accessibility standard version and level to reference (verify).
+
+## 11. When research fails
+
+- Nothing found → `[UNKNOWN → OQ-nn]` with a proposed owner (user / vendor / legal / design) and a proposed default the build session may use if unanswered, clearly marked as such.
+- Conflicting sources → record both, decide, state why; add `[VERIFY-AT-BUILD]` if the conflict is about volatile facts.
+- Volatile facts (availability, sanctions, prices, app-store policy) → always `[VERIFY-AT-BUILD]` in addition to the verification tag; the session protocol makes the building agent re-check these before relying on them.
+- Never "fill in" a plausible library, endpoint or parameter name. If the docs page that lists it was not read, it is not in the document.
+
+## 12. Research summary format (feeds the Decision brief)
+
+```
+### Research summary
+Outcome sentence: …
+Glossary seeds: term → definition (5–15)
+Today's alternatives: …
+Benchmark: <n> players; leaders: …; gap: …; positioning: …
+Best-in-class per flow: onboarding → …; core loop → …; payment → …; recovery → …
+Architecture drivers (ranked, with targets): AD-1 …, AD-2 …; non-drivers: …
+Architecture shape: … (score x/y vs runner-up …); exit triggers: …; modules: …; fitness functions: …
+Stack decision: … (score x/y vs runner-up …); forbidden: …
+Quality gate: check = …; expected runtime …; mutation tool: yes/no; metrics instrumented: …
+Integrations: gateway → …; SMS → …; email → …; hosting → …
+Locale realities: …
+UX benchmarks: …
+Open questions found: OQ-01 …, OQ-02 …
+Sources so far: S-01 … S-nn
+```
+
+## 13. Iran verification list (load when users are Iranian)
+
+Each item below is a *thing to verify this session*, not a fact. Availability, licensing and blocking change frequently; the tag on each must include the date and `[VERIFY-AT-BUILD]`.
+
+**Money**
+- Which payment gateways currently hold a Shaparak (شاپرک) licence / operate as licensed PSP aggregators; sandbox availability; refund API; callback model; fee structure; whether a company registration or personal ID is needed to open a merchant account.
+- Currency display convention in the category (Toman vs Rial), rounding, and how competitors label it.
+- Wallet/credit patterns common in the category.
+
+**Identity and messaging**
+- SMS/OTP providers currently operating (service SMS lines, template pre-approval requirements, delivery to all operators, blacklist behaviour, cost per message, Unicode segment length limits for Persian text).
+- Mobile number formats and operator prefixes; national ID (کد ملی) check-digit validation if identity is needed; postal code format; address structure norms.
+- Which messengers matter for bots/notifications in the target segment (domestic messengers vs Telegram/WhatsApp under filtering) and the current status of each bot API.
+
+**Hosting and reach**
+- Iranian cloud/VPS providers and their offerings (managed DB, object storage, CDN), or foreign hosts reachable from Iran without VPN; DNS/TLS providers reachable; whether the chosen hosting can pay for/reach the chosen services.
+- Foreign services commonly blocked for Iranian IPs or requiring foreign cards (fonts CDNs, analytics, maps, package registries mirrors, container registries, error tracking, email delivery) — and the domestic or self-hosted alternative for each one you need.
+- Sanctions clauses in ToS of any foreign service you still depend on.
+
+**Distribution**
+- App-store reality: domestic Android stores (which are active, their publishing requirements), whether Google Play / Apple App Store publishing is feasible for the user, PWA installability on common Iranian Android browsers.
+- Common device/browser mix in the segment if any recent local data exists (otherwise `[ASSUMED]` mid-range Android).
+
+**Calendar, time, language**
+- Time zone (Asia/Tehran) and current DST policy; official holiday calendar source; work week (Saturday–Wednesday full, Thursday half or off in many sectors — verify for the segment); Jalali calendar library options in the chosen stack (maintained, correct leap-year handling).
+- Persian typography: a well-maintained open Persian web font (license, weights, self-host files) and the number-glyph behaviour; whether the chosen UI library documents RTL.
+
+**Legal/regulatory to flag (never answer)**
+- E-commerce trust seal (e-namad) requirements for taking online payments; personal-data and consumer-protection rules applicable to the category; content licensing for any media; VAT/invoicing rules for the business model.