Coverage (Data-Completeness) Dots Everywhere — Implementation Plan

[OAGr]

Coverage Dots Everywhere — Implementation Plan (v2)

TL;DR

Wiki entities have wildly varying data depth but users have no at-a-glance signal when browsing. We'll extend the existing CoverageDots component (1-4 dot ladder) from 4 directory tables to all applicable tables, entity detail headers, and eventually search results via pre-computed dataDepth scores in database.json. Phase 1a adds coverage dots to 6 simple directory tables in one session. Critical finding: the generic scorer produces uniform scores (all 4s) for benchmarks and policies — per-type scorers with calibrated thresholds are mandatory, not optional.

Problem

Users browsing directory pages see no signal for content depth. The coverage dot system covers only 4 of 15+ directory tables and zero other surfaces. The wiki has ~3,800 entities with massive variation — some orgs have financial data, 10+ people, wiki pages, and verified facts; others have just a name. Without a visual indicator, users waste time clicking into stubs.

Current State

Asset	Status	Gap
CoverageDots component	Complete, tested	Only used in 4 tables
coverage-score.ts (5 scorers)	Complete, tested	Missing 7+ entity-type scorers; generic scorer produces uniform scores for structured types
Organizations table	Has "Data" coverage column	Scoring includes people + wiki page
People, AI Models, Legislation	Have Coverage column	Adequate scoring
11+ other directory tables	No coverage column	Need per-type scoring + column integration
Entity detail page headers	None	No shared header component
Search results	None	Needs pre-computed dataDepth in database.json
SourceCheckDot (precedent)	21 files, 7 PRs	Gold standard for pervasive rollout
Page coverage system	Complete (12+ items/page)	Build-time, in database.json — complementary

Complete Directory Page Inventory

Page	Architecture	Scorer	Phase	Include?
organizations	Custom + useServerTable	EXISTS	Done	✓
people	Custom + useServerTable	EXISTS	Done	✓
ai-models	Custom	EXISTS	Done	✓
legislation	Custom	EXISTS	Done	✓
projects	Custom	computeProjectCoverage	1a	✓
benchmarks	Custom	computeBenchmarkCoverage	1a	✓
grants	Custom paginated	computeGrantCoverage	1a	✓
funding-programs	Custom paginated	computeFundingProgramCoverage	1a	✓
funding-rounds	Custom paginated	computeFundingRoundCoverage	1a	✓
divisions	Custom	computeDivisionCoverage	1a	✓
approaches	Custom	Generic	1b	✓
events	Custom	Generic	1b	✓
publications	TanStack React Table	computePublicationCoverage	1b	✓
resources	TanStack React Table	computeResourceCoverage	1b	✓ if variance
research-areas	Custom	Generic	1b	✓
politicians	Custom	Exclude	—	✗ Niche type
races	Custom	Exclude	—	✗ Parent-child structure
data-sources	Dashboard	Exclude	—	✗ Meta-dashboard
risks	Listing page	Exclude	—	✗ No table component
investments	Inline in page.tsx	Defer	2+	✗ No table component

External Research: How Other Sites Handle This

Project	How	Key Lesson
Wikipedia	Quality grades (Stub→FA) on talk pages only. Readers see only stub notices and FA stars — NOT the full scale.	Show extremes to readers, full scale to editors.
Wikidata Recoin	Relative completeness vs. peers + list of missing properties. Opt-in gadget, not default.	Peer-relative scoring + "what's missing" is more actionable than raw counts.
LinkedIn	Profile strength meter visible only to profile owner, never to viewers. Disappears at completion.	Self-facing completeness meters ≠ reader-facing.
Crunchbase	No completeness indicator. Shows derived scores (Growth, Heat).	Mature data platforms don't expose raw completeness to readers.
Google Knowledge Panel	No explicit indicator. Panel presence/absence IS the signal.	Absence of sections communicates "not enough data" implicitly.
HubSpot/Salesforce	Completeness on admin dashboards only. Not on public-facing records.	Aggregate coverage metrics for editors; per-record indicators for internal tools.

Consensus across external research: Reader-facing quality indicators should be categorical (stub/comprehensive) rather than granular (1-4 scale). Full granularity belongs on internal dashboards. Wikipedia's stub notice is the strongest precedent — it surfaces only the low extreme, not a continuous scale.

UX Design Decision: Dots vs. Stub Badge

