epic: in-app feedback & suggestion system

[wcmchenry3-stack]

In plain English

Users of gaming_app and book_app can submit bug reports, feature requests, and localization suggestions directly from within the app. Submissions are validated, enriched by Claude, and automatically filed as structured GitHub issues in the originating repo — without developers having to triage free-form emails or Discord messages.

Problem statement

Current state: There is no in-app channel for users to report bugs or suggest features. Feedback arrives ad-hoc and unstructured via external channels, creating triage overhead and losing context (no session logs, no device info, no structured reproduction steps).

Desired state: A themed feedback widget lives in each app. Users fill in a title, description, type (bug / feature / localization), and optional screenshot. On submit, session logs are attached automatically, Claude validates and enriches the submission, and a well-structured GitHub issue is filed in the correct repo with appropriate labels.

Architecture note

Global worker, per-repo UI. A single Cloudflare Worker (cloudflare/feedback-worker/ in this meta-repo) handles all backend concerns: rate limiting, content validation (Claude API), Claude enrichment, and GitHub issue creation. This avoids duplicating identical worker code across repos.

Each app repo hosts its own feedback widget UI component that matches its design tokens/theme and calls the shared worker endpoint (configured as a secret/env var, not hardcoded). This split keeps infrastructure DRY while allowing each app's widget to look native.

Worker location: wcmchenry3-stack/.github → cloudflare/feedback-worker/
UI location: per-repo (gaming_app, book_app)
Worker URL: injected via env var / secret in each app's build config

Child stories

• feat: Cloudflare feedback worker — core POST endpoint, rate limiting, Claude enrichment, GitHub issue creation #109 — Cloudflare feedback worker — core POST endpoint, rate limiting, Claude enrichment, GitHub issue creation
• feat(gaming_app): feedback form UI widget — themed bug/feature submission with screenshot and session log attachment #110 — Feedback form UI — gaming_app (themed widget, screenshot upload, session log attachment)
• feat(book_app): feedback form UI widget — themed bug/feature submission with screenshot and session log attachment #111 — Feedback form UI — book_app (themed widget, screenshot upload, session log attachment)
• feat: localization suggestion form variant — AI vs human translation provenance, 3-model consensus before submit #112 — Localization suggestion form variant (AI vs human provenance, 3-model consensus check)
• feat: security hardening for feedback worker — OWASP input validation, abuse rate limits, CSRF protection, secrets management #113 — Security hardening for feedback worker (OWASP input validation, CSRF, abuse rate limits, secrets management)
• feat: feedback widget theme contract — design-token interface spec so new apps can integrate without code changes #114 — Feedback widget theme contract (design-token interface spec for new app integrations)
• ci: feedback-theme.css token lint — validate required --feedback-* tokens are defined in each app #116 — Token lint CI — validate required --feedback-* tokens are defined in each app's feedback-theme.css
• ci(gaming_app): wire called-feedback-token-lint into gaming_app CI pipeline #118 — Wire token lint CI into gaming_app CI pipeline
• ci(book_app): wire called-feedback-token-lint into book_app CI pipeline #119 — Wire token lint CI into book_app CI pipeline
• ci: provenance.json coverage enforcement — every i18n key must have an ai/human entry #120 — Provenance.json coverage enforcement — every i18n key must have an ai/human entry

Out of scope

• Native mobile push notifications
• An admin dashboard for reviewing feedback (GitHub Issues UI serves this purpose)
• Sentiment analytics or feedback aggregation
• Third-party feedback SaaS integrations (Canny, UserVoice, etc.)
• Feedback from any repo outside gaming_app and book_app (for now)

Success metrics

• A bug report or feature request submitted in-app appears as a structured GitHub issue in the correct repo within 10 seconds
• Zero spam issues created (content policy blocks or flags abuse before issue creation)
• Widget renders correctly in both gaming_app and book_app visual regression tests
• Localization suggestion form correctly surfaces AI-vs-human translation provenance
• Worker handles 3-model consensus check for localization submissions before filing

Dependencies

• Blocked by: none — greenfield feature