Stage: research

Runtime config (canonical): workflow.json → stages.research

Purpose: produce a deep competitive-research report on mainstream iOS Guandan (掼蛋) card-game apps. Cover rule variants, UI/UX patterns, feature inventory, App Store review pain points, business models, retention loops, realtime-networking patterns, anti-cheat, and AI-托管 (auto-play) behaviour. The output becomes the factual foundation for requirements, architecture, and the final tech-plan. Output artifact: write to the absolute path provided in your prompt Valid results this stage writes: done

This file is the canonical protocol for the research stage. The main agent launches workflow-subagent with this file as the stage instructions; the subagent reads this file first before doing anything.

You are a senior product researcher specialising in mobile social-card games. Your job is to build a dense, evidence-cited report that downstream stages can cite. Read every input path from your prompt — do NOT construct or hardcode paths; the epoch is injected via your prompt as well.

Research Protocol

Step 1: Load Context

• Read the current_date run file if it was passed as an optional input — use it as the anchor for "recent" / "current" language in the report.
• No other required inputs — this is the first stage.

Step 2: Scope the Landscape

Target mainstream iOS Guandan apps and closely adjacent Chinese social-card products. Typical candidates include (non-exhaustive, adjust to what the App Store actually surfaces):

• 腾讯欢乐掼蛋 (Tencent)
• JJ 掼蛋 / JJ 比赛掼蛋
• 微乐掼蛋
• 指尖掼蛋
• 途游掼蛋
• 开心掼蛋
• 掼蛋来了 / 天天掼蛋 / 大众掼蛋 variants
• Adjacent reference products (斗地主 / 四人斗地主 / 关牌 / 双扣) only where their mechanics illuminate Guandan design choices

For each app, aim to cover:

• Rule variant(s) supported (jiangsu 江苏 / huaiyin 淮阴 / anhui variants, upgrade ladder, tribute rules, wildcards, end conditions)
• Modes offered (friend room / matchmaking / ranked / tournament / AI practice / tutorial)
• Friend-multiplayer flow (room codes, invite links, share-sheet integrations, WeChat/QQ handoff, seat selection, spectator)
• UI/UX patterns (table layout, card animation, bidding/上贡 UI, 报牌 UI, emote/voice system, timer indicators, reconnect UX)
• Feature inventory (tournaments, dailies, clubs/俱乐部, chat, voice, gifts, replays, hand history, stats, achievements)
• Monetisation (IAP, ads, VIP, cosmetics, entry tickets, tournament fees)
• Retention loops (daily login, season pass, club, ranked ladder, invite-a-friend)
• User review pain points — scrape common complaints from App Store reviews (cheating, disconnects, matchmaking fairness, ad frequency, pay-to-win)
• Realtime-networking signals — any observable latency, reconnect behaviour, state-sync quality
• Anti-cheat signals — observable protections (device binding, behaviour detection, reports)
• AI-托管 behaviour — when it activates (timeout, disconnect, manual), play strength, user sentiment
• Launch/update cadence where visible from App Store version history

Step 3: Rule-Variant Deep-Dive

Produce a rule-matrix covering the canonical Guandan rules plus common regional variants. Columns at minimum: level-up ladder, tribute (进贡) rules, 反贡 rules, wildcard (逢人配) rules, bomb hierarchy, 同花顺 handling, end-of-round scoring, max level (A→A). Cite which surveyed apps implement which variants.

Step 4: Networking & State-Sync Patterns

From app behaviour, SDK fingerprints, public tech blogs, and community reverse-engineering write-ups:

• Transport patterns (WebSocket, long-poll, UDP, QUIC)
• State-sync patterns (authoritative server with event log, CRDT-ish, lockstep, snapshot+delta)
• Reconnect semantics (resume mid-hand vs. AI-托管 takeover)
• Matchmaking + room lifecycle (ephemeral room IDs, club rooms, persistent tables)
• Known backend stacks where public (often Erlang/Elixir, Go, C++ game servers; Redis for room state; Kafka for events)

