feat(rca): generic multi-client RCA agent plugin

[ruturaj-browserstack]

What this is

A portable Claude-Code/Cursor plugin that drives BrowserStack's collaborative
RCA loop (tfaRcaTurn) over all failed tests of a build — generic across
product and infra. It wraps the stable bstack MCP tools (listTestIds +
tfaRcaTurn) and adds the harness that batches RCA over a whole build, clusters
failures by signature, routes evidence requests to whatever skills/tools the
client already has, and records a per-test RCA.

Generalizes the product-/infra-coupled obs-tfa-rca skill: the loop, routing,
digest, and report core are ported; the coupling points (BrowserStack discovery,
fixed kubectl/chitragupta/bifrost, /tmp, server name) become config +
runtime capability discovery.

Companion change (separate repo, not in this PR): @browserstack/mcp-server
listTestIds gains an opt-in includeFailureDetail flag returning a trimmed
per-test failure signature — the seed for clustering with no extra probe turns.

Architecture

Three roles over the stable MCP contract:

• rca-build skill (build-level orchestrator) — mandatory pre-flight GitHub
  intake, discovery via listTestIds, the CSV/WAL state spine, failure-signature
  clustering, build-evidence pre-compute + capability manifest, and fan-out.
• ai-tfa-coordinator agent (per-test) — drives the tfaRcaTurn loop
  (turn-cap, one-thread, soft-PENDING, digest-not-dump); routes each ask by
  capability (no hardcoded tools); runs suspect-PR falsification.
• TFA (server-side, test-level) — owns the per-test logs, authors the RCA.

Two modes, one coordinator (only the injected gap-resolver differs):

• auto → workflows/rca-batch.mjs dynamic workflow (5 concurrent, no user
  input; gap → "unavailable" → best-effort finalize).
• interactive → subagents 5 at a time; on an evidence gap a subagent ends with
  a GAP_OUTPUT (resume handles) and the orchestrator asks the user, then
  re-dispatches with resume=.

Key decisions

• Clustering seeds off discovery, not probe turns — signature =
  normalize(category | first-error-line | file_path); representative runs the
  full loop, siblings pre-seed a one-turn confirm against their own logs, with a
  fall-back-to-own-loop safeguard (never blindly inherit).
• Evidence routing is config + capability manifest, never hardcoded tools.
• No GitHub forensics harness — references/github-evidence.md specifies the
  exact evidence needed; the coordinator uses GitHub MCP → gh → degrade.
• CSV is a write-ahead log (claim/heartbeat/flip + startup reaper) — in-session
  resumable; pending-resume rows stay re-claimable.
• Coverage stamp — TFA confidence capped by evidence coverage, so a RESOLVED
  built with evidence unavailable reads as lower confidence because of the gap.

In scope: ideation #1–#5 + the v1 slice of #6 (coverage stamp), #7 (resume), #8
(conformance fixture). Deferred: #6 blast-radius digest, #8 git-forensics-MCP,
cross-session durability, Codex/Gemini orchestration parity.

Testing

• 51 tests pass (npm test → node --test), dependency-free.
• Unit coverage: routing registry + manifest, CSV/WAL codec + claim/heartbeat/flip/
  reaper + flip-guard + pending-resume resumability, signature normalization +
  clustering, evidence cache, coverage band, report renderer.
• Conformance fixtures replay recorded tfaRcaTurn transcripts
  (resolved/blocked/pending/turn-cap) through the executable loop mirror
  (lib/loop.mjs, which doubles as the sequential thin-client harness) — proving
  rca capture, test_logs skip, soft-PENDING no-re-poll, turn-cap never submits a
  7th turn, and the degraded no-capability path still reaches a valid terminal RCA.
• workflows/rca-batch.mjs follows the documented Workflow runtime shape (meta +
  pipeline/parallel/agent); it's validated via the conformance fixtures and
  the unit-tested libs it relies on (the runtime DSL globals can't be unit-loaded).

Install / usage

git clone … && cd browserstack-ai-tfa-demo
cp .env.example .env   # BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY
claude --plugin-dir ./
/rca-build <build-id>

Post-Deploy Monitoring & Validation

No production/runtime impact — this is a client-side plugin (skills/agents/workflow

• a bundled MCP server config), not a deployed service. Validation is manual:
  run /rca-build against a known red build and confirm every failed test lands a
  terminal CSV row + a per-test RCA. The two things to validate live: the sibling
  one-turn-confirm cost win, and the "last green" baseline resolution (both have
  safeguards so correctness doesn't depend on them).

🤖 Generated with Claude Code