Bug Clustering Process

Step-by-step procedure for transforming raw XPost objects into structured, clustered bug candidates with PII redaction and reliability scoring.

Overview

Loaded by the bug-clusterer agent inside the x-bug-triage plugin. Transforms raw XPost records ingested from X/Twitter into structured BugCandidate rows, deduplicates near-identical candidates, classifies each candidate into one of 12 bug families, redacts six categories of PII, scores reporter reliability across four dimensions, and groups results into bug clusters by deterministic signature. The output feeds the downstream repo-scanning, owner-routing, and triage-display stages.

Prerequisites

• Database initialized via lib/db.ts schema migrations
• config/cluster-matching-thresholds.json present (controls dedup + cluster overlap thresholds)
• config/approved-accounts.json present (drives reporter category tagging)
• Raw XPost[] array passed in by the orchestrator (not fetched here)

Instructions

Step 1: Parse

For each XPost, produce a BugCandidate with all 33 fields using lib/parser.ts:

• Extract product_surface, feature_area, symptoms, error_strings, repro_hints
• Extract urls, media_keys, language, conversation references
• Determine source_type (mention, reply, quote_post, search_hit)

Step 1.5: Deduplicate

Before classification, run content-similarity deduplication using lib/dedupe.ts:

• Call deduplicateCandidates() with parsed candidates and the candidate_dedup.hybrid_similarity_threshold from config/cluster-matching-thresholds.json (default 0.70)
• Uses char-trigram + token-Jaccard hybrid similarity
• Does NOT remove posts — tags them as duplicate groups with a canonical post (highest engagement)
• Only canonical posts and non-duplicates (forward_ids) proceed to classification
• Log dedup stats in the form: "N posts (M unique, K duplicate groups)" with N/M/K replaced by integer counts

Step 2: Classify

Run lib/classifier.ts on each candidate:

• Assign one of 12 classifications with confidence score (0.0-1.0) and rationale
• Sarcastic bug reports get classified separately — still treated as signal

Step 3: Redact PII

Run lib/redactor.ts on each candidate:

• Detect 6 PII types: email, API key, phone, account ID, media flag, URL token
• Replace with [REDACTED:type] tags
• Set pii_flags array and raw_text_storage_policy

Step 4: Score Reliability

Run lib/reporter-scorer.ts on each candidate:

• 4 dimensions: report quality, independe…

Owner Routing Process

Step-by-step procedure for determining the most likely owner/team for each bug cluster using strict 6-level precedence with staleness detection and override memory.

Overview

Loaded by the owner-router agent inside the x-bug-triage plugin. Walks each open bug cluster through a deterministic six-level routing precedence (service-owner → oncall → CODEOWNERS → recent assignees → recent committers → fallback mapping), applies confidence modifiers, detects stale signals, and produces a ranked routing recommendation. Honors prior routing overrides recorded in cluster memory before consulting any signal source.

Prerequisites

• Cluster table populated upstream by the bug-clustering stage
• Routing config available at config/routing.json (precedence modifiers, staleness threshold)
• Triage MCP server reachable for mcp__triage__lookup_* tool calls
• Repos in the cluster's product_surface have a configured surface→repo mapping

Instructions

Step 1: Check Overrides First

For each cluster, check if a routing_override exists from a prior run:

• If found: use the override (confidence 1.0, source "routing_override"), skip precedence lookup
• Log the override application to audit

Step 2: Query Sources in Precedence Order

For each cluster without an override, query sources strictly in order:

Stop at the first level that returns a valid team or assignee.

Step 3: Apply Confidence Modifiers

Multiply each result's confidence by the precedence modifier from routing_config.

Step 4: Detect Staleness

Flag any routing signal older than the staleness threshold (default 30 days):

• Mark the result as stale with the number of days
• Reduce confidence accordingly
• Stale signals are still usable but should be noted in output

Step 5: Build Recommendation

Using lib.buildRoutingRecommendation():

• Rank valid results by level (lowest level = highest priority)
…

Repo Scanning Process

Step-by-step procedure for scanning GitHub repos to gather corroborating evidence for bug clusters, assigning confidence tiers to each finding.

Overview

Loaded by the repo-scanner agent inside the x-bug-triage plugin. Walks each clustered bug through a fixed evidence-gathering pipeline against the up-to-three repos most likely to host the bug: matching open/recent issues, recent commits in the impact window, affected code paths, and recent deploys correlated to the cluster's first_seen timestamp. Each finding is graded against the evidence-tier policy and recorded as cluster evidence.

Prerequisites

• Cluster table populated upstream by the bug-clustering stage
• surface_repo_mapping configured for every product_surface present in clusters
• Triage MCP server reachable for mcp__triage__search_issues, mcp__triage__inspect_recent_commits, mcp__triage__inspect_code_paths, and mcp__triage__check_recent_deploys
• GitHub access tokens with read scope on the target repos

Instructions

Step 1: Select Repos

For each cluster:

1. Look up repos from surface_repo_mapping using the cluster's product_surface
2. Cap at top 3 repos per cluster (hard limit — never scan more)
3. If no mapping exists, note it as a warning and skip

Step 2: Search Issues

For each repo, call mcp__triage__search_issues with the cluster's symptoms and error_strings:

• Match error strings against open/recent issues
• Assign evidence tier based on match confidence

