| 1 | # DOCKET - Neutral Government Activity Tracker |
| 2 | ### Product & Brand Plan (v0, planning only - nothing built) |
| 3 | |
| 4 | *Name: **Docket** (LOCKED). A "docket" is the official register of proceedings - it inherits TreeTrace's evidence/record DNA while reading as civic, not forensic-security.* |
| 5 | |
| 6 | Date: 2026-06-26 · Status: PLAN ONLY |
| 7 | |
| 8 | ### Locked decisions (2026-06-26) |
| 9 | - **Name:** Docket |
| 10 | - **Accent:** Brass/amber `#E0A53B` |
| 11 | - **Scope:** Federal **+ state** from day one (OpenStates in the MVP - see cost note in §4) |
| 12 | - **Summaries at launch:** Structured fields first (title/status/$/votes from official data); LLM prose added later |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## 1. The Idea in One Line |
| 17 | |
| 18 | > The unfiltered public record of what government does - **every bill, law, amendment, and vote, including what gets slipped in by either side** - at federal *and* granular state level, made legible to any citizen, with **zero spin** and every fact sourced directly to an official record. |
| 19 | |
| 20 | **Scope correction (2026-06-26, Zion):** Docket is NOT a spending tracker. Spending is one lens. Docket is **full-spectrum government transparency** - all bills, all laws, all amendments/riders, all votes, plus the procedural / closed-door activity that is technically public but buried where no ordinary citizen can find it. |
| 21 | |
| 22 | Two jobs at once: |
| 23 | - **Awareness** - a neutral feed so you catch what's happening (*"this was happening and I had no idea"* - e.g. the CBS Texas clip: an election bill stalling on a House blockade, a floor event most people never hear about). |
| 24 | - **Lookup** - a resource where anyone, including an 80-year-old, can dig up exactly what their representatives did on any bill, in any state, on a granular level - unfiltered, in plain English. |
| 25 | |
| 26 | The product's job is to convert **the complete official record** into calm, neutral, *legible* visibility - and to do it without ever picking a side. |
| 27 | |
| 28 | --- |
| 29 | |
| 30 | ## 1b. Coverage pillars (full-spectrum) |
| 31 | |
| 32 | Docket must cover, for federal and every state, on a granular look-up-anything basis: |
| 33 | |
| 34 | 1. **Bills & laws** - every bill introduced, its full text, status timeline, sponsors/cosponsors, committee path, and final enacted law. |
| 35 | 2. **Amendments & riders - "what got slipped in."** *The signature feature.* Every amendment, manager's amendment, en-bloc add, and rider - and a **text-diff view** that shows what was added/removed between bill versions (Introduced → Reported → Engrossed → Enrolled) and between House/Senate/conference versions. This is where provisions get buried; Docket drags them into daylight. |
| 36 | 3. **Votes - recorded AND unrecorded.** Roll calls with per-member positions, *and* surfacing when something passed by **voice vote / unanimous consent / suspension** (i.e., no individual record exists) - because "there is no record" is itself information a citizen deserves. |
| 37 | 4. **The buried / closed-door layer** - committee markups & hearings, conference committees, procedural maneuvers (cloture, discharge petitions, motions to recommit), the Congressional Record, lobbying disclosures, and executive actions (Executive Orders, agency rulemaking via the Federal Register). Technically public, practically invisible. |
| 38 | 5. **Spending** - appropriations, awards, agency outlays, debt/deficit. *One lens among many, not the headline.* |
| 39 | 6. **Who** - representatives and their actual records (votes, sponsorships, what they slipped in), so "what did MY rep do" is one search. |
| 40 | |
| 41 | **Two modes for every pillar:** the *feed* (what's new, ranked by official action) and *deep look-up* (search/browse anything, any state, any granularity). The look-up mode is co-equal with the feed - Zion's explicit ask. |
| 42 | |
| 43 | ## 1c. Accessibility as a first-class principle |
| 44 | |
| 45 | Docket must be usable by **any** citizen, explicitly including an 80-year-old with low vision and low tech-literacy. This is a hard requirement, not a polish item: |
| 46 | - A clean, high-contrast **readable mode** alongside the dark forensic brand; large type, big touch targets, no hover-only interactions. |
| 47 | - Plain-language explanations at a low reading grade level - **without** adding spin (extraction, not opinion; see §3 neutrality). |
| 48 | - "Look up my state / my rep / my topic" search that doesn't overwhelm. |
| 49 | - (Targets being researched; will land in `docs/ACCESSIBILITY.md` and fold into BRAND.md.) |
| 50 | |
| 51 | --- |
| 52 | |
| 53 | ## 2. Why Now / The Market Gap (validated by research) |
| 54 | |
| 55 | The civic-data space is structurally empty at the consumer-awareness level: |
| 56 | |
| 57 | | Player | What it is | Why it leaves the gap open | |
| 58 | |---|---|---| |
| 59 | | **GovTrack** | Deepest federal bill/vote data, since 2004 | Dated dense UI, for engaged watchers; no spending; jargon summaries; no push | |
| 60 | | **USAFacts** (Ballmer) | Gold-standard neutral govt data | Static macro data, no bill-by-bill, no alerts, academic UX | |
| 61 | | **Ballotpedia** | Neutral encyclopedia | Reference tool, not a real-time "what changed" feed; not mobile-first | |
| 62 | | **Countable / ProPublica Represent** | Were the consumer apps | **Both dead.** Audience now unserved | |
| 63 | | **FiscalNote / Quorum / Plural** | Enterprise intel | $10k+/yr, locked behind paywalls, not consumer | |
| 64 | | **FastDemocracy / LegiScan / BillTrack50** | Power-user trackers (+ some AI) | Built for policy staff; jargon; no spending; no emotional hook | |
| 65 | | **2025 DOGE trackers** | Spending-cut trackers | **Nearly all carry partisan valence** (pro- or anti-) | |
| 66 | |
| 67 | **The empty slot:** a consumer product that combines (1) federal **bills + spending in one feed**, (2) **push-alert awareness for normal people** who aren't already tracking politics, (3) **genuinely neutral** framing, and (4) **plain-English "here's what it does"** with no opinion. Nobody owns this. |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## 3. Neutrality Doctrine - the non-negotiables |
| 72 | |
| 73 | This is the whole product. If it leans, it dies. Five rules to **hard-code into the codebase**, not just the style guide: |
| 74 | |
| 75 | 1. **Government-source-only.** Every displayed fact links to an official URL (Congress.gov, USAspending.gov, GPO/GovInfo, CBO, Treasury). No secondhand, no think tanks, no media. |
| 76 | 2. **No adjectives.** Strip all qualitative modifiers from generated text before display. Never "slashed/gutted/expanded/massive" - only "reduced by $X," "added $Y," with the number and the source. (USAFacts' rule: *adjectives are partisan.*) |
| 77 | 3. **Surface by official action, never by virality.** Ranking = date of legislative action (introduced → markup → floor vote → signed) × dollar magnitude × people affected (per CBO/agency estimate). **Never** by news coverage or social engagement - that just imports media's agenda. |
| 78 | 4. **No comment sections, ever.** The single biggest bias-injection point. If engagement is needed, allow reactions on **summary clarity only** (was this clear? yes/no), never on the bill itself. |
| 79 | 5. **LLM summaries use extraction templates, not free-form generation.** Pull structured fields from official bill text. Free-form summarization is where documented LLM political lean creeps in (AAAI 2025: models skew pro-Democratic on health/guns). Test high-salience summaries against a Polarization Index before they go live. |
| 80 | |
| 81 | **Standing risks to monitor:** (a) LLM bias *drifts* as models update - needs ongoing automated checks, not a one-time test; (b) **topic-selection** is soft bias - proportional, dollar-and-action-weighted surfacing, not editorial "what matters" calls; (c) **partisan co-option** - if one base adopts it heavily it gets socially coded as "their tool"; mitigate with a visible bipartisan advisory board + dual-side launch outreach. |
| 82 | |
| 83 | **Visualization neutrality note:** when showing party splits (sponsor party / vote breakdown *is* factual data, so it's allowed), **never use saturated red-vs-blue** - the eye codes that as "teams." Use muted/desaturated party tones of equal visual weight, or a neutral yea/nay encoding. |
| 84 | |
| 85 | --- |
| 86 | |
| 87 | ## 4. Data Architecture |
| 88 | |
| 89 | ### Primary stack (the backbone - all free, all official) |
| 90 | 1. **Congress.gov API** (`api.congress.gov/v3/`) - canonical bill status, actions, members, votes. Free api.data.gov key, 5,000 req/hr, same-day freshness. *Poll with `?sort=updateDate&fromDateTime=…` every 15-30 min.* |
| 91 | 2. **GovInfo API** (`api.govinfo.gov`) - full bill text, Congressional Record, public laws, appropriations docs. Same key, **36,000 req/hr** (most generous). `/published/{start}/{end}` for delta polling. |
| 92 | 3. **USAspending.gov API** (`api.usaspending.gov/v2/`) - award-level contracts/grants/loans, agency outlays. **No auth.** 10k-result cap per call → use bulk download for completeness. |
| 93 | 4. **Treasury Fiscal Data API** (`fiscaldata.treasury.gov`) - debt, deficit, daily cash flows (DTS T+1), monthly outlays by agency (MTS). No auth. |
| 94 | |
| 95 | ### Supplements |
| 96 | - **Roll-call votes, fastest path:** House Clerk XML (`clerk.house.gov/evs/`) + Senate roll-call XML - posted within hours, no key. Faster than the API for "a vote just happened." |
| 97 | - **CBO cost estimates:** no API - scrape `cbo.gov/cost-estimates` by bill; macro projections via the `us-cbo` GitHub CSVs. |
| 98 | - **Voteview.com** - bulk vote CSV + ideology scores (use scores internally for QA, not as user-facing labels). |
| 99 | - **OpenStates v3** - 50-state + DC/PR coverage, standardized schema, JSON. **IN MVP SCOPE (decision: federal + state from day one).** Free tier is only 500 q/day, 10 req/sec - far too tight for production; **a paid tier is required** (Bronze 5k/day, Silver 50k/day; pricing not public - contact OpenStates). This is the one place the data stack stops being free. State ingest is also messier: freshness and schema completeness vary by state. Budget for: (a) the paid tier, (b) per-state polling cadence tuning, (c) a "coverage map" so the UI is honest about which states lag. |
| 100 | |
| 101 | ### Real-time / change detection |
| 102 | No government API offers webhooks - **everything is polling.** Build a change-detection layer: store last `updateDate` per bill, diff on each poll, emit an event on change → that event drives the feed + push notifications. Congress.gov website RSS (`congress.gov/rss/`) is a cheap pre-check before a full pull. |
| 103 | |
| 104 | ### Biggest data-engineering risk |
| 105 | **Congress.gov reliability.** It had a multi-day silent outage in Aug 2025 (redirect loop, key signup broke, zero comms). It's the only live bill-status source. **Mitigation:** fall back to the community `unitedstates/congress` scraper (pulls GovInfo bulk XML, LoC-independent); design ingest to tolerate 24-72h of Congress.gov downtime without going stale. |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## 5. Product Surfaces |
| 110 | |
| 111 | **MVP (federal only):** |
| 112 | - **The Feed** - reverse-chronological stream of official actions: "House passed HR ___ (vote 218-210)," "Senate cloture failed on S ___," "$2.1B contract awarded to ___ by DoD." Each card: plain-English what-it-does, status, dollar figure, **source link**. |
| 113 | - **Bill page** - extraction-template summary, sponsor (name/party/state, factual), status timeline, CBO score if any, full-text link, vote breakdown (muted colors). |
| 114 | - **Spending page** - agency outlays, notable awards, debt/deficit at a glance from Treasury, all with baselines and % context. |
| 115 | - **Alerts** - push/email on: a bill changing status, a vote happening, spending over a threshold, or topics the user follows (by policy area or agency - **not** by party). |
| 116 | - **"How we pick what to show"** + **"Who pays for this?"** transparency pages (core trust signals). |
| 117 | |
| 118 | **v1:** topic follows, personalized digest ("your weekly government recap"), "find my representatives + their actual votes," saved bills, share-as-image (factual card, no social-comment import). |
| 119 | |
| 120 | **In MVP (decision):** state-level via OpenStates, with an honest per-state coverage map. |
| 121 | **Later:** historical trends, "where did the money actually go" award drilldowns, civics-educator/library partnerships. |
| 122 | |
| 123 | --- |
| 124 | |
| 125 | ## 6. Brand Pack - adapted from the TreeTrace pattern |
| 126 | |
| 127 | We **inherit TreeTrace's system architecture** (dark-first, forensic/record aesthetic, rationed accent, monospace data, custody-stamp mark, multi-page functional site) but **deliberately diverge on the accent color** - because the brand color itself must be politically neutral. |
| 128 | |
| 129 | **Key divergence: drop cobalt blue.** Blue reads Democrat, red reads Republican. The neutral, "official record / Capitol brass / parchment ledger" choice is **amber/brass on ink**. It evokes seals, the dome, and the public record - and belongs to neither side. |
| 130 | |
| 131 | ### Color tokens (proposed) |
| 132 | | Token | Hex | Role | |
| 133 | |---|---|---| |
| 134 | | `--dk-ink` | `#0B0C0E` | Page background (near-black) | |
| 135 | | `--dk-surface` | `#121316` | Cards, terminal chrome | |
| 136 | | `--dk-graphite` | `#23262B` | Raised/hover | |
| 137 | | `--dk-paper` | `#F2EFE9` | Primary text (warm bone) | |
| 138 | | `--dk-ash` | `#9BA0A6` | Secondary / mono labels | |
| 139 | | `--dk-line` | `rgba(155,160,166,.18)` | Hairlines | |
| 140 | | **`--dk-signal`** | **`#E0A53B`** | **Brass/amber - PRIMARY accent (rationed)** | |
| 141 | | `--dk-signal-dim` | `#B07F25` | Hover/pressed | |
| 142 | | `--dk-signal-tint` | `rgba(224,165,59,.08)` | Active-row wash | |
| 143 | | `--dk-yea` | `#7FA88C` (muted sage) | Vote "yea" / funded - *not vivid green* | |
| 144 | | `--dk-nay` | `#B98A8A` (muted clay) | Vote "nay" / cut - *not vivid red* | |
| 145 | | party tones | desaturated, equal weight | only when party is the factual datum | |
| 146 | |
| 147 | *Alt accent if brass feels too warm: a neutral teal `#2BB3A3`. Avoid any dominant red or blue.* |
| 148 | |
| 149 | ### Typography (same skeleton as TreeTrace) |
| 150 | - **Display:** Archivo 800-900, uppercase, tight tracking - for headlines/numbers. |
| 151 | - **Data / labels / nav:** JetBrains Mono, uppercase, tracked - vote counts, dollar figures, bill numbers, timestamps. (Reinforces "this is a record, not an op-ed.") |
| 152 | - **Prose:** Fraunces for the rare lead sentence / plain-English summary. |
| 153 | |
| 154 | ### Visual signature (adapted) |
| 155 | - **Mark:** a **custody-stamp/seal frame** like TreeTrace's `[TT]`, but civic - a registration frame around a monogram (`[D]` / docket tick) reading as an *official stamp on the record*, not a forensic crosshair. Flat strokes, no gradient, no eagle/flag clichés (those carry valence). |
| 156 | - **Hero:** TreeTrace uses a live CLI terminal; here, a **live "register" / ticker** - official actions materializing in real time as stamped record-lines ("14:02 ET - H.R. ___ - FAILED - 209-214"). Same "real thing happening live" energy, civic skin. |
| 157 | - **Rationed accent:** one brass signal per view (a live dot, an active filter, a "just happened" flag). Never large fills. Calm, sealed, authoritative. |
| 158 | - **Light mode:** parchment `#F6F4EF` bg, ink text - reads like an official document. |
| 159 | |
| 160 | ### Philosophy line |
| 161 | > *Record the action, not the argument - every entry sealed to its source.* |
| 162 | |
| 163 | --- |
| 164 | |
| 165 | ## 7. Tech Stack & Deployment |
| 166 | |
| 167 | - **Frontend:** Next.js (multi-page functional site, matches TreeTrace pattern), Tailwind with the token set above, dark-first. Mobile-first PWA so push works without app-store friction at MVP. |
| 168 | - **Backend/ingest:** Python or Node workers polling the four APIs on cron; a change-detection table keyed by `updateDate`; Postgres for bills/actions/awards; a normalized "event" table that powers feed + alerts. |
| 169 | - **Summaries:** extraction-template pipeline. Can run locally with an open-weight LLM for cost-free draft extraction, with a Polarization-Index QA gate before publish - but **prefer deterministic field extraction over generation** wherever possible. |
| 170 | - **Push:** ntfy for MVP; web-push for PWA. |
| 171 | - **Hosting:** Cloudflare Pages for the static/edge front, self-hosted workers for the ingest service. |
| 172 | - **Costs:** all primary data is free; main cost is compute for ingest + summary QA. |
| 173 | |
| 174 | --- |
| 175 | |
| 176 | ## 8. Build Phases |
| 177 | |
| 178 | - **Phase 0 - Brand + spike (this plan + a clickable shell):** lock name/colors/mark; stand up the token set + a static feed mockup with fake data. |
| 179 | - **Phase 1 - Ingest spine:** Congress.gov + USAspending + Treasury pollers → events table → real feed (read-only, no auth). Source links on every card. |
| 180 | - **Phase 2 - Summaries + bill pages:** extraction templates + Polarization-Index gate; full bill pages. |
| 181 | - **Phase 3 - Alerts + accounts:** topic follows (policy area/agency), push via ntfy/web-push, weekly digest. |
| 182 | - **Phase 4 - Trust + polish:** transparency pages, advisory board outreach, dual-side launch. |
| 183 | - **Phase 1.5 - State spine:** OpenStates ingest (paid tier) + per-state coverage map, folded in alongside federal. |
| 184 | - **Later:** reps lookup, historical trends, award drilldowns. |
| 185 | |
| 186 | --- |
| 187 | |
| 188 | ## 9. Decisions - RESOLVED (2026-06-26) |
| 189 | 1. **Name:** ✅ **Docket** |
| 190 | 2. **Accent:** ✅ **Brass/amber `#E0A53B`** |
| 191 | 3. **Scope of MVP:** ✅ **Federal + state** (OpenStates in MVP; paid tier required) |
| 192 | 4. **Summaries:** ✅ **Structured fields first** (LLM prose later) |
| 193 | 5. **Domain style:** OPEN - `.org` reads most neutral/non-commercial for a civic-trust product; `docket.org` likely taken, so candidates like `docket.vote`, `getdocket.org`, `docket.gov`-adjacent, or `ondocket.org` need a availability check. *(Only remaining open item.)* |
| 194 | |
| 195 | --- |