LocalIntelligence

LocalIntelligence

Customization

Before executing, check for user customizations at: ~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/LocalIntelligence/

If this directory exists, load and apply any PREFERENCES.md, optional source-list overrides, or per-source API keys (e.g., OpenStates, Google News topic ID). These override defaults. If the directory does not exist, proceed with skill defaults — universal sources only.

sources.json in the same directory is the deterministic per-city source list (RSS feeds, local JSON APIs) consumed by Tools/UserSources.ts on every refresh — see Tools/UserSources.help.md for the schema. City-specific URLs belong there, never in this skill.

Voice Notification

When executing a workflow, do BOTH:

1. Send voice notification:

   bashCopy code
   curl -s -X POST http://localhost:31337/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running WORKFLOWNAME in LocalIntelligence"}' \
     > /dev/null 2>&1 &
   

2. Output text notification:

   Copy code
   Running **WorkflowName** in **LocalIntelligence**...
   

What It Does

LocalIntelligence is a civic intelligence aggregator for any US city. It pulls eight categories of local data — construction permits, crime, new businesses, public officials, legislation, elections, arrests, and local news — into a single daily JSON digest, keyed off the city in the principal's identity file and served to the Pulse LOCAL tab. Crime delegates to the dedicated crime-stats skill.

The Problem

What's actually happening where you live is scattered across a dozen sites that nobody checks — the city's permit portal, the council agenda system, the sheriff's blotter, a local paper, the elections office. No single feed tells you a new ordinance is up for a vote, a building is going up down the street, or an election is coming. Most "local news" tools either cover one city, hardcode endpoints that break, or paywall the good stories. This skill stays generic across every US city, resolves the target city at runtime, and degrades gracefully when a source has no data instead of blanking the whole digest.

How It Works

Local civic intelligence for whatever city the principal lists in PRINCIPAL_IDENTITY.md Hometown. Generic across all US cities — no per-city profiles, no hardcoded endpoints. Eight fetchers run in parallel and write one JSON digest, served to the Pulse LOCAL tab.

Default Hometown — Always Dynamic

The principal's hometown is never hardcoded in this skill. Every workflow and tool resolves it at runtime via:

typescriptCopy code
import { readHometown } from "./Tools/Hometown.ts"
const { city, state, zip, county } = await readHometown()

Tools/Hometown.ts parses the **Hometown:** line from ~/.claude/LIFEOS/USER/PRINCIPAL/PRINCIPAL_IDENTITY.md. If absent, every workflow surfaces a clear "no hometown set" message and refuses to fetch. There is no fallback city.

Workflow Routing

Architecture

Copy code
LocalIntelligence/
├── SKILL.md                  this file
├── Workflows/
│   ├── DailyBrief.md         orchestrator — runs Refresh.ts and summarizes
│   ├── Construction.md
│   ├── Crime.md              fetches city crime stats via the configured crime-data adapter
│   ├── Business.md
│   ├── Officials.md
│   ├── Legislation.md
│   ├── Elections.md
│   ├── Arrests.md
│   └── News.md
├── Tools/
│   ├── Hometown.ts           parser + types — sole source of city info
│   ├── Refresh.ts            orchestrator — calls 8 fetchers, writes latest.json; --fill adds AI gap-fill
│   ├── ClaudeFill.ts         AI gap-filler — one web-research claude subprocess for empty sections
│   ├── UserSources.ts        user-configured RSS/JSON sources from CUSTOMIZATIONS sources.json
│   ├── FetchConstruction.ts
│   ├── FetchBusiness.ts
│   ├── FetchOfficials.ts
│   ├── FetchLegislation.ts
│   ├── FetchElections.ts
│   ├── FetchArrests.ts
│   ├── FetchNews.ts
│   └── FetchCrime.ts         shells to a dedicated crime-stats skill's workflow output
└── References/
    └── DataSources.md        catalog of universal civic sources keyed off {city,state}