Step 3: Inspect Recent Commits

Call mcp__triage__inspect_recent_commits for each repo:

• 7-day window from current date
• Filter by affected paths if known from the cluster's feature_area
• Look for commits that touch relevant code paths

Step 4: Inspect Code Paths

Call mcp__triage__inspect_code_paths with the cluster's surface and feature_area:

• Identify likely affected code paths
• Check for recent changes or known fragile areas

Step 5: Check Recent Deploys

Call mcp__triage__check_recent_deploys for each repo:

• Correlate deploy/release timing with cluster's first_seen timestamp
• Recent deploy near first_seen is a stronger signal

Step 6: Assign Evidence Tiers

For each piece of evidence, assign a tier:

Triage Display Process

Step-by-step procedure for formatting triage results as terminal-ready markdown and handling interactive review command parsing.

Overview

Loaded by the triage-summarizer agent inside the x-bug-triage plugin. Renders the orchestrator's triage results as compact terminal markdown (summary view, detail view, action confirmations) and parses interactive review commands (details, file, dismiss, merge, escalate, monitor, snooze, split, reroute, full-report). The skill is purely formatting + parsing — it never mutates triage state directly; it returns parsed commands to the orchestrator for execution.

Prerequisites

• Cluster + evidence + routing rows produced upstream by bug-clustering, repo-scanning, and owner-routing
• Triage MCP server reachable for mcp__triage__parse_review_command
• Helper library mcp/triage-server/lib.ts available for formatActionConfirmation()

Instructions

Step 1: Render Summary

Produce the initial triage summary as terminal markdown:

X Bug Triage — Run {date} {time} UTC
Account: @{account} · Window: last {window} · {count} posts ({unique} unique, {dedup_groups} duplicate groups)
[warning] Data quality: {warning}                  ← show ONLY when date_confidence is low or medium

--- Sources ---                             ← show ALWAYS between header and clusters
{source_name}      {status}    {count} posts   (rate limit: {remaining}/{limit})
...

--- {n} clusters ({new} new, {existing} existing) ---

{icon} {#} · {bug_signature}
     {report_count} reports · {severity} severity · {status_note}
     Owner: {team}
     Evidence: {t1} Tier 1, {t2} Tier 2, {t3} Tier 3, {t4} Tier 4 · Top: {description}

--- Commands ---
details <#>  ·  file <#>  ·  dismiss <#>  ·  merge <#> <issue>
escalate <#>  ·  monitor <#>  ·  snooze <#> <duration>
split <#>  ·  reroute <#>  ·  full-report

Step 2: Render Detail View (for details command)

When showing a single cluster in detail:

• Family, surface, feature area
• Report count, confidence percentage
• Severity + rationale (always show rationale for high/critical)
• Status and time range (first_seen to last_seen)
• Evidence summary line (omit tiers with 0 count)
• Evidence listed by tier (all tiers, highest first)
• 3 representative posts (highest quality, most distinct, most recent) — truncate at 100 chars
• Routing with ranked assignees and confidence percentages

Step 3: Parse Review Commands

When receiving a command string, call mcp__triage__parse_review_command:

X Bug Triage

Closed-loop bug triage from public X/Twitter complaints to clustered, evidence-backed GitHub issues.

Overview

Product teams learn about bugs from X/Twitter hours before internal monitoring catches them. This skill automates the pipeline: ingest complaints, classify and cluster them by bug family, scan repos for corroborating evidence, route to owners, and file issues — all with human confirmation gates. Results display directly in the terminal with optional Slack delivery for team review.

Prerequisites

• X API bearer token configured at ~/.claude/channels/x-triage/.env
• SQLite database initialized (bun run db:migrate)
• config/approved-accounts.json and config/approved-searches.json populated
• GitHub CLI (gh) for issue filing

Verify environment before starting:

!test -f data/triage.db && echo "DB ready" || echo "Run: bun run db:migrate"

!test -f config/approved-accounts.json && echo "Accounts configured" || echo "Missing: config/approved-accounts.json"

Instructions

Step 1: Intake

1. Resolve account username to ID: mcp__triage__resolve_username
2. Fetch mention timeline: mcp__triage__fetch_mentions
3. Run approved searches: mcp__triage__search_recent
4. Cross-reference mentions with search results for completeness
5. Hydrate conversation threads for posts with conversation_id: mcp__triage__fetch_conversation
6. Fetch quote tweets for high-engagement posts: mcp__triage__fetch_quote_tweets

After intake completes:

1. Call assessFreshness() from lib/freshness.ts with the combined post set and the requested window boundaries. If date_confidence is "low" or "medium", pass the warning string to the display step for rendering.
2. Collect all DegradationReport objects from intake tool responses. Call buildSourceStatusReport() from lib/source-status.ts to aggregate into a SourceStatusReport. Pass to the display step for rendering between the header and cluster list.

Step 2: Normalize

For each ingested post:

• Parse into BugCandidate (all 33 fields) using lib/parser.ts
• Classify into 12 categories using lib/classifier.ts
• Redact PII (6 types) using lib/redactor.ts
• Score reporter reliability (4 dimensions) using lib/reporter-scorer.ts
• Tag reporter_category from config/approved-accounts.json

Step 3: Match Existing Clusters

• Load…