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 productsurface, featurearea, symptoms, errorstrings, reprohints
• Extract urls, media_keys, language, conversation references
• Determine sourcetype (mention, reply, quotepost, search_hit)

Step 1.5: Deduplicate

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

• Call deduplicateCandidates() with parsed candidates and the candidatededup.hybridsimilarity_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 piiflags array and rawtextstoragepolicy

Step 4: Score Reliability

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

• 4 dimensions: repo

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 mcptriagelookup_* 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():

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
• surfacerepomapping configured for every product_surface present in clusters
• Triage MCP server reachable for mcptriagesearchissues, mcptriageinspectrecentcommits, mcptriageinspectcodepaths, and mcptriagecheckrecent_deploys
• GitHub access tokens with read scope on the target repos

Instructions

Step 1: Select Repos

For each cluster:

1. Look up repos from surfacerepomapping 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 mcptriagesearchissues with the cluster's symptoms and errorstrings:

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

Step 3: Inspect Recent Commits

Call mcptriageinspectrecentcommits 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 mcptriageinspectcodepaths 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 mcptriagecheckrecentdeploys 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:

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

!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"