m038/intotheeast-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add entry enrichment implementation plan

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vgmzx8VTTTmCskSpQtsLTr
This commit is contained in:
Mischa
2026-06-21 12:43:46 +02:00
parent 647f76333d
commit 93aa6d9b42
1 changed files with 327 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-06-21-entry-enrichment.md
+327
View File
@@ -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