## User Feedback Analysis — 2025-12-18

### Data sources reviewed
- Discord daily summaries: **2025-12-15, 2025-12-16, 2025-12-17**
- GitHub activity snapshot: **2025-12-17** (14 new issues; 3 UX issues closed: #6243, #6242, #6240)
- Weekly/monthly repo summaries (context for recurring themes)

Across the **3 Discord days**, **token migration/exchange handling** appears in **3/3 days (100%)**, making it the most consistently recurring community friction point in this slice of feedback. Development/onboarding friction (plugins/actions, DB setup) appears in **2/3 days (67%)**.

---

## 1) Pain Point Categorization (Top 7)

### 1) Integration — Token migration & exchange handling inconsistencies (High frequency, High severity)
**What users report**
- Confusion and frustration that **Bithumb vs Kraken** handle the AI16Z → ELIZAOS swap differently (12-17).
- Repeated requests (notably from Korean community members) for **proof of project–exchange communications**, especially around **snapshot timing** (12-17).
- Concern about **eligibility + wallet support gaps** (e.g., Tangem wallet not supported via WalletConnect per GitHub issue #6211, monthly report).
- Safety concerns: reports/rumors that the **migration site may be compromised** (12-15), plus Discord impersonators (GitHub #6211 mentions “Discord support compromised”).

**Most affected users**
- Non-custodial wallet users with unsupported connectors (Tangem) and **custodial exchange users** who relied on exchange messaging around snapshot/distribution.

---

### 2) Documentation — “How do I extend actions/plugins?” and “Where is X folder?” (High frequency, Medium severity)
**What users report**
- Confusion about plugin source layout: “can’t see the starknet-plugin folder” → advised to “clone the plugin into the packages folder” (12-17).
- Uncertainty about the correct steps to add actions: create file in `actions/` **and** register in `src/index` (12-17).
- Ongoing internal call to **update/clean/sync documentation** (12-17).
- Documentation clarity gaps also surfaced in UI wording issues (GitHub #6240 “Replace ‘RAG’ terminology with plain language”).

**Most affected users**
- New plugin developers and “first extension” builders (e.g., FenrirFawks).

---

### 3) Technical Functionality — Database setup/migrations and persistent plugin DB errors (Medium frequency, High severity)
**What users report**
- Persistent local PostgreSQL migration problems and permission issues when setting up (12-16).
- Twitter replies causing DB failures due to foreign key constraints; “latest codebase has SQL fixes” (12-15).
- Broader context: SQL plugin migration compatibility work is a major effort (weekly/monthly reports), indicating recurring pain.

**Most affected users**
- Self-hosters and developers trying to run locally (Postgres, Neon, PGLite) and social plugins that write frequently (Twitter).

---

### 4) UX/UI — Streaming UI behavior inconsistent; edit-mode misfires; visual mismatches (Medium frequency, Medium severity)
**What users report**
- Streaming works for simple messages/actions, but **Actions UI still renders all text at once** (12-16).
- UI correctness issues closed quickly on GitHub:
  - #6243: “Edit mode chat suggestions triggering agent responses” (closed)
  - #6242: “Fix avatar mismatch between edit view and sidebar” (closed)
- Strong ongoing push to simplify UI language and flows (weekly/monthly reports; #6240 closed).

**Most affected users**
- Users relying on the cloud UI for iterative prompting/testing and developers demoing agent behavior.

---

### 5) Community — Support trust & channel hygiene issues (Medium frequency, High severity)
**What users report**
- Reports of scammers/impersonators; one scammer was identified and banned (12-15).
- GitHub #6211 explicitly states Discord support is unreliable due to impersonators.
- Repeated price-talk/off-topic content requiring redirection to correct channels (12-16).

**Most affected users**
- Newcomers seeking help with migration and setup, who are least able to verify official links/support.

---

### 6) Engineering Process / Maintainability — Oversized PRs and review bottlenecks (Lower frequency, Medium severity)
**What users report**
- Discord plugin PR has **66 commits**, open for 3 weeks; concern it’s “getting too big” and should be reviewed before merge (12-17).

**Most affected users**
- Plugin maintainers and downstream users waiting for fixes/features.

---

### 7) Documentation/UX — Terminology mismatch (“RAG”, “MCP”, etc.) (Medium frequency, Medium severity)
**What users report**
- GitHub #6240 closed: remove/replace “RAG” terminology with plain language.
- Weekly/monthly reports show multiple issues aimed at renaming and simplifying terms (e.g., “Knowledge” → “Files”, “Services” vs “MCP”).

**Most affected users**
- New users and non-ML engineers evaluating the product.

---

## 2) Usage Pattern Analysis (Actual vs intended)

### How users are actually using elizaOS
1. **Production-ish agents connected to real workflows**
   - Example: a community member deployed a **Polymarket tracking agent** writing to a **Neon database**, deployed to **Fly.io**, and published to GitHub (12-16).
   - This is more “agent-as-integration glue + data pipeline” than purely chat.

2. **Agents in social environments as a business requirement**
   - Market makers require agents deployed and “actively engaging in social environments” before investment (12-17 partners channel).
   - This increases importance of Discord/Twitter plugins, stability, moderation, and streaming UX for demos.

3. **“Vibe coding” + AI-assisted dev workflows**
   - Multiple users report large portions of code AI-generated (e.g., “50%”) and ask for workflow guides/tools (12-16).
   - This changes expectations: users want **fast scaffolding, strong defaults, fewer footguns**, and “copy/paste runnable” examples.

### Emerging / unexpected use cases
- **Sports analytics Q&A agent** over NFL trade data in Neon (12-15): indicates demand for “DB + tool use + domain Q&A” templates.
- **Payments/monetization planning** (monthly: issue #6244): users expect “deploy → publish → monetize” paths, not just local experimentation.

### Feature requests that align with observed usage
- **Web search** (weekly/monthly mentions of #6246): aligns with agents operating in public/social contexts.
- **Better file/RAG ingestion UX** (ongoing issue themes): aligns with data-backed Q&A use cases (NFL, Polymarket).
- **Streaming UI consistency**: crucial for demo/production confidence.

---

## 3) Implementation Opportunities (2–3 per major pain point)

### A) Token migration & exchange inconsistencies (Integration)
**Opportunity 1 (High impact, Medium effort): Publish an “Exchange Status & Rules” live page**
- A single canonical page listing each exchange (e.g., **Bithumb, Kraken**) with:
  - snapshot cutoff rules (“sold after snapshot not eligible” explanation given in Discord on 12-17),
  - expected distribution timing,
  - what the project can/can’t do for custodial balances.
- Similar approach: many L1/L2 migrations maintain a **status dashboard** + pinned updates per exchange.

**Opportunity 2 (High impact, Medium effort): Add a “Wallet/Exchange Troubleshooter” wizard**
- Questions: “Where were tokens held on snapshot date?” “Can you connect the snapshot wallet?” “Is it custodial?”
- Output: exact next steps + warnings (e.g., “Do not send tokens to anyone; only use official portal”).
- Similar approach: Stripe-like guided flows; also common in bridge UIs.

**Opportunity 3 (High impact, Higher effort): Expand connector support / alternative verification path**
- For unsupported wallets (e.g., Tangem), provide one of:
  - read-only address proof + signed message verification options where possible,
  - manual support process with strict verification (GitHub-only intake) if signatures aren’t possible.
- Similar approach: many airdrops provide **manual claim review** for edge-case wallets.

---

### B) Plugin/actions extension confusion (Documentation)
**Opportunity 1 (High impact, Low–Medium effort): “Create your first action” golden-path doc**
- Minimal steps with exact file paths:
  - create `packages/<plugin>/src/actions/myAction.ts`
  - export/register in `packages/<plugin>/src/index.ts`
  - run a single command to test locally
- Include the exact scenario from Discord (12-17): missing plugin folder → recommended cloning into `packages/`.

**Opportunity 2 (Medium impact, Medium effort): CLI scaffolding for actions**
- `elizaos plugin add-action <name>` creates file + updates `src/index.ts`.
- Similar approach: RedwoodJS / NestJS generators reduce these registration errors.

**Opportunity 3 (Medium impact, Low effort): Add repo-level “Where is the plugin code?” FAQ**
- Address common confusion directly: monorepo vs external plugin repos, and recommended dev workflow.

---

### C) DB setup/migrations failures (Technical Functionality)
**Opportunity 1 (High impact, Medium effort): Add a single “DB doctor” command**
- `elizaos doctor db` checks:
  - connection/auth,
  - migration status,
  - required extensions/permissions,
  - common Postgres role/grant issues.
- Similar approach: Rails’ `db:prepare` and Prisma’s migration diagnostics.

**Opportunity 2 (High impact, Medium effort): Publish “Known-good DB configs”**
- Provide copy-paste docker-compose for Postgres + env examples for Neon.
- Include fixes referenced informally (“latest codebase has SQL fixes”) (12-15) so users know what version to use.

**Opportunity 3 (Medium impact, Higher effort): Add a migration failure error explainer**
- When FK constraint fails (Twitter replies issue), show actionable guidance and link to docs.

---

### D) Streaming UI inconsistency (UX/UI + Performance perception)
**Opportunity 1 (High impact, Medium effort): Make streaming behavior consistent across components**
- Ensure Actions UI renders token-by-token (or chunk-by-chunk) like chat.
- Add an integration test that asserts incremental rendering (prevents regressions).

**Opportunity 2 (Medium impact, Low effort): Add a “Streaming: On/Off” toggle + indicator**
- If some contexts cannot stream, set expectations explicitly (spinner + “streaming not available here yet”).

**Opportunity 3 (Medium impact, Medium effort): Standardize on one streaming event protocol**
- Avoid partial implementations across monorepo and cloud repo (noted PRs in both eliza-cloud-v2 and monorepo on 12-17).

Similar projects: Chat UIs (OpenAI-like) often centralize streaming in a single hook/component to avoid mismatched experiences.

---

### E) Support trust, scams, and channel hygiene (Community)
**Opportunity 1 (High impact, Low effort): Harden “official support” verification**
- Pin a message in migration/support channels:
  - “We will never DM you first”
  - “We will never ask you to send tokens”
  - official links list
  - support escalation path via GitHub issues for sensitive cases (mirrors #6211 preference).

**Opportunity 2 (High impact, Medium effort): Add a verified-support ticket bot or GitHub issue template**
- Force structured fields (wallet address, exchange, snapshot location, screenshots) and auto-warn about scams.
- Similar approach: many crypto projects use ticket forms + signed announcements only.

**Opportunity 3 (Medium impact, Medium effort): Better channel routing**
- Auto-detect price talk and prompt users to move channels (already manual moderation on 12-16).

---

### F) Oversized PR review bottlenecks (Engineering process)
**Opportunity 1 (High impact, Low effort): Enforce PR size limits / staged merges**
- Require splitting into refactor vs behavior change (Discord plugin PR: 66 commits, 3 weeks open) (12-17).

**Opportunity 2 (Medium impact, Low effort): “Screenshots/video required for UI PRs” policy**
- Already proposed in Discord (12-15). Implement as PR template checkbox + CI check.

**Opportunity 3 (Medium impact, Medium effort): Add CODEOWNERS + review routing**
- Ensures plugin maintainers automatically requested.

---

## 4) Communication Gaps (Expectations vs reality)

### Gap: “Migration is a project action” vs “Migration is exchange-controlled”
- Users expect the team can directly fix custodial exchange delays; community members repeatedly clarify exchanges control distribution (12-15, 12-17).
**Fix**
- Put this in the migration portal and docs as a first-class callout with per-exchange status.

### Gap: “Folder not found” → unclear plugin development workflow
- Users expected the Starknet plugin to be in the repo by default; solution was to clone into `packages/` (12-17).
**Fix**
- Document supported workflows: monorepo plugin vs external plugin repo, and how to link locally.

### Gap: “Streaming works” but not in Actions UI
- Users hear streaming is “working,” then see non-streaming UI in key workflows (12-16).
**Fix**
- Track “streaming coverage” explicitly (Chat: ✅, Actions UI: ❌, etc.) in release notes.

### Recurring questions indicating onboarding gaps
- “Is ElizaOS finished / still alive?” (12-16)
- “Where is the Twitter page?” (12-16)
- “Is the migration site safe now?” (12-17 unanswered)
**Fix**
- Add an onboarding “Start Here” panel in Discord + docs, and a security status banner when incidents occur.

---

## 5) Community Engagement Insights

### Power users (and what they need)
- **Stan / standujar / Odilitime**: actively troubleshooting, reviewing PRs, and guiding plugin/action registration (12-16, 12-17). Need:
  - better docs to reduce repeated Q&A load,
  - smaller PRs to review,
  - test coverage for streaming/messaging changes.
- **Thirtieth** (builder): deploying real agents (Polymarket → Neon → Fly.io) (12-16). Needs:
  - clearer deployment templates,
  - “agent config: what it should talk about” guidance (noted as an action item).

### Newcomer questions (onboarding friction)
- Setup blockers: Postgres migrations and permissions (12-16).
- Plugin extension confusion (12-17).
- Project legitimacy/status questions (“still alive?”) (12-16).

### Converting passive users into contributors
- Create “good first issue” bundles from the UX issue backlog (many issues opened/closed rapidly).
- Run a monthly “Docs drive” where helpers turn top Discord questions into PRs (reward via contributor role, contest tie-ins).
- Provide a template repo for common agent patterns (DB-backed Q&A, tracker-to-DB, social bot) to encourage PRs in examples.

---

## 6) Feedback Collection Improvements

### Current channel effectiveness
- **Discord**: great for rapid troubleshooting, but high noise (price/off-topic) and vulnerable to impersonation during sensitive events.
- **GitHub issues**: better for high-stakes topics (e.g., #6211 explicitly moved there for safety), but many user problems never become structured reports.

### Improvements (more structured, actionable feedback)
1. **Add “Support Intake” GitHub issue templates**
   - Separate templates for: migration/exchange, wallet-connector problems, DB/setup, plugin dev.
   - Require minimal reproducible info (versions, OS, steps, logs).

2. **Weekly “Top 5 Discord FAQs → Docs updates” ritual**
   - A rotating volunteer converts FAQs into PRs; reduces repeated questions.

3. **Add lightweight product telemetry prompts (opt-in)**
   - In Cloud UI: “Was this confusing?” after onboarding steps (plugins selection, file upload, deploy).
   - Helps quantify UX pain beyond Discord anecdotes.

### Underrepresented segments
- Non-English communities (Korean users are present but appear underserved with official, timely bilingual updates).
- Non-crypto developers who want agent framework features but are deterred by migration noise in main channels.
- Enterprise evaluators (an “enterprise subscription solution” was mentioned but unclear; needs a clearer intake path).

---

## Prioritized High-Impact Actions (Next 2–4 weeks)

1) **Launch a canonical Token Migration Status + Safety page** (exchange-by-exchange rules, snapshot explanation, official links, incident/status banner).  
2) **Publish a “First Action in a Plugin” golden-path guide + add CLI scaffolding backlog item** (reduce repeated Discord support for actions registration and plugin placement).  
3) **Fix streaming consistency in Actions UI and document streaming coverage** (close the perception gap between “streaming works” and actual UI behavior).  
4) **Add DB “doctor” diagnostics + known-good Postgres/Neon configs** (cut setup time and migration failures).  
5) **Implement support hardening: verified-support guidance + structured GitHub templates for sensitive issues** (reduce scam risk and restore trust during migrations).