feat(team-summary): team comparison view with three impact strategies (GLOOK-4)

[msogin]

Summary

Implements GLOOK-4: a new Teams tab on /report/[id]/team that compares teams against each other using the same impact dimensions as the IC table. Adds three impact columns (Weighted / Avg / Total) and full column parity with the Individuals table.

Spec: docs/superpowers/specs/2026-05-19-glook-4-team-comparison-design.md
Plan: docs/superpowers/plans/2026-05-19-glook-4-team-comparison.md

Impact formulas

For each team, three numbers — all derived from the existing IC computeImpactScore formula, no new weights:

• (W) Weighted — per-capita-then-apply. Default sort. Divide additive metrics (commits, PRs, jira, reviews) by the authoritative team size from team_members, then run the IC formula. Inactive members still dilute per-capita — by design.
• (A) Avg. Arithmetic mean of active developers' impact scores.
• (T) Total — sum-then-apply. IC formula applied to team-level sums. Useful context but saturates fast (the IC formula's min(x/N, 1) caps engage at single-developer scale).

Brainstormed against real data from your latest report — scripts/team-impact-poc.ts was used to compare strategies side-by-side on real team rollups. (W) was the most defensible primary sort: it differentiates between teams without inflating large teams or unfairly rewarding small teams.

Architecture

• Pure client-side aggregation. The page already fetches /api/report/[id] (devs) and /api/teams?org=<org> (team members). A new pure function aggregateTeams(developers, teams) → TeamRow[] runs inside a useMemo and feeds a new <TeamTable /> component. No new API endpoint, no DB migration.
• computeImpactScore extracted to src/lib/impact-score.ts so server (per-dev impact at report run time) and client (team-level impact) call the same function. No drift.

UI

• Tab strip on the existing page, styled identically to /report/[id]/org. URL state ?view=individuals | teams, default individuals — existing bookmarks unaffected.
• Column parity with the IC table: Team, Size, Active (with −N indicator when inactive), PRs, Commits, Lines +/−, Cmplx, PR%, AI%, Jira (conditional), Spend (admin-only, conditional), Impact W/A/T.
• Every column header is a sort button with ▲/▼ caret. Default sort is Impact (W) desc. Sort state is URL-stated (?sort=…&dir=…) so it survives page reload and shareable links.
• Row click drills back to the Individuals view filtered to that team — sets both team (drives TeamPulseCard) and dev (drives the dev-filter chips and table) URL state, mirroring the existing dropdown behavior.

Files

• New src/lib/impact-score.ts — extracted computeImpactScore (function move, no logic change).
• New src/lib/teams/team-aggregator.ts — aggregateTeams(developers, teams) pure function.
• New src/app/report/[id]/team/team-table.tsx — <TeamTable /> component.
• New src/lib/__tests__/unit/impact-score.test.ts — pinned numeric assertions on the extracted formula.
• New src/lib/__tests__/unit/team-aggregator.test.ts — 15 tests covering sum aggregation, weighted ratios, type/repo aggregations, the three impact strategies, single-member team invariant (W = T), multi-team membership, no-team devs, orphan team skip.
• New scripts/team-impact-poc.ts — one-off used during brainstorming to compare formulas against real data; useful for future formula tweaks.
• New spec at docs/superpowers/specs/2026-05-19-glook-4-team-comparison-design.md.
• New plan at docs/superpowers/plans/2026-05-19-glook-4-team-comparison.md.
• Modified src/lib/aggregator.ts — re-export computeImpactScore from the new module so existing callers stay unchanged.
• Modified src/app/report/[id]/team/page.tsx — ?view= URL state, tab strip, conditional render, hide filter dropdown + dev-search + TeamPulseCard on Teams view.

Tests

• npm test → 62 suites / 647 tests pass.
• npx tsc --noEmit -p tsconfig.json → clean.
• The two pure modules are fully unit-tested (16 tests on impact-score + 15 on team-aggregator). UI smoke happened locally per the plan's Task 10 checklist.

Known caveats (documented in spec)

• Single-member team: W = T holds exactly (per-capita-with-size-1 collapses to total). A may differ by ≤0.5 because the persisted impact_score was computed with totalStoryPoints which isn't exposed via /api/report. Tolerable for v1; smallest follow-up fix is adding total_story_points to the report SELECT.
• Devs in multiple teams contribute to each team's totals (no de-duping in v1). Documented via tooltip on the Team column.
• Period-over-period trend arrow on team row is deferred to v2.

Test plan

• Open /report/{id}/team — defaults to Individuals tab, no behavior change.
• Click Teams tab — table swaps to one row per team, sorted by Impact (W) desc.
• Click column headers — sort flips direction (caret toggles).
• Reload the page on ?view=teams&sort=total_commits&dir=desc — sort preserved.
• Click a team row — URL updates to ?view=individuals&team=<name>&dev=<login>&dev=<login>…; IC view filters to those members; TeamPulseCard appears.
• Teams with inactive members show N −M in Active column.
• Spend column hidden for non-admins; Jira column hidden if no team has Jira issues.

🤖 Generated with Claude Code

[msogin]

Review findings — 4 suggested fixes, 1 question

Reviewed production code only. Tests pass, TypeScript clean, architecture is sound. Four issues worth addressing before merge:

I1 — teams as AggregatorTeam[] cast bypasses TypeScript

File: src/app/report/[id]/team/page.tsx

The local Team interface ({ id, name, members }) is missing color: string, which AggregatorTeam requires. The cast papers over the gap. Fix: add color: string to the local Team interface, remove the cast.

I3 — Teams SWR waterfall renders false "No teams configured" during load

File: src/app/report/[id]/team/page.tsx

The teams SWR key depends on org from the first SWR. During the window between activeReport resolving and teamsData resolving, teams=[] so aggregateTeams returns [] and the empty-state message fires incorrectly.

Fix: change the TeamTable render condition from:
{view === "teams" && activeReport && ...}
to:
{view === "teams" && activeReport && teamsData !== undefined && ...}

No loading placeholder needed — this is a fast sequential same-origin fetch.

S1 — cc_total_cost in SORT_KEYS but column hidden for non-admins

File: src/app/report/[id]/team/team-table.tsx

A non-admin opening a shared link with ?sort=cc_total_cost sees the table sorted by an invisible column with no sort caret.

Fix: const effectiveSortKey = (!hasSpend && sortKey === "cc_total_cost") ? "impact_weighted" : sortKey; — use effectiveSortKey in sortedRows useMemo and sortCaret.

S2 — Lines +/- column missing toLocaleString

File: src/app/report/[id]/team/team-table.tsx

IC table uses toLocaleString() for line counts; team table does not. On high-volume orgs team totals exceed 50k.

Fix: row.lines_added.toLocaleString() and row.lines_removed.toLocaleString()

Question (S8)

team-aggregator.ts: If team.members contains a duplicate login, devByLogin.get deduplicates silently but team.members.length (used as teamSize) is inflated, deflating impact_weighted without any signal. Is member-list uniqueness guaranteed by the server?

Phase 1 flags (non-blocking)

• scripts/team-impact-poc.ts (163 lines): PR description calls it "one-off used during brainstorming." Consider whether it belongs merged to main.
• docs/superpowers/plans + docs/superpowers/specs (1290 lines combined): planning artifacts that go stale post-merge. The PR description already captures the rationale — consider Confluence/Jira instead of source control.

[msogin]

Review findings for PR 42 - see summary below

[msogin]

Review findings — 4 fixes, 1 question

Reviewed production code only (, , , , ). Tests pass, TypeScript clean, architecture sound. Four issues before merge:

---

I1 — teams as AggregatorTeam[] cast bypasses TypeScript

File: src/app/report/[id]/team/page.tsx

Local Team interface is missing color: string, which AggregatorTeam requires. The cast papers over the gap — if color is absent, style={{ background: row.color }} silently renders nothing.

Fix: Add color: string to the local Team interface, remove the as AggregatorTeam[] cast.

---

I3 — Teams SWR waterfall renders false "No teams configured" during load

File: src/app/report/[id]/team/page.tsx

The teams SWR key depends on org from the first SWR. During the window between activeReport resolving and teamsData resolving, teams=[] → aggregateTeams returns [] → the empty-state message fires incorrectly.

Fix: Gate TeamTable on teamsData having resolved:

// was:
{view === "teams" && activeReport && ( <TeamTable ... /> )}
// becomes:
{view === "teams" && activeReport && teamsData !== undefined && ( <TeamTable ... /> )}

No loading placeholder needed — this is a fast sequential same-origin fetch.

---

S1 — cc_total_cost in SORT_KEYS but column hidden for non-admins

File: src/app/report/[id]/team/team-table.tsx

A non-admin opening a shared link with ?sort=cc_total_cost sees a table sorted by an invisible column with no caret.

Fix:

const effectiveSortKey = (!hasSpend && sortKey === "cc_total_cost") ? "impact_weighted" : sortKey;
// use effectiveSortKey in sortedRows useMemo and sortCaret

---

S2 — Lines +/- column missing .toLocaleString()

File: src/app/report/[id]/team/team-table.tsx

IC table uses toLocaleString() for line counts; team table does not. Team totals on high-volume orgs easily exceed 50k.

Fix: +{row.lines_added.toLocaleString()} / −{row.lines_removed.toLocaleString()}

---

Question (S8)

team-aggregator.ts: If team.members contains a duplicate login, devByLogin.get deduplicates silently but team.members.length (used as teamSize) is inflated — deflating impact_weighted with no signal. Is member-list uniqueness guaranteed by the server?

---

Phase 1 flags (non-blocking, team judgment call)

• scripts/team-impact-poc.ts (163 lines): PR says it's a "one-off used during brainstorming" — does it belong in main?
• docs/superpowers/plans + docs/superpowers/specs (1,290 lines): planning artifacts that go stale post-merge. PR description already captures the rationale — consider Confluence/Jira instead.