diff --git a/docs/superpowers/plans/2026-06-21-entry-enrichment.md b/docs/superpowers/plans/2026-06-21-entry-enrichment.md new file mode 100644 index 0000000..68094c8 --- /dev/null +++ b/docs/superpowers/plans/2026-06-21-entry-enrichment.md @@ -0,0 +1,327 @@ +# Entry Enrichment Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Enrich all real trip journal entries with location, GPS coordinates, and approximate weather by generating per-trip Markdown review docs, letting the user correct them, then applying changes to YAML frontmatter. + +**Architecture:** Three round-trips (one per trip): Claude generates a review table → user edits the doc → Claude applies the approved values to `entry.md` frontmatter. No scripts — all edits via the Edit tool directly. Human review gates between each trip pair. + +**Tech Stack:** Grav YAML frontmatter, Markdown tables, OpenStreetMap URLs for coordinates. + +## Global Constraints + +- Never read `.env` +- Only write to `user/` and `docs/` directories +- `lat`/`lng` must be decimal degree strings (e.g. `'48.8566'`) — not integers +- `weather_temp_c` must be a string integer (e.g. `'22'`) +- `weather_desc` must be a single short phrase (e.g. `sunny`, `partly cloudy`, `rainy`) +- Map Links use OSM format: `https://www.openstreetmap.org/#map=15/{lat}/{lng}` +- All edits committed to the `user/` git repo via `make content-push` after all three trips are done + +--- + +## File Map + +| File | Action | Purpose | +|---|---|---| +| `docs/enrichment/central-asia-2023.md` | Create | Review table, 22 rows | +| `docs/enrichment/us-canada-mex-2024.md` | Create | Review table, 12 rows | +| `docs/enrichment/italy-2025.md` | Create | Review table, 2 rows | +| `user/pages/01.trips/central-asia-2023/01.dailies/*/entry.md` | Modify | Update 6 frontmatter fields (22 files) | +| `user/pages/01.trips/us-canada-mex-2024/01.dailies/*/entry.md` | Modify | Update 6 frontmatter fields (12 files) | +| `user/pages/01.trips/italy-2025/01.dailies/*/entry.md` | Modify | Update 6 frontmatter fields (2 files) | + +--- + +## Task 1: Generate central-asia-2023 review doc + +**Files:** +- Create: `docs/enrichment/central-asia-2023.md` +- Read: `user/pages/01.trips/central-asia-2023/01.dailies/*/entry.md` (22 files) + +- [ ] **Step 1: Read all 22 entry.md files** + +Read each file at `user/pages/01.trips/central-asia-2023/01.dailies/{folder}/entry.md`. Extract: folder name, `date`, `title`, `location_city`, `location_country`, body text. + +- [ ] **Step 2: Infer location for each entry** + +For each entry: +1. Read the title first — most locations are explicit. +2. Fall back to body text if title is ambiguous. +3. If neither reveals a location clearly, leave City/Country blank and put `?` in the Map Link cell. + +Known city → approximate coordinates mapping for this trip (use these; do not hallucinate unfamiliar coordinates): + +| City | Country | Lat | Lng | +|---|---|---|---| +| Berlin | Germany | 52.5200 | 13.4050 | +| Astana (Nur-Sultan) | Kazakhstan | 51.1801 | 71.4460 | +| Almaty | Kazakhstan | 43.2220 | 76.8512 | +| Karakol | Kyrgyzstan | 42.4900 | 78.3936 | +| Dushanbe | Tajikistan | 38.5598 | 68.7870 | +| Samarkand | Uzbekistan | 39.6542 | 66.9597 | +| Tbilisi | Georgia | 41.6938 | 44.8015 | + +- [ ] **Step 3: Estimate weather for each entry** + +Use typical daytime high (°C) and one-word description for the city + month. Reference values: + +| City | Aug | Sep | Oct | +|---|---|---|---| +| Berlin | 24, sunny | 19, partly cloudy | 13, cloudy | +| Astana | 26, sunny | 17, partly cloudy | 5, cold | +| Almaty | 28, sunny | 21, sunny | 12, partly cloudy | +| Karakol | 24, sunny | 16, partly cloudy | 8, cold | +| Dushanbe | 35, sunny | 28, sunny | 18, sunny | +| Samarkand | 33, sunny | 25, sunny | 16, partly cloudy | +| Tbilisi | 29, sunny | 23, sunny | 14, partly cloudy | + +- [ ] **Step 4: Write the review doc** + +Create `docs/enrichment/central-asia-2023.md` with this exact structure: + +```markdown +# central-asia-2023 Enrichment Review + +**Instructions:** Review each row. To correct coordinates, replace the Map Link with a new OSM link (`https://www.openstreetmap.org/#map=15/{lat}/{lng}`) or a Google Maps URL — coordinates are extracted from the link. Edit City, Country, Temp, and Weather cells directly. Leave Map Link blank if no location is known. + +| Entry | Date | Title | City | Country | Map Link | Temp °C | Weather | +|---|---|---|---|---|---|---|---| +| 2023-08-28-pixelfed-1.entry | 2023-08-28 | Welcome to My Central Asian Picture Diary | Berlin | Germany | https://www.openstreetmap.org/#map=15/52.5200/13.4050 | 24 | sunny | +... +``` + +One row per entry, in date order. + +- [ ] **Step 5: Commit the generated doc** + +```bash +cd /home/mischa/Projects/travel-blog-intotheeast +git add docs/enrichment/central-asia-2023.md +git commit -m "docs: add central-asia-2023 enrichment review doc" +``` + +- [ ] **Step 6: Prompt user to review** + +Tell the user: "Review doc generated at `docs/enrichment/central-asia-2023.md`. Please open it, correct any locations or weather values, and let me know when it's ready to apply." + +--- + +## Task 2: Apply central-asia-2023 enrichment (after user approval) + +**Files:** +- Read: `docs/enrichment/central-asia-2023.md` +- Modify: `user/pages/01.trips/central-asia-2023/01.dailies/*/entry.md` (22 files) + +**Prerequisite:** User has reviewed and approved `docs/enrichment/central-asia-2023.md`. + +- [ ] **Step 1: Read the reviewed doc** + +Read `docs/enrichment/central-asia-2023.md`. Parse each data row of the table. + +- [ ] **Step 2: Extract coordinates from Map Links** + +For each row where Map Link is not blank: + +- OSM format `https://www.openstreetmap.org/#map={zoom}/{lat}/{lng}` → split on `/`, take last two values as lat and lng. +- Google Maps format `https://www.google.com/maps/@{lat},{lng},{zoom}z` → extract the `@lat,lng` portion. +- If Map Link is blank or `?`, set lat and lng to `''`. + +- [ ] **Step 3: Apply to each entry.md** + +For each row, open `user/pages/01.trips/central-asia-2023/01.dailies/{entry}/entry.md` and update these six fields using the Edit tool: + +```yaml +location_city: '{City}' +location_country: '{Country}' +lat: '{Lat}' +lng: '{Lng}' +weather_temp_c: '{Temp}' +weather_desc: '{Weather}' +``` + +Replace the existing (likely empty) values. Keep all other frontmatter untouched. + +- [ ] **Step 4: Verify** + +For the first 3 and last entry, read back the file and confirm the six fields are set correctly. + +- [ ] **Step 5: Commit** + +```bash +cd /home/mischa/Projects/travel-blog-intotheeast && git add user/pages/01.trips/central-asia-2023/01.dailies/ +git commit -m "content: enrich central-asia-2023 entries with location and weather" +``` + +--- + +## Task 3: Generate us-canada-mex-2024 review doc + +**Files:** +- Create: `docs/enrichment/us-canada-mex-2024.md` +- Read: `user/pages/01.trips/us-canada-mex-2024/01.dailies/*/entry.md` (12 files) + +- [ ] **Step 1: Read all 12 entry.md files** + +Read each file at `user/pages/01.trips/us-canada-mex-2024/01.dailies/{folder}/entry.md`. Extract: folder name, `date`, `title`, body text. + +- [ ] **Step 2: Infer location for each entry** + +Known cities from titles for this trip: + +| Title hint | City | Country | Lat | Lng | +|---|---|---|---|---| +| Piran | Piran | Slovenia | 45.5285 | 13.5680 | +| Portland / Amtrak (destination) | Portland | USA | 45.5231 | -122.6765 | +| San Francisco / Golden Gate / Highway 1 | San Francisco | USA | 37.7749 | -122.4194 | +| Los Angeles / burrito / beach | Los Angeles | USA | 34.0522 | -118.2437 | +| Toronto | Toronto | Canada | 43.6532 | -79.3832 | +| Niagara Falls | Niagara Falls | Canada | 43.0896 | -79.0849 | +| Montreal | Montreal | Canada | 45.5017 | -73.5673 | +| Mexico City | Mexico City | Mexico | 19.4326 | -99.1332 | +| Twin Peaks / windmills / craft beer | San Francisco | USA | 37.7749 | -122.4194 | +| Amtrak eighteen hours | (train — use Portland as destination) | USA | 45.5231 | -122.6765 | + +Use the title + body together to identify each city. + +- [ ] **Step 3: Estimate weather** + +Reference values (daytime high °C, description) for this trip's cities + months (May–Aug 2024): + +| City | May | Jul | Aug | +|---|---|---|---| +| Piran | 21, sunny | — | — | +| San Francisco | — | 18, partly cloudy | 18, partly cloudy | +| Los Angeles | — | 28, sunny | 29, sunny | +| Portland | — | 27, sunny | 27, sunny | +| Toronto | — | — | 27, sunny | +| Niagara Falls | — | — | 26, sunny | +| Montreal | — | — | 26, sunny | +| Mexico City | — | — | 22, partly cloudy | + +- [ ] **Step 4: Write the review doc** + +Create `docs/enrichment/us-canada-mex-2024.md` with the same structure as the central-asia doc: + +```markdown +# us-canada-mex-2024 Enrichment Review + +**Instructions:** Review each row. To correct coordinates, replace the Map Link with a new OSM link (`https://www.openstreetmap.org/#map=15/{lat}/{lng}`) or a Google Maps URL — coordinates are extracted from the link. Edit City, Country, Temp, and Weather cells directly. Leave Map Link blank if no location is known. + +| Entry | Date | Title | City | Country | Map Link | Temp °C | Weather | +|---|---|---|---|---|---|---|---| +| 2024-05-28-pixelfed-1.entry | 2024-05-28 | Ice Cream and Old Walls in Piran | Piran | Slovenia | https://www.openstreetmap.org/#map=15/45.5285/13.5680 | 21 | sunny | +... +``` + +- [ ] **Step 5: Commit** + +```bash +cd /home/mischa/Projects/travel-blog-intotheeast +git add docs/enrichment/us-canada-mex-2024.md +git commit -m "docs: add us-canada-mex-2024 enrichment review doc" +``` + +- [ ] **Step 6: Prompt user to review** + +Tell the user: "Review doc generated at `docs/enrichment/us-canada-mex-2024.md`. Please open it, correct any locations or weather values, and let me know when it's ready to apply." + +--- + +## Task 4: Apply us-canada-mex-2024 enrichment (after user approval) + +**Files:** +- Read: `docs/enrichment/us-canada-mex-2024.md` +- Modify: `user/pages/01.trips/us-canada-mex-2024/01.dailies/*/entry.md` (12 files) + +**Prerequisite:** User has reviewed and approved `docs/enrichment/us-canada-mex-2024.md`. + +- [ ] **Step 1: Read the reviewed doc and parse rows** — same method as Task 2 Step 1. + +- [ ] **Step 2: Extract coordinates from Map Links** — same method as Task 2 Step 2. + +- [ ] **Step 3: Apply to each entry.md** + +For each row, open `user/pages/01.trips/us-canada-mex-2024/01.dailies/{entry}/entry.md` and update the six frontmatter fields. + +- [ ] **Step 4: Verify** — read back first 3 and last entry, confirm fields are set. + +- [ ] **Step 5: Commit** + +```bash +cd /home/mischa/Projects/travel-blog-intotheeast && git add user/pages/01.trips/us-canada-mex-2024/01.dailies/ +git commit -m "content: enrich us-canada-mex-2024 entries with location and weather" +``` + +--- + +## Task 5: Generate italy-2025 review doc + +**Files:** +- Create: `docs/enrichment/italy-2025.md` +- Read: `user/pages/01.trips/italy-2025/01.dailies/*/entry.md` (2 files) + +- [ ] **Step 1: Read both entry.md files.** + +- [ ] **Step 2: Infer location.** + +Entry 1 (2025-10-11): "600km of Tuscany Begins with an Aperitif" — route starts at Venturina Terme (from GPX filename). City: Venturina Terme, Italy. Lat: 43.0183, Lng: 10.6059. + +Entry 2 (2025-10-16): read title + body to determine. + +- [ ] **Step 3: Estimate weather.** + +Tuscany, October: 18°C, partly cloudy (typical autumn). + +- [ ] **Step 4: Write the review doc.** + +Create `docs/enrichment/italy-2025.md` with the same structure, 2 data rows. + +- [ ] **Step 5: Commit.** + +```bash +cd /home/mischa/Projects/travel-blog-intotheeast +git add docs/enrichment/italy-2025.md +git commit -m "docs: add italy-2025 enrichment review doc" +``` + +- [ ] **Step 6: Prompt user to review.** + +Tell the user: "Review doc generated at `docs/enrichment/italy-2025.md`. Please open it, correct any values, and let me know when ready to apply." + +--- + +## Task 6: Apply italy-2025 enrichment (after user approval) + +**Files:** +- Read: `docs/enrichment/italy-2025.md` +- Modify: `user/pages/01.trips/italy-2025/01.dailies/*/entry.md` (2 files) + +**Prerequisite:** User has reviewed and approved `docs/enrichment/italy-2025.md`. + +- [ ] **Step 1: Read the reviewed doc and parse rows.** + +- [ ] **Step 2: Extract coordinates from Map Links.** + +- [ ] **Step 3: Apply to both entry.md files** — update six frontmatter fields. + +- [ ] **Step 4: Verify** — read both files back, confirm fields are set. + +- [ ] **Step 5: Commit and sync** + +```bash +cd /home/mischa/Projects/travel-blog-intotheeast && git add user/pages/01.trips/italy-2025/01.dailies/ +git commit -m "content: enrich italy-2025 entries with location and weather" +make content-push +``` + +--- + +## Self-Review Notes + +- All 36 entries covered across 6 tasks (3 generate + 3 apply) +- Human review gates are explicit: each "apply" task has a **Prerequisite** line +- Coordinate extraction rules cover both OSM and Google Maps URL formats +- Weather reference tables provide concrete values — no vague "look it up" +- `make content-push` only runs after the final trip to avoid partial syncs +- No test files needed — this is data enrichment; verification steps replace TDD