Work Summaries

1. Context

Leadership has no unified view of what happened over any given period. Activity is spread across five separate systems: Claude Code sessions in Cloudflare D1, task activity in Supabase, git history in GitHub, image generation in public.images, Gmail inbound/outbound, plus Cloudflare deploy events and backup logs.

Goal

An on-demand Work Summary page on the intranet where any authorized user can generate a structured summary for any time range. Each summary:

1. Shows an org-level "what we accomplished" section — headline and 3–5 bullets.
2. Offers two view modes: By Person (each contributor's activity) and By Surface (by area of the product/org, with attribution).
3. Includes an AI explanation strip on every section: a plain-English sentence or two on what was accomplished, not just what happened — powered by a lightweight Haiku pass.
4. Provides traceability: every activity item links to its source record where possible (GitHub commit, Supabase task, session, etc.).
5. Collects feedback reactions per-section to drive a self-improving prompt loop.

2. Architecture

3. Data sources

Same 9 sources as the original plan. Queries now accept start_at / end_at parameters (TIMESTAMPTZ) instead of midnight-to-midnight, enabling arbitrary ranges like "last 4 hours" or "last 30 days".

Surface area mapping

How raw sources become the By Surface view:

Cloudflare deploy events are classified as Development or Infrastructure by the Sonnet synthesis pass based on the deploy's project name. Source registry stored in public.work_summary_sources.

4. Database schema

Migration: apps/control/migrations/20260507_work_summaries.sql. Four tables:

-- One row per generated report
CREATE TABLE public.work_summaries (
  id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  start_at         TIMESTAMPTZ NOT NULL,
  end_at           TIMESTAMPTZ NOT NULL,
  title            TEXT,             -- e.g. "Last 24 hours · 7 May 2026" (auto-generated)
  raw_data         JSONB,
  review           JSONB,            -- org_summary + contributor_sections[] + surface_sections[]
  generated_by     UUID REFERENCES public.app_users(id),
  agent_cost_usd   REAL,
  template_version TEXT,
  created_at       TIMESTAMPTZ DEFAULT now()
);

review JSONB shape

{
  "org_summary": {
    "headline": "string",
    "bullets": ["string × 3-5"],
    "period_label": "Last 24 hours"
  },
  "contributor_sections": [{
    "contributor_name": "string",
    "contributor_id": "uuid|null",
    "personal_summary": "string (Haiku, 1-2 sentences)",
    "activity_groups": [{
      "source": "git_commits",
      "label": "3 commits to mobile",
      "ai_explanation": "string (1-3 sentences)",
      "items": [{ "description": "string", "link": "url|null" }]
    }]
  }],
  "surface_sections": [{
    "surface": "development",
    "label": "Development",
    "ai_explanation": "string",
    "activity_groups": [{
      "contributor": "string",
      "label": "string",
      "items": [{ "description": "string", "link": "url|null" }]
    }]
  }],
  "source_errors": ["string"]
}

-- Feedback per section
CREATE TABLE public.work_summary_feedback (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  summary_id    UUID REFERENCES public.work_summaries(id) ON DELETE CASCADE,
  feedback_type TEXT NOT NULL CHECK (feedback_type IN ('reaction', 'free_text')),
  section_key   TEXT,
  rating        TEXT CHECK (rating IN ('too_much', 'just_right', 'need_more', 'skip')),
  note          TEXT,
  reviewer_id   UUID REFERENCES public.app_users(id),
  processed     BOOLEAN DEFAULT false,
  created_at    TIMESTAMPTZ DEFAULT now()
);

-- Single-row instructions — the live prompt the edge fn reads
CREATE TABLE public.work_summary_instructions (
  id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  current_prompt   TEXT NOT NULL,
  template_version TEXT NOT NULL DEFAULT '1.0.0',
  history          JSONB DEFAULT '[]',  -- [{version, prompt, changed_at, reason}]
  last_updated_at  TIMESTAMPTZ DEFAULT now()
);

-- Source registry
CREATE TABLE public.work_summary_sources (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  source_key      TEXT UNIQUE NOT NULL,
  display_name    TEXT NOT NULL,
  surface         TEXT,   -- development | communications | tasks | assets | infrastructure
  is_active       BOOLEAN DEFAULT true,
  query_config    JSONB,
  last_active_at  TIMESTAMPTZ,
  auto_discovered BOOLEAN DEFAULT false,
  notes           TEXT,
  created_at      TIMESTAMPTZ DEFAULT now()
);

5. AI summarization — two-pass approach

Pass 1 — Claude Sonnet (main synthesis)

• Reads work_summary_instructions.current_prompt at runtime
• Receives raw source data for the requested range
• Outputs structured JSON: contributor_sections[], surface_sections[], raw_data
• Adaptive rules: skip zero-activity sections, compress routine (e.g. 30 CI bumps → one line), surface notable events, lead with highest-signal item

Pass 2 — Claude Haiku (explanation, parallel)

• One call per activity group in each section, run in parallel
• Input: group label + item list
• Output: ai_explanation — 1–3 sentences in plain language on what this accomplished
• Also generates: personal_summary per contributor, ai_explanation per surface section
• Separate call: org_summary.headline + org_summary.bullets (3–5 bullets)

Example explanations

• "3 commits to mobile" → "Fixed the LiveKit audio scope bug that was causing crashes on Android emulator."
• "2 Cloudflare deploys" → "Deployed the updated intranet search feature to production."
• "12 task activity events" → "Moved the Work Summaries feature through planning and into the spec-revision phase."

6. Intranet UI

New section "work-summaries" added to apps/control/src/types/intranet.ts.

Routes

src/app/[lang]/(intranet)/work-summaries/page.tsx       → list + generate form
src/app/[lang]/(intranet)/work-summaries/[id]/page.tsx  → summary detail view

Generate form (top of list page)

• Start / End <input type="datetime-local"> — follows the sessions-tab.tsx date filter pattern
• Quick-select buttons: Last 24h, Last 7 days, Last 30 days — pre-fill the range
• "Generate Work Summary" button → POST to edge fn → spinner overlay → redirect to /work-summaries/[id] on completion

Detail page layout

[Org Summary card — always visible at top]
  Headline
  • Bullet 1
  • Bullet 2
  • Bullet 3

[View toggle: By Person | By Surface]   ← sub-tabs.tsx URL pattern, amber underline

[By Person view]
  [Contributor card — expandable]
    AI personal summary (1–2 sentences)     ← ai-explanation-strip
    [Activity group card]
      [AI explanation strip]  "What this accomplished…"
      ▸ item 1 with trace link
      ▸ item 2 with trace link

[By Surface view]
  [Surface card — expandable]
    AI surface summary                      ← ai-explanation-strip
    [Activity group card — per contributor]
      [AI explanation strip]
      ▸ item 1 with trace link (Contributor: Name)

[Feedback — bottom of page]
  Per-section reaction bar (too_much | just_right | need_more | skip)
  Free-text feedback box

Components

src/components/work-summaries/
  summary-list.tsx          → card grid of past summaries
  generate-form.tsx         → date inputs + quick-select + Generate button + async state
  org-summary-card.tsx      → headline + bullet points
  contributor-view.tsx      → renders contributor_sections[]
  surface-view.tsx          → renders surface_sections[]
  activity-group-card.tsx   → shared: ai_explanation strip + expandable items + trace links
  ai-explanation-strip.tsx  → reusable callout band
  reaction-bar.tsx          → too_much | just_right | need_more | skip
  free-response-box.tsx     → open text + submit → feedback_type='free_text'

7. Edge functions

generate-work-summary/

Called by the intranet UI. Runs the two-pass synthesis and stores the result.

• Validates start_at, end_at, generated_by
• Queries all is_active = true sources in parallel (Gmail MCP, sessions MCP, Bash git log, Supabase, CF API)
• Continues on individual source failure; records failures in source_errors[]
• Sonnet synthesis pass → Haiku explanation pass (parallel) → INSERT into work_summaries
• Returns {id} immediately; status polled via a lightweight status endpoint

update-summary-instructions/

Triggered by Supabase webhook on work_summary_feedback INSERT. Same self-improvement design as the original plan.

• Reads all processed = false feedback for the relevant summary
• Calls Claude API: current_prompt + feedback → revised prompt + change summary
• Archives old prompt in history JSONB; bumps template_version
• Marks processed feedback as processed = true

8. Files to create / modify

New files

apps/control/migrations/20260507_work_summaries.sql
apps/control/supabase/functions/generate-work-summary/index.ts
apps/control/supabase/functions/update-summary-instructions/index.ts
apps/control/src/app/[lang]/(intranet)/work-summaries/page.tsx
apps/control/src/app/[lang]/(intranet)/work-summaries/[id]/page.tsx
apps/control/src/components/work-summaries/summary-list.tsx
apps/control/src/components/work-summaries/generate-form.tsx
apps/control/src/components/work-summaries/org-summary-card.tsx
apps/control/src/components/work-summaries/contributor-view.tsx
apps/control/src/components/work-summaries/surface-view.tsx
apps/control/src/components/work-summaries/activity-group-card.tsx
apps/control/src/components/work-summaries/ai-explanation-strip.tsx
apps/control/src/components/work-summaries/reaction-bar.tsx
apps/control/src/components/work-summaries/free-response-box.tsx

Modified files

apps/control/src/types/intranet.ts   → add "work-summaries" to IntranetSection + DEFAULT_TABS

Existing files to read first (patterns to follow)

apps/control/src/components/devcontrol/sessions-tab.tsx        ← date filter + expandable card
apps/control/src/components/intranet/sub-tabs.tsx              ← view toggle (amber underline)
apps/control/src/types/intranet.ts                             ← section/tab structure
apps/control/supabase/functions/daily-task-reminder/index.ts   ← edge fn + Supabase pattern
apps/control/supabase/functions/_shared/                       ← shared utilities
apps/control/src/components/tasks/task-detail-drawer.tsx       ← AI summary UI reference

9. Credentials

All secrets in Bitwarden, collection DevOps-sponicgarden (ALPU.CA org). See infra/runbook.md for unlock recipe.

Gmail and ccd_session_mgmt accessed via MCP — no additional secrets needed beyond what the intranet already uses.

10. Bootstrap prompt (new session)

Paste this into a fresh Claude Code session to start implementation:

Implement the Work Summaries feature for the Sponic Gardens monorepo.
Full spec: docs/devtasks/day-in-review.md

Start with Phase 1 (the DB migration):
  apps/control/migrations/20260507_work_summaries.sql
  using the schema from §4. Follow existing migrations in that folder as a pattern.
  Then ask me before moving to Phase 2.

Before starting, read these files to understand patterns:
  apps/control/src/components/devcontrol/sessions-tab.tsx
  apps/control/src/components/intranet/sub-tabs.tsx
  apps/control/src/types/intranet.ts
  apps/control/supabase/functions/daily-task-reminder/index.ts
  apps/control/supabase/functions/_shared/

Credentials are in Bitwarden DevOps-sponicgarden — see infra/runbook.md for unlock recipe.

11. Build sequence

1. Migration — work_summaries, work_summary_feedback, work_summary_instructions, work_summary_sources tables + seed data
2. Edge fn: generate-work-summary — Sonnet synthesis pass + Haiku explanation pass + INSERT
3. Edge fn: update-summary-instructions — self-improvement loop + Supabase webhook
4. Intranet section — types → generate-form + list page → org-summary-card → ai-explanation-strip + activity-group-card → contributor-view + surface-view → reaction-bar + free-response-box
5. Source registry admin tab — manage work_summary_sources, activate auto-discovered sources

12. Verification

13. Deferred to v2

• Email delivery — formatted HTML email via Resend to leadership team
• Scheduled CRON — nightly generation at 8 PM CT
• Mobile push notifications
• Slack integration
• Multi-workspace Gmail (single authenticated account only)
• Historical import (reviews start from launch date)
• Public-facing version