diff --git a/docs/superpowers/specs/2026-06-21-entry-enrichment-design.md b/docs/superpowers/specs/2026-06-21-entry-enrichment-design.md new file mode 100644 index 0000000..bb98bec --- /dev/null +++ b/docs/superpowers/specs/2026-06-21-entry-enrichment-design.md @@ -0,0 +1,102 @@ +# Entry Enrichment — Design Spec + +**Date:** 2026-06-21 +**Status:** Approved + +## Overview + +Enrich all real trip journal entries with `location_city`, `location_country`, `lat`, `lng`, `weather_temp_c`, and `weather_desc` using an in-chat review workflow. One Markdown review doc per trip; Claude infers values, user corrects, Claude applies to YAML. + +--- + +## Scope + +### What this covers + +- Filling in `location_city` and `location_country` where blank +- Geocoding to `lat`/`lng` for all entries with a city +- Approximate seasonal `weather_temp_c` and `weather_desc` for each entry date + location +- Three real trips: `central-asia-2023`, `us-canada-mex-2024`, `italy-2025` + +### What this does not cover + +- Adding new journal entries (content creation) +- Adding GPX tracks to central-asia or us-canada-mex +- Historical weather API lookups (values are seasonal approximations, not exact) + +--- + +## Review Document Format + +One file per trip at `docs/enrichment/{trip-slug}.md`. + +### Table columns + +| Column | Source | Notes | +|---|---|---| +| Entry | folder name | e.g. `2023-09-05-pixelfed-8.entry` | +| Date | `date` frontmatter | `YYYY-MM-DD` | +| Title | `title` frontmatter | Read-only reference | +| City | inferred from title+body | Edit to correct | +| Country | inferred from title+body | Edit to correct | +| Lat | extracted from Map Link | Do not edit directly; update Map Link instead | +| Lng | extracted from Map Link | Do not edit directly; update Map Link instead | +| Map Link | OSM link `https://www.openstreetmap.org/#map=15/{lat}/{lng}` | Replace with corrected OSM or Google Maps link | +| Temp °C | seasonal approximation | Edit directly if wrong | +| Weather | seasonal approximation | Edit directly if wrong (e.g. `sunny`, `cloudy`, `rainy`) | + +### Coordinate extraction rules + +When reading back a reviewed doc, extract lat/lng from Map Link using these URL patterns: + +- **OSM:** `openstreetmap.org/#map={zoom}/{lat}/{lng}` → use the two numbers after `#map=N/` +- **Google Maps:** `maps.google.com/.../@{lat},{lng},{zoom}z` or `maps.app.goo.gl/...` (follow redirect, then parse) + +If a cell has no Map Link (blank city), lat/lng are left empty. + +--- + +## Inference Rules + +1. Read `title` first — most locations are explicit ("Poutine and French Echoes in Old Montreal"). +2. Fall back to body text if title is ambiguous. +3. If neither title nor body reveals a location, leave City/Country blank and note it for manual fill. +4. City = the specific city or town; Country = the country. + +--- + +## Weather Approximation + +Fill `weather_temp_c` with a single integer (the approximate daytime high in °C for that city + month). Fill `weather_desc` with one word: `sunny`, `cloudy`, `partly cloudy`, `rainy`, `cold`, or `hot`. Based on known climate patterns — not historical API data. + +--- + +## Application Step + +After user approves a reviewed doc, Claude: + +1. Re-reads the table row by row +2. Extracts coordinates from Map Link (or leaves blank if no link) +3. Updates the corresponding `entry.md` frontmatter fields in-place +4. Reports a summary of changes made + +No scripts are written — changes are applied directly via Edit tool. + +--- + +## Order of Execution + +1. `central-asia-2023` — 22 entries (generate doc → review → apply) +2. `us-canada-mex-2024` — 12 entries (generate doc → review → apply) +3. `italy-2025` — 2 entries (generate doc → review → apply) + +--- + +## File Map + +| File | Change | +|---|---| +| `docs/enrichment/central-asia-2023.md` | New — review table, 22 rows | +| `docs/enrichment/us-canada-mex-2024.md` | New — review table, 12 rows | +| `docs/enrichment/italy-2025.md` | New — review table, 2 rows | +| `user/pages/01.trips/*/01.dailies/*/entry.md` | Update 6 frontmatter fields per entry |