The red team's UX critic argued coverage is a "maintainer metric surfaced to readers." External research confirms this concern — no major knowledge platform shows granular completeness to readers.

Two viable approaches (user should decide):

Option A: 4-dot ladder on all surfaces (current plan)

• Pros: Granular, sortable, provides continuous signal
• Cons: When ~85% of orgs score 1-2, the column is dominated by low scores, communicating "most of our data is incomplete"
• Best for: An audience that understands data quality (researchers, grantmakers)

Option B: Binary "stub" badge + internal dot dashboard

• Reader-facing: Small "Stub" pill on score-1 entities only. No indicator on 2/3/4.
• Internal: Full 4-dot ladder on coverage dashboard (Phase 5)
• Pros: Minimal visual noise, follows Wikipedia/LinkedIn precedent
• Cons: Loses 2/3/4 discrimination on reader surfaces
• Best for: A general audience that might misinterpret dots as importance/quality ratings

This plan implements Option A (4-dot ladder) per the user's request, but the scoring infrastructure supports either approach. Switching to Option B requires only changing the rendering layer, not the scoring functions.

Critical Finding: Score Distribution Validation

Real entity score analysis revealed the generic scorer produces uniform scores:

Entity Type	Score Distribution	Variance	Issue
Organizations	1→3 range	✓ Good	—
Benchmarks	ALL score 4	✗ None	Generic scorer too permissive — all have 5+ fields
Policies	ALL score 4	✗ None	Same problem
Projects	Cluster at 3-4	~ Marginal	Only 2 distinct scores
Grants	2→4 range	✓ Moderate	—
Approaches	Cluster at 2	~ Marginal	Thin type, expected
Events	Cluster at 2	~ Marginal	Thin type, expected

Root cause: computeGenericCoverage caps filledFieldCount at 4 signals, but most structured entities have 5+ fields, pushing everything to score 4. The generic scorer is only appropriate for thin types (approaches, events) where the limited field set naturally produces variance.

Fix: Per-type scorers with calibrated thresholds are mandatory for any type with 5+ structured fields. The generic scorer's filledFieldCount cap should be reduced from 4 to 2.

Architecture

Scoring Layer

coverage-score.ts
├── computeOrgCoverage()              — EXISTS, good variance ✓
├── computePersonCoverage()           — EXISTS, good variance ✓
├── computeAiModelCoverage()          — EXISTS, good variance ✓
├── computeLegislationCoverage()      — EXISTS, needs threshold tuning
├── computeProjectCoverage()          — NEW: status + website + org + description + wikiId
├── computeBenchmarkCoverage()        — NEW: modelsCount(threshold) + category + maintainer + wikiId
├── computeGrantCoverage()            — NEW: amount + recipient + date + source + status
├── computeFundingProgramCoverage()   — NEW: budget + type + deadline + status + description
├── computeFundingRoundCoverage()     — NEW: raised + valuation + instrument + date + lead
├── computeDivisionCoverage()         — NEW: divisionType + status + hasData + parentHref
├── computePublicationCoverage()      — NEW: credibility + peerReviewed + resourceCount + pageCount
├── computeResourceCoverage()         — NEW: credibility + citingPageCount + tags + type
├── computeGenericCoverage()          — EXISTS, filledFieldCount cap reduced to 2

Integration Patterns (4 table architectures)

Pattern 1 — Simple custom table (projects, benchmarks, approaches, events):

// Import
import { CoverageDots } from "@/components/coverage/CoverageDots";
import { computeProjectCoverage } from "@/components/coverage/coverage-score";

// Header: add after last data column, before any action column
<th className="py-2.5 px-3 font-medium text-center">Coverage</th>

// Cell: compute inline from row fields
<td className="py-2.5 px-3 text-center">
  <CoverageDots score={computeProjectCoverage(row)} />
</td>

Pattern 2 — Table with SourceCheckDot (divisions, funding-programs, funding-rounds):

// SourceCheckDot stays inline with name (existing, unchanged)
// CoverageDots goes in a separate column BEFORE SourceCheckDot
<th className="py-2.5 px-3 font-medium text-center">Coverage</th>
// ...
<td className="py-2.5 px-3 text-center">
  <CoverageDots score={computeDivisionCoverage(row)} />
</td>

Pattern 3 — TanStack React Table (publications, resources):

// Add to ColumnDef array in makeColumns()
{
  accessorKey: "coverage",
  header: ({ column }) => <SortableHeader column={column}>Coverage</SortableHeader>,
  cell: ({ row }) => (
    <CoverageDots score={computePublicationCoverage(row.original)} />
  ),
},

