← Về thư mục

---

name: brand-monitoring description: Workflow for designing and deploying automated brand health and crisis monitoring systems.

---

Brand Monitoring Setup

Workflow for designing and deploying automated brand health and crisis monitoring systems.

Trigger

Use this skill when a user wants to track mentions, reputation, or crisis signals for one or more brands across public web sources.

Workflow

1. Brand Scope & Entity Mapping

• Multi-brand Namespace: Use a scalable structure: brands/<brand_id>/.
• Entity Hierarchy: Define the primary brand and its sub-entities (e.g., Fulbright -> FUV, FSPPM). Treat them as a single brand with child entities in the keyword map, not as separate brands.
• Keyword Mapping:
  • Core Entity: Main brand names.
  • Variant Entity: Acronyms, translated names, common misspellings.
  • Program Entity: Specific schools, degrees, or campus identifiers.
  • Crisis Trigger: High-risk words (e.g., "scandal", "controversy", "complaint", "tuition hike").
  • Sentinel Phrases: Specific combinations that trigger immediate alerts.

2. Public Source Mapping (Tiered)

Avoid private APIs or logged-in content. Focus on public accessibility.

Tier	Source Type	Method	Example
Tier A	Aggregators	RSS / Search RSS	Google News RSS (use site: operator to fetch domains blocked by WAF)
Tier B	High-Authority News	Tag pages / RSS	VietnamPlus, Tuổi Trẻ, VnExpress
Tier C	Public Social/Web	Scrape / Public API	YouTube public, FB public pages
Tier D	Academic/Formal	REST API / Search	OpenAlex, SSRN

Feasibility & WAF (Azure/Cloudflare 403): - Official university/brand websites often aggressively block direct scrapers. - Solution: Do not attempt direct scraping or bypass. Use Google News RSS query with the site:domain.edu.vn operator. Google crawls them easily, and the RSS output exposes title, source, publication date, and link without WAF risk. - VietnamPlus RSS: Standard RSS endpoint may return 404. Fall back to parsing the public tag pages directly (vietnamplus.vn/tags/<tag>.vnp), which return a stable 200 OK. - VnExpress search: Can block custom headers with 406. Fall back to parsing the general RSS feeds.

Social Media Collection (via Google News RSS Workaround)

Social platforms (Facebook, Threads, TikTok) do not offer free public keyword-search APIs. Use Google News RSS with the site: operator as a workaround.

Approach: - Query format: https://news.google.com/rss/search?q=site:{platform_domain}+{keyword}&hl=vi&gl=VN&ceid=VN:vi - Keywords must be URL-encoded with urllib.parse.quote() — Vietnamese characters and spaces break feedparser otherwise. - Use platform-specific keyword lists: broader for Facebook, stricter for TikTok.

Platform Behaviour: | Platform | Query Domain | Result Quality | Notes | |:---|:---|:---|:---| | Facebook | site:facebook.com | Good | Google indexes many public Facebook posts. Filter Vietnam-specific content with keyword matching on title+snippet. | | TikTok | site:tiktok.com | Fair — noisy | Returns TikTok video pages but mixed with unrelated hashtag content. Apply strict title+country filters (e.g. require "Việt Nam" or "FUV" in title). | | Threads | site:threads.net | Poor — no results | Google does not meaningfully index Threads content as of mid-2026. No workaround available without dedicated scraping. |

