pal-e-docs

Review: Spike: Stripe payment + payout + revenue split

review-787-2026-04-03 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue-spike required sections:
  • [x] Type — Spike
  • [x] Lineage — Standalone, second ticket for project
  • [x] Repo — forgejo_admin/twitch-2k-wager
  • [x] Question — Well-framed "which approach" question covering buy-in collection, payout mechanics, and revenue split
  • [x] What to Explore — Detailed with five investigation areas (buy-in, payout options, split tracking, webhook handler, test mode)
  • [x] Success Criteria — 5 criteria, all checkboxed
  • [x] Time-box — 2 hours with clear reasoning ("payment collection is straightforward, payout mechanics are the unknown")
  • [x] Related — 4 items listed (project page, board, two user stories)
All spike template sections present and well-populated. Template is complete.

Traceability

  • [x] story:challenger-pay label — present on board item
  • [ ] story note MISSING — No note found for story:challenger-pay. Issue Related section self-documents this: "story-twitch-2k-wager-challenger-pay (to be created)". [SCOPE] Create user story entry on project-twitch-2k-wager user-stories section.
  • [x] story:winner-payout label — present on board item
  • [ ] story note MISSING — No note found for story:winner-payout. Issue Related section self-documents this: "story-twitch-2k-wager-winner-payout (to be created)". [SCOPE] Create user story entry on project-twitch-2k-wager user-stories section.
  • [x] arch:stripe-api label — present on board item
  • [ ] arch note MISSING — No arch-stripe-api note found in pal-e-docs. [SCOPE] Create architecture note arch-stripe-api for the Stripe integration component.
  • [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/forgejo_admin/twitch-2k-wager/issues/2, state: open
  • [ ] project-twitch-2k-wager — Project page not found in pal-e-docs (empty TOC, no search results). All traceability anchors depend on this page existing. [SCOPE] Create project page project-twitch-2k-wager with user-stories and architecture sections.

File Targets

N/A — Spike type. No file targets expected. Issue mentions ~/secrets/stripe/ as credential location, which is informational context for the spike investigator, not a code target.

Repo Placement

OK. Issue is filed on forgejo_admin/twitch-2k-wager. Repo exists and is confirmed via Forgejo API (private repo, SvelteKit + Stripe per description). The spike investigates Stripe architecture for this project — correct placement.

Dependencies

  • Board item #786 (Spike: Twitch OAuth for public users) — same board, backlog. Independent spike — OAuth and payments are orthogonal concerns. No blocking dependency.
  • Board item #788 (Service onboarding: playme2k funnel + kustomize) — overlapping concern: the "Where does the webhook handler live?" question in this spike touches the same service architecture that #788 will configure. Not a hard blocker, but the spike investigator should be aware.
  • Board item #789 (Landing page HTML/CSS prototype) — depends on both spikes completing first to inform UI flows. No blocking concern for this spike.
  • No dependencies are documented in the issue body. The Related section lists project and board but not sibling tickets.

Acceptance Criteria

5 criteria assessed for testability:
  • [x] "Payout mechanism decided with evidence" — verifiable: spike output is a decision doc with evidence. Agent can confirm doc exists.
  • [x] "Revenue split tracking approach decided" — verifiable: spike output is a decision doc. Agent can confirm approach is documented.
  • [x] "Working Stripe Checkout test flow" — verifiable: agent can run the test flow locally with test keys and confirm session creation + webhook receipt.
  • [x] "Webhook delivery confirmed" — verifiable: Stripe CLI output or test endpoint logs. Issue specifically mentions verification method.
  • [x] "Follow-up feature tickets created" — verifiable: agent can check Forgejo issues list after spike completion.
All criteria are testable. Good specificity on verification methods (Stripe CLI explicitly mentioned).

Blast Radius

Greenfield spike for a new project — no existing codebase to affect. No sibling services share Stripe credentials yet. The revenue split decision may set a precedent for future Marcus/Lucas ventures, but that is a business decision, not a code blast radius. Low risk. Rollback is N/A (spike produces decisions, not deployments).

Decomposition Assessment

Apply three-thing limit and five-minute rule:
  • 5 acceptance criteria, but this is a spike (investigation, not implementation) — criteria are research questions, not code changes
  • 1 repo scope
  • Time-boxed to 2 hours by design
  • No discrete independent subtasks that need parallelization — the investigation is sequential (understand options, test one flow, decide)
No decomposition needed. Spike is appropriately scoped as a single investigation pass.

Recommendation

  • [SCOPE] Create project page project-twitch-2k-wager with user-stories and architecture sections. This is the anchor for all traceability — both story labels and the arch label reference backing notes that do not yet exist.
  • [SCOPE] Create user story entries for story:challenger-pay and story:winner-payout on the project page user-stories section.
  • [SCOPE] Create architecture note arch-stripe-api for the Stripe integration component.
  • [BODY] Add sibling ticket awareness to Related section: "Board item #788 (Service onboarding) may affect webhook handler placement decision."