analytics-rerank

name	analytics-rerank
description	Pick a tea-rags rerank preset, build a `{custom: {...}}` weight set, or

Analytics Rerank

Rerank reorders search results by git + structural signals. Deep-dive: pick preset, build custom weight set, apply recipe for a specific analytics question.

Rerank decision tree

Documentation search? (language: "markdown" OR documentation: "only")
├─ Yes → no explicit rerank needed
│     → facade auto-applies "documentationRelevance" preset
│     → heading-weighted ranking is automatic
│     Optimal flow for navigating docs:
│       1. find_symbol(relativePath: "docs/file.md") — TOC of one doc, OR
│          hybrid_search/semantic_search with pathPattern: "docs/**" — to
│          discover which doc covers a topic
│       2. find_symbol(symbol: "doc:<parentHash>") — drill into a specific
│          section taken from search result's parentSymbolId or from the TOC
│       3. Read — only when you need continuous prose spanning many sections
│
└─ No → continue to preset selection

Existing preset fits the analytics question?
├─ Yes → use it. Read tea-rags://schema/presets for the full catalog with
│         weights and tools each preset is registered on.
│
└─ No → build custom weights. Read tea-rags://schema/signals for the
         canonical weight-key catalog (it is generated from the live
         registry; never invent weight key names from memory).

Catalogs — always read on demand

Canonical sources, generated from live registry of THIS build. Memorized training-data lists WILL drift.

ReadMcpResourceTool(server: "tea-rags", uri: "tea-rags://schema/presets")
ReadMcpResourceTool(server: "tea-rags", uri: "tea-rags://schema/signals")
ReadMcpResourceTool(server: "tea-rags", uri: "tea-rags://schema/signal-labels")

schema/presets = full preset list with weights + tools. schema/signals = every weight key for {custom: {...}} mode. schema/signal-labels = how numeric overlay values map to labels (healthy / concerning / critical, etc.) per signal.

Preset cheat sheet (when each is the right pick)

Catalog has full list; this is routing tier.

Question	Preset
"Where are the bug-prone areas in domain X?"	hotspots
"Old + churny + bug-fixed legacy in domain X?"	techDebt
"Single-author silos / bus factor in domain X?"	ownership
"Review the recent changes in this area"	codeReview (with maxAgeDays: 7)
"Old code in security-sensitive paths"	securityAudit (with pathPattern: "**/auth/**")
"Recently modified, sprint-review style"	recent
"Stable, low-bug template code"	proven / stable
"Refactor candidates by size+volatility+bug-fix history"	refactoring
"Bug-prone + volatile + high blast radius"	dangerous
"Find candidates to decompose"	decomposition
"Blast radius before a change (real call edges)"	blastRadius (codegraph on) — else custom { imports: 0.5, churn: 0.3, ownership: 0.2 }
"Structural backbone — high-fan-in hubs"	architecturalHub (codegraph)
"Entry points / flow drivers of a scope"	entryPoint (codegraph)

Codegraph composites (blastRadius / architecturalHub / entryPoint) rank on real call/import edges (fanIn, isHub, fanOutPerLine). Meaningful only when prime ## Enrichment lists codegraph.symbols; codegraph off → they degrade to similarity — fall back to imports-proxy custom weights, say centrality is approximate. See search-cascade "Graph navigation".

Custom weight recipes

No preset fits exactly → combine weight keys from tea-rags://schema/signals. Format:

{ "rerank": { "custom": { "<weightKey>": <number>, ... } } }

Negative weights penalize a signal. Magnitudes not absolute — reranker normalizes per-query. Keep total magnitude ≈ 1.0 for sane ranking.

Fragile Silo (looks stable, breaks a lot, single-author)

{
  "rerank": {
    "custom": {
      "bugFix": 0.45,
      "knowledgeSilo": 0.3,
      "similarity": 0.15,
      "churn": -0.1,
    },
  },
  "metaOnly": true,
}

Surfaces files with bugFixRate concerning+ + single live-line owner (knowledgeSilo ≈ 1.0), despite low commit count (churn negative weight penalizes high-churn files — want the SILENT fragile, not the obvious churner). Files whose commitCount falls below confidence-clamp thresholds get bugFixRate.label clamped to healthy — do NOT classify as Fragile silo even if raw value high. Correct behavior of the unified confidence mechanism.

Impact analysis (blast radius before a change)

{
  "rerank": {
    "custom": {
      "imports": 0.5,
      "churn": 0.3,
      "ownership": 0.2,
    },
  },
  "metaOnly": true,
}

High imports = many files import this = wide blast radius. churn included: high-churn high-import files are the genuine danger ("everyone depends on this AND it keeps changing"). ownership surfaces single-owner high-impact files — knowledge silo with reach.

Prefer the blastRadius preset when codegraph is on: ranks on real fanIn (actual call/import edges) + churn + bugFix, not the raw imports-line proxy. Use this custom recipe only as the codegraph-off fallback (result then approximate — import-proxy, not edge truth).

Active driver concentration (who's mentally loaded right now)

{
  "rerank": {
    "custom": {
      "recentActivityConcentration": 0.5,
      "burstActivity": 0.3,
      "similarity": 0.2,
    },
  },
}

Different from ownership. recentActivityConcentration = commit-window based (recent committers), ownership = blame-based (live-line owners). Use for review routing / "who's driving this area in the current sprint", not authority questions.

Security-sensitive legacy

{
  "rerank": {
    "custom": {
      "age": 0.3,
      "pathRisk": 0.3,
      "bugFix": 0.2,
      "ownership": 0.1,
      "volatility": 0.1,
    },
  },
  "pathPattern": "**/auth/**",
}

pathRisk = structural signal flagging security-sensitive paths (auth, crypto, etc.). Combined with age + bug-fix history, surfaces "old code in a critical path that still gets bug-fixed" — prime audit target.

Reading the overlay back

Every reranked result carries rankingOverlay.derived (normalized 0-1 signal contributions) + rankingOverlay.raw.{file,chunk} (raw payload values with labels). Read references/runtime-introspection.md for the structure, references/signal-interpretation.md for pair diagnostics disambiguating single-signal ambiguity (god module vs bug attractor, healthy owner vs toxic silo, legacy minefield vs proven stable).

Project calibration

Thresholds vary by codebase. commitCount of 8 is "high" in one project, "typical" in another. Call get_index_metrics(project: "<alias>"), read signals[language][signalKey][scope].labelMap for THIS project's percentile-based thresholds before phrasing a filter or weight in absolute numbers. See references/runtime-introspection.md for the calibration recipe.

When this skill does NOT apply

• Multi-dimensional cross-preset risk scan (overlap across 4 presets to classify tiers) → use tea-rags:risk-assessment. This skill = single preset or single custom weight set.
• Root-cause investigation of a concrete bug symptom → use tea-rags:bug-hunt.
• Picking filter shape (typed sugar vs raw filter, level=file vs chunk) → use tea-rags:filter-building.
• Generic exploration of unfamiliar code → use tea-rags:explore.

For rerank selection + custom weight composition, stay here.