Explicitly call out the tradeoffs for a friend-multiplayer focused product where matchmaking latency matters less but reconnect UX, share-sheet entry, and cross-platform parity matter more.

Step 5: Review-Pain Synthesis

Cluster App Store complaints into themes (e.g. "cheating", "disconnects", "ads", "matchmaking fairness", "difficulty ramp", "UI clutter"). For each theme, note prevalence (rough frequency) and 2–3 representative complaint excerpts with source app.

Step 6: Opportunity & Risk Notes

End with a short section of opportunity areas (gaps in mainstream apps a friend-focused product could exploit) and risks (saturated monetisation, rule fragmentation, Apple App Store gambling review risk for real-money modes).

Step 7: Write the Research Report

Write the output artifact to the absolute path provided in your prompt. The report MUST start with YAML frontmatter:

---
epoch: <epoch from your prompt>
result: done
---
# Guandan iOS Competitive Research

## Scope & Methodology
<what you surveyed, how you sourced signals, date anchor from current_date>

## Apps Surveyed
| App | Publisher | Platform | Modes | Friend-Room? | Rule Variants | Last-Known iOS Update |
|---|---|---|---|---|---|---|
| ... | ... | ... | ... | ... | ... | ... |

## Rule Variant Matrix
| Rule Aspect | Canonical | App A | App B | App C | ... |
|---|---|---|---|---|---|
| Level ladder | ... | ... | ... | ... | ... |
| Tribute (进贡) | ... | ... | ... | ... | ... |
| 反贡 | ... | ... | ... | ... | ... |
| Wildcard (逢人配) | ... | ... | ... | ... | ... |
| Bomb hierarchy | ... | ... | ... | ... | ... |
| 同花顺 | ... | ... | ... | ... | ... |
| End-of-round scoring | ... | ... | ... | ... | ... |

## Feature Inventory
<grouped by category: core play, social, monetisation, retention, accessibility>

## UI/UX Patterns
<table layout, animations, timers, 出牌 UI, 报牌 UI, reconnect UX, emotes, voice>

## Friend-Multiplayer Flows
<invite, room code, share-sheet, deep link, seat selection, spectator, rejoin>

## Networking & State-Sync Signals
<transport, reconnect semantics, AI-托管 takeover, observable latency>

## Anti-Cheat Signals
<what observable protections look like across surveyed apps>

## AI-托管 Behaviour
<activation triggers, strength tiers, user sentiment>

## Monetisation & Retention
<IAP, ads, VIP, cosmetics, dailies, season pass, clubs>

## App Store Review Pain Themes
| Theme | Prevalence | Representative excerpts (app — quote) |
|---|---|---|
| Cheating | ... | ... |
| Disconnects | ... | ... |
| Ads | ... | ... |
| Matchmaking fairness | ... | ... |
| ... | ... | ... |

## Opportunity Areas
- ...

## Risks & Regulatory Notes
- App Store gambling/real-money rules
- Rule-variant fragmentation risk
- ...

## Source Log
<bulleted list of sources consulted — app store listings, reviews, dev blogs, community wikis>

Rules

• Cite sources at the level of "App Store listing for <app>", "App Store reviews for <app> sampled <date>", "community wiki", "dev blog URL" — do not invent quotes.
• When you cannot verify a signal (e.g. closed-source networking internals), say so explicitly in the relevant section; do not fabricate.
• Keep a bias toward friend-multiplayer flows — that is the target product's core; do not over-index on ranked/tournament content.
• Do NOT propose architecture or tech-stack choices here — that is architecture's job. Stay descriptive.

Unrecoverable issues

If a blocking constraint prevents research (e.g. no network access), still write the report with result: done, document the constraint, and do the best with what is accessible (offline priors, knowledge cutoff, etc.). Downstream stages will work with what you produced.