Pattern 4 — Custom paginated (grants):

// Same as Pattern 1 but update colSpan in empty state
// After Status header:
<th className="py-2.5 px-3 font-medium text-center">Coverage</th>
// After Status cell:
<td className="py-2.5 px-3 text-center">
  <CoverageDots score={computeGrantCoverage(row)} />
</td>

Visual Design

Table column (size="sm", 6px dots):

| Entity Name        | Type    | Status | Coverage |
|--------------------+---------+--------+----------|
| Anthropic          | AI Lab  | Active | ●●●●     |   ← 4/4 comprehensive
| MIRI               | Nonprof | Active | ●●●○     |   ← 3/4 moderate
| SafeAI Inc         | Startup | Active | ●●○○     |   ← 2/4 basic
| NewOrg             | Other   |   —    | ●○○○     |   ← 1/4 stub

Entity header (size="md", 8px dots):

  [Avatar]  Anthropic  [AI Lab]  ●●●●
            Also known as: Anthropic PBC
            Founded Jul 2021 · HQ: San Francisco

Tooltip on hover: "Coverage: Comprehensive"
  Score 1 = "Stub"
  Score 2 = "Basic"  
  Score 3 = "Moderate"
  Score 4 = "Comprehensive"

Implementation Phases

Phase 1a: Simple directory tables — S (1 session)

Goal: 6 more directory tables show coverage dots. Users browsing projects, benchmarks, grants, funding programs, funding rounds, and divisions see at-a-glance content depth.

• Write 6 new per-type scoring functions: project, benchmark, grant, funding-program, funding-round, division
• Calibrate thresholds using real data — each scorer must produce ≥3 distinct score values across actual entities
• Write tests: empty → 1, partial → 2-3, full → 4 for each scorer
• Score distribution validation test: assert new Set(scores).size >= 3 across real entity samples
• Reduce computeGenericCoverage filledFieldCount cap from 4 to 2
• Add coverage column to 6 tables following the 4 integration patterns above
• For tables with SourceCheckDot: coverage column before SourceCheckDot
• Update colSpan constants in empty/loading states
• For tables with 7+ columns: hidden sm:table-cell

Quality gates:

• pnpm build passes
• Score distribution: ≥3 distinct values per type across real data
• Visual check: all 6 directory pages render dots correctly
• Dual-dot tables (divisions, funding-programs, funding-rounds): verify two dot systems aren't visually confusing
• E2E: pnpm exec playwright test apps/web/e2e/directory-pages.spec.ts

Exit criteria: 10 of 15+ directory tables show coverage dots with meaningful variance.

Phase 1b: TanStack tables + thin types — S (1 session)

Goal: Complete directory table coverage.

• Write scorers for publications and resources
• Add coverage to TanStack tables using columnHelper.display() pattern
• Add coverage to approaches, events, research-areas using generic scorer
• For tables where >80% score identically: hide by default via column picker

Exit criteria: All applicable directory tables show coverage dots or have documented exclusion rationale.

Phase 2: Entity detail page headers — S (1 session)

Goal: Entity detail pages show coverage in the header area.

• Add CoverageDots size="md" inline with type badge on org detail page (~line 760 in organizations/[slug]/page.tsx)
• Add to person detail page header
• Add to legislation detail page header
• Tooltip shows label (Stub/Basic/Moderate/Comprehensive)

Exit criteria: Org, person, legislation detail pages show coverage dots in header.

Phase 3: Build-time pre-computation — M (1-2 sessions)

Goal: dataDepth (1-4) pre-computed for every entity in database.json, enabling search and wiki surfaces.

• Add dataDepth computation to build-data.mjs: iterate entities, call appropriate scorer
• Store alongside quality and importance (existing pattern)
• Create data/entity-coverage.ts: getEntityDataDepth(entityId): number | null
• Log score distribution at build time; warn if any type has >80% uniform
• Build time increase <5 seconds

Exit criteria: dataDepth in database.json for all scored types.

Phase 4: Search results — S (1 session)

Goal: Search results show coverage dots for entity results.

• Read dataDepth from pre-computed data
• Add CoverageDots size="sm" in ResultRow below entity title, before description
• Only show for entity results with dataDepth available
• Note: UX risk of bias toward well-documented entities — keep dots non-prominent