Output: ~/.claude/LIFEOS/MEMORY/DATA/LocalIntelligence/<YYYY-MM-DD>_<city>_<state>_digest.json (dated history — the Week/Month/Year views aggregate these) plus latest.json written to BOTH LIFEOS/USER/CUSTOMIZATIONS/SKILLS/LocalIntelligence/ (the Pulse module's primary read path) and MEMORY/DATA/LocalIntelligence/ (legacy fallback).

--fill mode: bun run Tools/Refresh.ts --fill runs the fetchers, then ClaudeFill.ts researches any empty/unavailable sections via one web-enabled claude subprocess with deterministic output validation. The daily Pulse cron and the dashboard Refresh button both use --fill; a bare invocation stays purely deterministic.

Fetch order per refresh: built-in fetchers → UserSources.ts (deterministic, user-configured) → ClaudeFill.ts (only sections still empty). Deterministic data always wins over model research.

Fetcher Contract

Every fetcher exports a single function:

typescriptCopy code
type Item = { title: string; source: string; url: string; date: string; summary?: string }
type FetchResult = { items: Item[]; source_status: "ok" | "unavailable" | "empty"; errors?: string[] }
export async function fetch(home: Hometown): Promise<FetchResult>

Fetchers return the empty/unavailable case rather than throwing. Refresh.ts runs all eight via Promise.allSettled so a dead source never blanks the digest. Errors land in meta.errors with the failing source label.

Pulse Integration

The skill writes JSON; Pulse reads it. Coupling lives in two places:

1. Pulse module at ~/.claude/LIFEOS/PULSE/modules/local-intelligence.ts — read-only over MEMORY/DATA/LocalIntelligence/latest.json. Endpoints: GET /api/local-intelligence, POST /api/local-intelligence/refresh.
2. Pulse dashboard tab at ~/.claude/LIFEOS/PULSE/Observability/src/app/local/page.tsx — fetches the JSON and renders nine section cards. Nav entry in AppHeader.tsx lifeNav between LIFE and WORK.

Daily refresh: [[job]] in PULSE.toml at 0 6 * * * running bun run skills/LocalIntelligence/Tools/Refresh.ts.

Examples

Example 1: Run the daily digest

Copy code
User: "What's happening in my city today?"
→ Invokes DailyBrief workflow
→ Reads hometown from PRINCIPAL_IDENTITY.md
→ Runs Tools/Refresh.ts orchestrator
→ Writes latest.json
→ Summarizes top-3 items per category in chat

Example 2: Council agenda check

Copy code
User: "Anything on the council agenda this week?"
→ Invokes Legislation workflow
→ Calls Tools/FetchLegislation.ts for hometown
→ Returns pending council items with source links

Example 3: Refresh from the dashboard

Copy code
User clicks "Refresh now" on the LOCAL tab
→ Pulse POSTs /api/local-intelligence/refresh
→ Pulse module spawns Tools/Refresh.ts
→ latest.json is regenerated and the tab re-renders

Gotchas

• No hometown line = no fetch. If PRINCIPAL_IDENTITY.md lacks a Hometown: line, every workflow returns a clear setup-help message and exits zero. Do not invent a city.
• Per-city API quality varies wildly. Some cities have rich Granicus/OpenStates coverage; others publish PDFs only. Each fetcher must return source_status: "unavailable" rather than fail when a universal source has no data for the resolved city.
• Census Building Permits Survey is monthly, not daily. Construction signal is medium-latency by nature; do not promise "today's permits."
• OpenStates covers state legislatures, not city councils. For council pending/enacted laws, fetchers attempt Granicus/Legistar discovery via well-known URL patterns. Coverage is best-effort.
• Patch RSS path varies by state. https://patch.com/<state-slug>/<city-slug>/feed works for most cities but a few have legacy slugs. The News fetcher tries the canonical path first and falls back to a Google News topic search keyed on "<city>, <state>".
• Sheriff blotter scraping is jurisdiction-specific. Fetchers attempt the county sheriff's blotter page if discoverable; if not, they return unavailable. No bypassing CAPTCHA, no paid scraping services in v1.
• Crime never duplicates a dedicated crime-stats skill. FetchCrime.ts invokes that skill and shapes the result into the digest. Direct calls to CitizenRIMS, FBI UCR, or AreaVibes from inside this skill are forbidden — see ISC-12 in the design ISA.
• Daily JSON files accumulate. Old digests stay in MEMORY/DATA/LocalIntelligence/ for trend retrieval; only latest.json is the read target for Pulse. Periodic prune is the user's call.
• Local newspapers paywall the good stories. RSS feeds usually surface headlines + summaries; the dashboard links to the source. The skill never bypasses paywalls.
• Two latest.json paths exist and BOTH must be written. The Pulse module reads USER/CUSTOMIZATIONS/SKILLS/LocalIntelligence/latest.json first, MEMORY/DATA/LocalIntelligence/latest.json second. From 2026-05-03 to 2026-07-16 Refresh.ts wrote only the legacy path — the tab silently served a 2.5-month-old digest while the 6 a.m. job "succeeded" daily. persist() now writes both; never remove one.
• No-clobber guard is load-bearing. An all-empty run (fetchers stubbed/down, fill failed) writes its dated file but never overwrites a populated latest.json. Without it, one bad 6 a.m. run blanks the dashboard.
• ClaudeFill output never enters the digest unvalidated. All model output passes validateSection() (field checks, URL shape, caps). Fill errors degrade to the fetchers' digest — the fill can only add.
• Aggregator search feeds rank by relevance, not date. A Google News RSS query happily returns decade-old stories. Every aggregator source in sources.json needs BOTH a when:Nd operator in the query AND max_age_days (the deterministic backstop — when: alone still leaks old items).
• Google News item links are news.google.com redirects and titles end "Headline - Publication". Set strip_title_suffix: true to promote the publication into the item's source field. Redirect URLs resolve fine in a browser; don't rewrite them.
• Municipal CivicPlus/city sites often hard-block bots (Akamai 403 even with browser headers). Don't wire them directly — their content arrives via Google News queries instead. Verified against a city site 2026-07-16.
• source_status: "empty" is not the same as "unavailable". empty = source returned 200 with zero matching items (common for small towns). unavailable = source 4xx/5xx or DNS failure. The dashboard renders different empty states for each.

Public Release Readiness

This skill body is generic by design. Pre-flight grep:

bashCopy code
rg -i "<your-city>|<your-zip>|<your-county>|/Users/[a-z]+/" ~/.claude/skills/LocalIntelligence/

Zero matches required before treating the skill as releasable. The principal's actual hometown lives in PRINCIPAL_IDENTITY.md, never here.

Execution Log

After completing any workflow, append a single JSONL entry:

bashCopy code
echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"LocalIntelligence","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' >> ~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl