/pulse-faq-sync

name: pulse-faq-sync
description: "Sync and update the community FAQ from Discord conversations, WhatsApp groups, and GitHub issues. Identifies recurring questions, adds new entries, and keeps the FAQ as a living knowledge base. Use when user says 'update faq', 'sync faq', 'community faq', 'frequently asked questions', or when running community routines that detect unanswered/recurring questions."

FAQ Sync — Living Knowledge Base

Routine that keeps the community FAQ always updated, fed by questions from Discord, WhatsApp, and GitHub issues.

**Always respond in English.**

Main file

workspace/community/[C] FAQ.md

This is the single source of truth file. All agents and support bots should consult this file.

FAQ Structure

The file follows this format:

# FAQ — Community

> Automatically updated. Last sync: {YYYY-MM-DD HH:MM}
> Sources: Discord (#help, #feedback) + GitHub Issues
> Total: {N} questions

---

## Installation & Setup
<!-- tag: installation, setup, docker, deploy -->

### How to install the main API via Docker?
**Answer:** [clear and direct answer]
**Source:** Discord #help (recurring) | [Official doc link if available]
**Added:** YYYY-MM-DD

### How to configure SSL/HTTPS?
**Answer:** [...]
**Source:** GitHub YOUR_ORG/main-api#123
**Added:** YYYY-MM-DD

---

## Configuration
<!-- tag: config, env, variables, webhook -->

### How to configure webhooks?
...

---

## Integrations
<!-- tag: whatsapp, telegram, typebot, n8n, chatwoot -->

...

## Evo CRM
<!-- tag: crm, agents, pipeline, leads -->

...

## Evo Go
<!-- tag: evogo, go, manager -->

...

## Billing & Licenses
<!-- tag: license, plan, price, payment -->

...

## Common Errors
<!-- tag: error, bug, 503, 401, timeout -->

...

Workflow

Step 1 — Read current FAQ

Read `workspace/community/[C] FAQ.md`. If it does not exist, create it with the base structure.

Count how many entries exist and which categories.

Step 2 — Collect new questions

**From Discord (last 24h):** Use `/discord-get-messages` on channels:

• `🆘・help` (ID do canal de help)
• `🆘・feedback`
• `💬・chat-pt`

Identify messages that are **questions** (end in ?, ask for help, report errors).

**From GitHub (last 24h):**

# Issues abertas recentemente nos 5 repos
gh issue list --repo YOUR_ORG/main-api --state open --json title,body,labels,createdAt --limit 10
gh issue list --repo YOUR_ORG/crm-product --state open --json title,body,labels,createdAt --limit 10
gh issue list --repo YOUR_ORG/go-service --state open --json title,body,labels,createdAt --limit 10
gh issue list --repo YOUR_ORG/crm-community --state open --json title,body,labels,createdAt --limit 10
gh issue list --repo YOUR_ORG/methodology --state open --json title,body,labels,createdAt --limit 5

Filter issues that are questions or recurring bugs.

**From WhatsApp (last 24h):** Use `/int-whatsapp` to fetch messages from groups:

python3 {project-root}/.claude/skills/int-whatsapp/scripts/whatsapp_client.py messages_24h

Filter messages that are questions (end in ?, ask for help, report errors, ask for configuration guidance). Mark source as "WhatsApp {group name}".

**From Linear — "Evolution Suporte" Project:** Use Linear MCP to fetch recently resolved issues from the paid support project:

list_issues(project="Evolution Suporte", state="Done", updatedAt="-P1D")

Resolved issues from paid support are a gold mine for the FAQ — these are real client problems with validated solutions. For each resolved issue:

• Extract the reported problem as a question
• Extract the resolution as an answer
• Mark source as "Linear — Paid Support"
• Prioritize inclusion in FAQ (paying clients = high relevance)

Step 3 — Analyze and classify (MANDATORY validation gate)

For each question found:

1. **Already in the FAQ?** → If yes, check if the answer needs updating 2. **Is it recurring?** → If it appeared 2+ times (Discord, GitHub, or WhatsApp), add with priority 3. **HAS A REAL, VERIFIED ANSWER?** → **This is a HARD GATE. If this check fails, SKIP the question — do NOT add to FAQ.** Required by source:

• **GitHub issues:** must link to the specific comment URL with the solution, and the comment must be from a team member (org member, maintainer) OR the issue must be in state `closed` with label `solved`/`resolved`. Issues with no replies or only community speculation → SKIP.
• **Linear (Evolution Suporte):** only issues with `state=Done` AND a resolution comment from the assignee. Cite the issue ID + resolution comment.
• **Discord:** must cite the exact username + timestamp + message link of the **reply** (not the question). The reply must come from a team member or a verified helper. Questions without a reply, or with only "+1"/"same here" → SKIP.
• **WhatsApp:** since messages don't have stable links, require the responder's name + approximate timestamp AND the literal reply text. If only the question exists with no reply → SKIP.
• **No answer found within 24h?** → SKIP and count under "pending documentation" in the Step 6 report. Do not create an FAQ entry.

4. **Which category?** → Classify in the correct FAQ category

Step 4 — Update FAQ (no paraphrasing)

For each new question that passed the Step 3 gate:

• Formulate a clear question in PT-BR (rewriting the question is fine)
• **DO NOT rewrite, paraphrase or "improve" the answer.** Extract the literal text of the answer from the source and cite it. Light formatting (bullet list, code fences) is OK, but the content must come from the source.
• If the source answer is partial or unclear for one aspect, add `[pending: {specific missing detail}]` inline and flag for follow-up — do not fill the gap with generic knowledge.
• Include source with the verifiable reference (comment URL, username + timestamp, Linear issue ID)
• Include date
• Add to the correct category

For existing questions:

• Update the answer only if there is new verified information from a sou