m038andClaude Opus 5
8202d2a257
Five weeks of undocumented evolution left the docs describing a site that
partly no longer exists, with nothing marking which documents were historical.
The code is treated as the source of truth throughout; every claim below was
verified against code, config or the Makefile rather than inferred.
Two mechanisms, following patterns the repo already used:
- docs/reference/superseded-decisions.md (new) — one authoritative table of all
14 reversals: what was planned, where, what is true now, when, and why. Plus
a short list of decisions that were NOT reversed, since their planning docs
are old enough to look suspect.
- Inline "> **Superseded ...**" notes at each stale claim, so a claim can never
be read un-corrected. This mirrors the existing "> History:" notes in
architecture.md and "> **Changed 2026-07:**" in trip-switching.md.
Scope split by tense: present-tense docs (CLAUDE.md, reference/, guides/,
README.md, CONCEPTS.md) are corrected; past-tense records (plans/, specs/,
milestones/, summary.md, pm-analysis.md) are annotated only, never rewritten —
their staleness is what makes them records.
Present-tense corrections:
- CLAUDE.md asserted css-compiled/ is generated from css/style.css and
css/tokens.css. That source relationship does not exist: css/ is hand-authored
and served directly via assets.addCss in partials/base.html.twig, while
css-compiled/ is esbuild output from the CSS imports inside js/src/*.js.
Highest-severity finding — an always-loaded file inviting a hand-edit of a
generated bundle.
- README.md documented every remote-* target without the -test/-prod suffix
guard-env requires, so its entire server runbook was unrunnable, and listed
7 of ~20 targets while CLAUDE.md designates it authoritative for the full
list. Rewritten with all targets, grouped, and the suffix rule stated.
- README.md told readers to "git clone" into user/, which is a submodule.
- architecture.md: nav is Home + Trips + (authenticated) New Post, not
"Home + Past Trips only"; template tree omitted trips.html.twig,
post-form.html.twig and forms/, and placed base.html.twig at templates/ root
rather than in partials/; entry-actions has three API routes, not just delete;
added the undocumented css-compiled/maplibre-gl.css output and a section on
the /post pin editor as the one sanctioned non-entry-map map.
- design-system.md: documented 13 colour tokens against 19 in tokens.css
(missing --color-error, --color-draft-accent and four glass overlays); claimed
"all 3 map templates"; and described --color-canvas as "white".
- design-system-light.md documented a light palette in present tense. No light
mode exists — tokens.css has a single :root block, no prefers-color-scheme or
data-theme switch, and no light hex appears in css/. Banner added.
- posting.md said photos were optional; they are required, 1-6. It documented
hero_image, which was removed for entries (stories keep it). It had no mention
of the frontend edit flow or photo editor, both shipped 2026-07-08. Photo
files are photo-01..NN, zero-padded.
- working/README.md advertised summary.md as the project's "current state" while
summary.md describes Leaflet, /tracker, /map and /stats. Most misleading line
in the tree.
- CLAUDE.md: recorded js/src/location-map.js as the one sanctioned exception to
the single-map-path rule, and documented that make start/setup fail on a clean
checkout because docker-compose.yml still builds a travel-memories service
whose source moved out in a80b0a9.
Also: 2026-07-23-post-form-location-override.md read "Not started" while merged
in user/ as dd19995; status corrected.
Findings that are not documentation problems — the compose breakage, a
repeatable drift check, the unused shortcode-gallery-plusplus, and demo fixtures
for retired views — are collected in
docs/working/2026-07-25-doc-drift-recommendations.md and deliberately not acted
on. Design and verification method: docs/working/specs/2026-07-25-docs-reconciliation-design.md
The submodule gitlink is deliberately not bumped.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
8.4 KiB
PM Analysis — What to Build (and What to Skip)
Role: Senior Product Manager. Audience: one solo traveler (Mischa), platform: Grav CMS flat-file PHP, no native app.
Historical — written 2026-06-21. The verdicts still hold; some delivery mechanisms do not.
The SKIP column is still the standing decision and has not been revisited — background GPS, followers, comments, social discovery, reactions, reels, 3D flyover, print, and AI itineraries remain deliberately out of scope. What changed is how some BUILD items shipped: the map and stats render inline on the trip page rather than as
/mapand/stats, MapLibre replaced Leaflet, galleries use PhotoSwipe rather thanshortcode-gallery-plusplus, andhero_imagewas dropped for entries. See../reference/superseded-decisions.md.
Starting position
Polarsteps and FindPenguins are native mobile apps built around:
- Background GPS tracking (requires OS-level access)
- Social networks (followers, discovery, comments)
- App-side video/reel processing
None of these three pillars are reproducible in a web CMS. Any plan that tries to replicate them wholesale is delusional. What we can do is cherry-pick the outputs — the things those apps display to readers — and build them into the blog in ways that add real value to both Mischa (the poster) and readers (friends/family following along).
Feature-by-Feature Audit
| Feature | Makes sense solo? | Buildable in Grav+JS? | Value to readers? | Worth the cost? | Decision |
|---|---|---|---|---|---|
| Auto background GPS tracking | No — posting manually anyway | No — requires native app | — | — | SKIP |
| Interactive map of visited locations | Yes | Yes — Leaflet.js + frontmatter lat/lng | High | High | BUILD |
| Route line on map between entries | Yes | Yes — connect entry coords in order | High | Medium | BUILD |
| Entry location name (city, country) | Yes | Yes — manual input on form | High | Low | BUILD |
| Weather metadata per entry | Yes | Yes — Open-Meteo free API, no key needed | Medium | Medium | BUILD |
| Photo gallery per entry | Yes | Yes — shortcode-gallery-plusplus installed | High | Low | BUILD (already partial) |
| Hero image on feed cards | Yes | Yes — already in frontmatter | High | Low | BUILD |
| Trip statistics page | Yes | Yes — compute from frontmatter | Medium | Low | BUILD |
| Countries visited world map | Yes | Yes — highlight SVG or Leaflet layers | Medium | Medium | BUILD |
| Follower system | No — solo blog | Would need auth + DB | None | — | SKIP |
| Comments on entries | No — spam risk, no community | Would need plugin + moderation | Minimal | — | SKIP |
| Social discovery / explore | No — not a platform | Would need indexing infrastructure | None | — | SKIP |
| Group trip / travel buddies | No — solo trip | — | — | — | SKIP |
| Reactions / likes | No | — | — | — | SKIP |
| 3D flyover video | No — proprietary pipeline | No | Nice | — | SKIP |
| Trip reels / short video | No — app-side processing | No | Nice | — | SKIP |
| Travel book / print | No — out of scope | No | — | — | SKIP |
| AI itinerary builder | No — trip already started | No | — | — | SKIP |
| Flight detection | No — requires native app sensors | No | — | — | SKIP |
| Delayed sharing / live location | No — blog posts after the fact | Irrelevant | — | — | SKIP |
| Offline posting | Already works | Already works (Grav form offline) | — | — | ALREADY EXISTS |
| Scheduled / draft posts | Already exists | Already exists (publish_date) | — | — | ALREADY EXISTS |
| Step suggestions / nudges | No — push notifications not possible | No | — | — | SKIP |
| Eebook / export | No — out of scope | Possible but niche | — | — | SKIP |
What to Build — Summary
Keep (already exists, just needs to work reliably)
- Login-gated mobile posting form ✓
- Draft and scheduled publishing ✓
Build
1. Entry enrichment — make each entry richer with zero extra effort from Mischa:
- Location name (city, country) captured at post time
- Weather auto-fetched via Open-Meteo at post time using lat/lng
- Photos displayed in a proper gallery (lightbox)
- Hero image shown on feed card
2. Interactive map — the single most "Polarsteps-like" thing that's genuinely achievable:
/mappage with Leaflet.js- Marker per entry (lat/lng from frontmatter)
- Route line connecting entries in date order
- Popup with title, date, thumbnail, link to entry
- Mobile-friendly (touch pan/zoom)
3. Trip statistics — a simple stats page:
- Days on the road (count of entries with distinct dates)
- Entries posted
- Countries/regions visited (derived from location name field)
- Approx distance traveled (sum of haversine distances between GPS points)
What to Skip — with reasons
| Feature | Reason skipped |
|---|---|
| Background GPS tracking | Requires native app. Grav runs on a server. |
| Social features (followers, comments, likes) | Adds spam risk, moderation burden, zero value for a solo travel blog with a personal audience. A "share link" is enough. |
| Video reels | App-side video processing pipeline, not available in a web CMS. |
| 3D flyover | Proprietary rendering. Not worth building from scratch. |
| Travel book printing | Out of scope. Mischa can use Polarsteps or FindPenguins for this if desired. |
| AI itinerary builder | Trip is already in progress. Out of scope. |
| Discovery / explore | Not a platform. No community. |
| Group trips | Solo traveler. |
| Flight detection | Requires native OS sensor access. |
| Delayed sharing | Moot — we don't broadcast real-time location at all. |
Milestone Plan
Milestone 1 — Entry Enrichment (2–3 days)
Goal: Every entry is richer out of the box — photo gallery works, location name shown, weather captured, hero image on feed.
Features:
- Location name field (city + country) added to post form and displayed on entries/cards
- Weather auto-fetch on post form (JS call to Open-Meteo using entered lat/lng, fills hidden fields)
- Weather displayed on entry page
- Photo gallery working (shortcode-gallery-plusplus or native media display)
- Hero image shown on tracker feed cards
Value: Immediate. Makes each entry feel like a real travel log entry, not just a text post.
Milestone 2 — Interactive Map (2–3 days)
Goal: A /map page shows all entries as markers on an interactive Leaflet.js map, connected by a route line, with popups.
Features:
- New
mappage and template - Leaflet.js loaded from CDN (no build step)
- Entries serialized to JSON in the template (lat/lng, title, date, url, hero_image)
- Route polyline in chronological order
- Marker popup: date, title, thumbnail, "Read entry →" link
- Map added to site navigation
Value: High for readers — gives a bird's-eye view of the trip. The single most compelling "where is Mischa?" feature.
Milestone 3 — Statistics Page (1–2 days)
Goal: A /stats page with key trip numbers.
Features:
- Days on the road (first entry date to today)
- Total entries posted
- Unique countries visited (derived from location names)
- Approximate distance traveled (haversine between consecutive entry GPS points)
- Simple, scannable layout — no charts needed for v1
Value: Medium — nice context for readers, satisfying for Mischa to see progress.
Milestone 4 — Map on Tracker Feed (1 day)
Goal: A mini-map showing recent positions above or alongside the feed, so the first thing readers see is "where is Mischa now?"
Features:
- Small embedded Leaflet map on the tracker/feed page
- Shows last 10 entries as markers, with the most recent highlighted
- Route line between them
- Tapping a marker opens the entry
Value: Medium — gives context to the feed without navigating away. Nice "current location" feel.
Milestone Priority Order
M1 first — entry quality affects every post Mischa makes from day 1 of the trip. Get this right immediately.
M2 second — the map is the headline feature that makes this feel like a Polarsteps-style blog. Technically independent from M1 (uses lat/lng already in frontmatter).
M3 third — stats are a nice-to-have. Easy to add once M1 and M2 are stable.
M4 fourth — the mini-map on the feed is polish. Only worth doing once the full map (M2) is solid.