Exit criteria: Entity search results show coverage dots.

Phase 5: Dashboard + tooltip (optional) — M (1-2 sessions)

Goal: Maintainers see site-wide coverage distribution; power users see breakdown on hover.

• Coverage dashboard (Pattern A): distribution by type, lowest-coverage entities, averages
• CoverageBreakdown popover (shadcn Popover) showing dimensional breakdown
• Register in internal sidebar

Exit criteria: Dashboard live; popover shows per-dimension detail.

Parallelization Plan

The work fans out after a single-file bottleneck (coverage-score.ts). Here's how to use multiple agent slots:

Wave 0: Ship foundation (1 slot — current branch claude/coverage-dots)
  CoverageDots component + 4 existing table integrations
  Must merge first — everything builds on this.
       │
       ▼
Wave 1: ALL scorers (1 slot, 1 PR — CRITICAL PATH)
  Write all 8 new scoring functions + tests + fix generic threshold
  Single file (coverage-score.ts) = cannot parallelize.
       │
       ├──────────────┬──────────────┬──────────────┐
       ▼              ▼              ▼              ▼
Wave 2a            Wave 2b        Wave 2c        Wave 2d
projects           grants         divisions      publications
benchmarks         funding-progs  events         resources
approaches         funding-rounds research-areas (TanStack)
(3 tables)         (3 tables)     (3 tables)     (2 tables)
       │              │              │              │
       └──────────────┴──────────────┴──────────────┘
       │
       ├──────────────┐
       ▼              ▼
Wave 3a            Wave 3b
Phase 2: headers   Phase 3: build-time precompute
(org, person, leg) (dataDepth in database.json)
       │              │
       │              ├──────────────┐
       │              ▼              ▼
       │           Wave 4a        Wave 4b
       │           Phase 4:       Phase 5:
       │           search results dashboard+tooltip
       └──────────────┴──────────────┘

Why this order

Wave	Slots	Parallelize?	Rationale
0	1	No	Foundation PR — ships component + base scorers
1	1	No — single file bottleneck	ALL scorers in coverage-score.ts. Split across slots = merge conflicts.
2	4 parallel	Yes	Each slot touches only its own table files. Zero shared files.
3	2 parallel	Yes	Headers ([slug]/page.tsx) vs build pipeline (build-data.mjs) — independent.
4	2 parallel	Yes	Search (search-client.tsx) vs dashboard (internal/entity-coverage/) — independent. Both depend on Wave 3b.

Conflict-free slot file assignments

Wave 2a: projects-table.tsx, benchmarks-table.tsx, approaches-table.tsx
Wave 2b: grants-table.tsx, funding-programs-table.tsx, funding-rounds-table.tsx
Wave 2c: divisions-table.tsx, events-table.tsx, research-areas-table.tsx
Wave 2d: publications-table.tsx, resources-table.tsx (TanStack pattern)

Each slot also touches its corresponding page.tsx — all slot-exclusive, zero overlap.

Timeline estimate

Wave	Work	Sessions	Calendar
0	Ship current branch	0.5	Day 1
1	All scorers + tests	1	Day 1-2
2	11 table integrations (4 parallel)	1 each	Day 2-3
3	Headers + build-time (2 parallel)	1 each	Day 3-4
4	Search + dashboard (2 parallel)	1 each	Day 4-5

With parallelization: ~5 calendar days, ~9 slot-sessions.
Without parallelization: ~7-8 sessions sequential.

Scope Cuts

• Historical trend tracking — Use existing data-quality-snapshots if needed.
• Politicians, races, data-sources, risks, investments — Excluded per inventory table.
• Wiki page sidebar — Entity pages already show PageStatus.
• Gap prompts ("Add revenue data") — Deferred, could enhance tooltip later.
• Entity matrix coupling — Explicitly avoid. dataDepth is independent.
• Server-mode score parity — Accepted as approximate (missing some fields).
• Option B (stub badge) — Infrastructure supports switching later if dots prove too noisy.

Quality & Verification

Area	Plan
Tests	Per-type scorer tests: empty→1, partial→2-3, full→4. Distribution validation: real entity samples, ≥3 distinct values per type.
Migration	After Phase 1b: grep all directory tables, confirm coverage status vs. inventory table.
Smoke test	Load each affected directory page in dev; spot-check 3+ tables with varied data.
UI verification	Each table at 375px/768px/1440px. Dual-dot tables: verify not confusing.
Deploy	Pure frontend — no env vars, migrations, or post-deploy steps.
Documentation	Update CLAUDE.md directory table. Comment block in coverage-score.ts listing scorer inventory.
Monitoring	Build-time distribution log (Phase 3). Dashboard (Phase 5).