Content Filtering (Vietnam-specific): - Global "Fulbright" mentions dominate Facebook/TikTok (scholarship programs worldwide). - Always combine with a VN_KEYWORDS list: ["việt nam", "vietnam", "tphcm", "hcmc", "saigon", "hồ chí minh", "fuv", "fsppm", "đại học fulbright"] - Apply the filter by checking if any keyword appears in the lowercase title + " " + snippet combined string. - Hub posts (short titles with #Hashtag patterns) should also be rejected.

Pitfall: facebook-scraper library fails on modern Facebook: - The facebook-scraper Python package depends on requests-html which in turn depends on lxml.html.clean, now split into a separate lxml_html_clean package. Expect ImportError on fresh installs. - Even after fixing the import, the library may return zero results due to Facebook API changes and aggressive bot detection. - Conclusion: Do not rely on facebook-scraper. The Google News RSS workaround is the only reliably working method for keyword-based Facebook monitoring without API credentials.

3. Pipeline Design (End-to-End)

Source Intake -> Normalize -> Deduplicate -> Relevance Score -> Sentiment Score -> Crisis Gate -> Deliver.

• Deduplication: Use canonical URLs and title/snippet similarity (threshold ~85%).
• Relevance Scoring: Weight Core Entity in Title highest, followed by Crisis triggers and Body mentions.
• Sentiment Taxonomy:
  • Positive: Achievements, praise.
  • Neutral: Pure information, announcements.
  • Ambiguous: Contextual debates requiring human review.
  • Negative: Criticism, risks, complaints.

4. Crisis-First Delivery Logic

Crisis management is the primary goal, not just coverage.

• Hot Alerts: Trigger immediately if Sentiment == Negative AND Relevance >= 70 OR Crisis Trigger is present.

Reporting & Digest Requirements (Mandatory)

• Air date ('Ngay dang'): Every report and digest table MUST include a column with the exact publish or update date of the article.
• Highlights: Every table row MUST have a 'Highlight Fulbright' column extracting specific brand entities (e.g. FUV, FSPPM, Fulbright) or matching keywords.
• Direct Article Link: Do not use Google News redirect links or hub search links. Follow redirect or parse the direct clean URL and display it as a clean clickable hyperlink inside the source text to keep messages compact.
• Strict Gating: Reject search hub/tag URLs (e.g. google.com/search?, /tag/, TuoiTre topic search). Links must point strictly to specific article pages. Set a higher relevance threshold (>= 25) to filter out mentions that only briefly cite the entity without context.
• Direct RSS Fallback for Stale Items: If direct RSS feeds are too narrow and miss older articles (due to fast roll-over of RSS), fall back to Google News RSS search but process through aggressive title filters (e.g., discard titles starting with # or containing tin tức, hình ảnh, video clip mới nhất về) to maintain quality.
• Digest Format: Consolidate multiple pending alerts into a single digest message containing Date Period, Source, Air Date, clean Hyperlink, Highlight excerpt (capturing the context containing the brand name), and Sentiment score.
• Notifications: Every time a report is generated, the pipeline MUST immediately dispatch a digest message summarizing the period, source, air date, and highlights to Telegram thread #3688. Do not wait for pending alerts to trigger report-level notifications.
• Format: Absolutely no dashes (-) in report text, lists, or descriptions. Use '*' or numbers.
• Noise control: Silent background steps must not emit intermediate Telegram updates; only the final digest/announcement belongs in the destination thread.

Weekly Digest: Scheduled summary (e.g., Mon/Wed/Fri 9AM) prioritizing Negative -> Neutral -> Positive.

• Telegram Routing: For purely automated notifications (no manual execution, cron-driven), do not create a system-level department or Kanban profile. Use a Receiver Channel pattern. Configure the target chat_id and thread_id directly in the project config file (e.g. report.yaml) and use hermes send --to telegram:<chat_id>:<thread_id> to dispatch alerts. Use descriptive channel icons (like 📣) to differentiate from active work threads.
• Silent runner: Cron and collection scripts should run with deliver = local or equivalent silent mode so logs stay out of chat; only the final dispatcher/report sender speaks.

Weekly Digest: Scheduled summary (e.g., Mon/Wed/Fri 9AM) prioritizing Negative -> Neutral -> Positive.

• Telegram Routing: For purely automated notifications (no manual execution, cron-driven), do not create a system-level department or Kanban profile. Use a Receiver Channel pattern. Configure the target chat_id and thread_id directly in the project config file (e.g. report.yaml) and use hermes send --to telegram:<chat_id>:<thread_id> to dispatch alerts. Use descriptive channel icons (like 📣) to differentiate from active work threads.

5. Technical Architecture (V1 Recommended)

• Storage: Hybrid Approach.
  • SQLite: Local operational store for all raw and processed mentions.
  • Google Sheet: Stakeholder view for the last N items and alert logs.
• Cron Schedule:
  • Collection: Every 6-12 hours.
  • Crisis Check: Every 1-4 hours.
  • Digest: Fixed weekly/daily slots.

Pitfalls & Lessons

• The "Fulbright" Noise: "Fulbright" is a global scholarship. Always combine with "Vietnam", "FUV", or "FSPPM" to avoid noise.
• Workspace Data Loss: Never save the only copy of an architecture draft in a Kanban workspace. Use a persistent /docs/ folder.
• API Over-reliance: Don't design for Page APIs unless access is guaranteed. Stick to public discovery.
• Kanban Task Completion Rule: Do not automatically mark Kanban tasks as complete (kanban_complete) without explicit CEO approval. When a task has completed its execution, update its result comments, block it with a status explaining it is awaiting approval, and assign it to the CEO (ceo). Only the CEO can finalize or unblock the task.
• Tailscale Funnel Delivery: Always verify that user-facing artifact URLs use the Tailscale Funnel domain (https://vmi3427693.tail8c1aaf.ts.net/files/...) instead of local loopback/private IPs, ensuring they are accessible to stakeholders from any network.