Risks & Mitigations

Risk	Severity	Mitigation
Generic scorer produces uniform scores	Blocking	Per-type scorers mandatory for structured types. Distribution validation gates each phase. Fixed filledFieldCount cap (4→2).
85% of entities score 1-2, communicating "site is incomplete"	Significant	Per-type calibration to spread scores. Option B (stub badge) available as fallback.
Two dot systems confuse visitors	Moderate	Distinct visual (4 teal vs 1 colored). Separate columns. Clear headers.
Phase 1a scope	Moderate	Batched into 1a (simple) + 1b (TanStack).
Search result bias toward 4-dot entities	Moderate	Phase 4 keeps dots small and non-prominent.
Score ≠ importance (1-dot entity might be very important)	Moderate	Coverage and importance are separate signals. Dots measure data depth, not entity significance.
Entity matrix anti-pattern	Minor	dataDepth = ONE number per entity. <20 lines per scorer. No framework.

Open Questions

1. 4-dot ladder vs. stub badge for reader-facing surfaces? External research supports the badge approach. Current plan uses dots per user request. Decision should be revisited after Phase 1a ships and real user feedback is available.

2. Column naming: "Coverage" vs "Data"? Org table uses "Data". New tables use "Coverage". Should unify. "Coverage" is more descriptive but "Data" is shorter.

3. Entity types without directory pages in search (Phase 4)? Risks (450), concepts (108), capabilities (56) appear in search but have no scorer. Use generic with calibrated thresholds.

Rejected Approaches

• Entity Health Gauge — Merging coverage + source-check loses distinct meanings.
• Peer Percentile — Hides absolute quality; poorly-documented site still shows 90th-percentile entities.
• Coverage Genome — 13-cell heatmap too dense for tables/mobile.
• Entity Matrix — 35×32 = 2,374 unmaintainable lines, 0 tests. dataDepth avoids this.
• All-generic scoring — Produces uniform scores for structured types (validated with real data).

Red Team Log

Round 1 — 17 issues (2 blocking, 8 significant, 7 minor)

Technical: (Blocking) Plan omitted 6+ directory pages → fixed with complete inventory. (Blocking) Search results lack entity data → reordered phases: build-time before search. (Significant) 8 scorers excessive → 7 specific + generic for thin types. (Significant) Phase 1 underscoped → split into 1a/1b. (Significant) No score distribution validation → added as quality gate.

UX: (Significant) Coverage is maintainer metric surfaced to readers → acknowledged, documented Option B as fallback. (Significant) Two dot systems confuse → visually distinct, separate columns. (Significant) Search bias → keep dots small. (Minor) Entity header utility low → kept Phase 2 but scoped to 3 types.

Scope: (Significant) Phase 4 risks entity matrix anti-pattern → constraint: ONE number, not matrix. (Significant) Dashboard redundant → made Phase 5 optional.

Round 2 — Revision + implementability

Reframing insight: dataDepth as build-time metadata (like quality/importance) is the right end-state. Phases 1-2 compute inline; Phase 3 pre-computes for search.

Round 3 — Deep-dive findings (5 targeted investigations)

External research: Wikipedia, Wikidata, LinkedIn, Crunchbase all avoid showing granular completeness to readers. Wikipedia shows only extremes (stub notice, FA star). Consensus: categorical signals > continuous scales for reader-facing UI.

Code patterns: 4 distinct table architectures documented with exact integration patterns and line numbers.

Score distribution (CRITICAL): Generic scorer produces ALL 4s for benchmarks and policies. Root cause: filledFieldCount cap too permissive. Fix: per-type scorers mandatory; reduce generic cap from 4 to 2.

UX validation: Coverage most useful for grantmakers (high) and researchers (moderate). Risky for students (may discourage exploring stubs). Recommendation: keep dots but be prepared to switch to stub badge if real usage data supports it.

[OAGr]

Branch: claude/deploy-tasks-verify-cmd

Renamed title to disambiguate from verification dots. This discussion is about data-completeness (1-4 dot ladder showing how much structured data an entity has). Verification dots (showing whether records are source-checked) are tracked separately in #3802. Per discussion review on 2026-04-08.