m038/intotheeast-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
203737cc3fc349aefbbde066b25842000ee1c061
intotheeast-com/docs/working/specs/2026-06-21-documentation-restructure-design.md
T

8.0 KiB
Raw Blame History

Documentation Restructure — Design Spec

Date: 2026-06-21 Scope: Full restructure of docs/ from organic flat layout to type-first hierarchy serving two personas: Mischa and Claude.

Problem

The docs/ folder grew organically: milestone specs, design specs, plans, QA docs, research, and how-tos sit at the same level with no clear navigation. There is no operational how-to for posting, GPX management, or trip switching. CLAUDE.md contains setup and architecture detail that inflates its size and makes it harder to scan.

Goals

  1. Two personas find what they need without searching: Mischa (poster, PM, designer, dev) and Claude (AI assistant).
  2. guides/ is written for Mischa now but extensible to external users later (future: publish as a Grav CMS travel setup).
  3. CLAUDE.md stays lean — inline context only, no content duplicated from docs/.

Folder Structure

docs/
  guides/               ← operational how-tos; Mischa-facing; extensible to external users
  reference/            ← stable facts: design system, architecture
  working/              ← active project docs: specs, plans, QA, backlog, milestones
    specs/
    plans/
    qa/
    milestones/
  research/             ← raw discovery input
  README.md             ← navigation index

Persona mapping

Persona Primary sections
Mischa (operational) guides/ for how-tos; working/ for PM status
Mischa (design/dev) reference/ for design system + architecture
Claude working/specs/ + working/plans/ for active context; reference/ for stable facts; CLAUDE.md for always-loaded project rules

File Migration

guides/ — new and extracted content

File Source
guides/posting.md new — end-to-end posting flow
guides/gpx-manager.md new — GPX upload/delete/slug/Komoot workaround
guides/trip-switching.md new — 3-file checklist, expanded
guides/local-setup.md extracted from CLAUDE.md §2

reference/ — moved and new

File Source
reference/design-system.md moved from docs/design/design-spec.md
reference/architecture.md new — stack, plugin roles, template hierarchy, post-submission data flow

working/ — moved and renamed

New path Current path
working/specs/* (13 files) docs/working/specs/*
working/plans/* (14 files) docs/working/plans/*
working/milestones/milestone-1.md docs/working/milestones/milestone-1.md
working/milestones/milestone-2.md docs/working/milestones/milestone-2.md
working/milestones/milestone-3.md docs/working/milestones/milestone-3.md
working/milestones/milestone-4.md docs/working/milestones/milestone-4.md
working/backlog.md docs/backlog.md
working/production-todo.md docs/production-todo.md
working/pm-analysis.md docs/pm-analysis.md
working/qa/test-plan.md docs/qa-test-plan.md
working/qa/results.md docs/qa-results.md
working/bugs-and-fixes.md docs/bugs-and-fixes.md
working/summary.md docs/summary.md

research/ — moved and renamed

New path Current path
research/polarsteps.md docs/research-polarsteps.md
research/findpenguins.md docs/research-findpenguins.md
research/story-editing.md docs/research-story-editing.md

New Content

guides/posting.md

Covers: opening /post, all form fields (title, body, location, weather fetch, lat/lng, photos), what happens on submit (form plugin → add-page-by-form → cache-on-save), how to verify the entry appeared, common failure modes (cache not cleared, entry in wrong trip folder).

guides/gpx-manager.md

Covers: logging in, upload flow, slug rules (spaces/special chars → hyphens, lowercase), how slugification works (client-side Blob trick), delete flow, how to bypass the UI (drop file into user/pages/01.trips/<slug>/ + make content-push), Komoot manual export workaround (no API integration yet).

guides/trip-switching.md

Covers: the 3-file checklist — user/config/site.yaml (active_trip), user/pages/02.post/post-form.md (pageconfig.parent) — why both must match, what breaks silently if they don't (entries post to wrong folder), and the new trip page tree to create under user/pages/01.trips/<new-slug>/.

guides/local-setup.md

Covers: first-time setup after clone (mkdir -p user/plugins user/data, make setup), fix-perms after 500 errors, Grav 2.0 upgrade process (update Dockerfile URL + make setup), required system.yaml settings (accounts.type: flex, pages.type: flex), admin user API permissions, disabling old admin plugin, language URL prefix fix.

reference/architecture.md

Covers:

  • Stack: Grav 2.0.0-rc.10 + Admin2, Docker image, PHP session config
  • Plugin roles: form (built-in) → add-page-by-form (third-party) → cache-on-save (custom); what each does in the post-submission pipeline
  • Template hierarchy: base.html.twig extended by all page templates; key templates: trip.html.twig, entry.html.twig, map.html.twig, stats.html.twig, gpx-manager.html.twig
  • Data flow for a post: form submit → page created in dailies folder → cache cleared → entry visible in feed
  • GPX pipeline: files on trip page media → picked up by map.html.twig via trip_page.media.all → rendered by MapLibre

docs/README.md

# docs/

## If you're Mischa
- **Doing something?** → guides/
- **Checking project status?** → working/backlog.md, working/production-todo.md
- **Design or architecture decisions?** → reference/

## If you're Claude
- **Project rules + always-needed context** → CLAUDE.md (root)
- **Active specs and plans** → working/specs/, working/plans/
- **Stable facts** → reference/
- **Raw research** → research/

CLAUDE.md Changes

Remove (moves to docs/):

  • §2 local development setup → docs/guides/local-setup.md; replace with one-line pointer
  • Architecture/plugin detail → docs/reference/architecture.md; replace with one-line pointer

Add (superpowers skill path overrides):

### Superpowers skill paths
Specs: `docs/working/specs/YYYY-MM-DD-<topic>-design.md`
Plans: `docs/working/plans/YYYY-MM-DD-<topic>.md`

The brainstorming and writing-plans skills default to docs/working/; these lines override that default so generated files land in the right place automatically.

Keep inline (always-loaded context Claude needs without following a link):

  • §0 project specifics (folder layout, stack versions, trip entity architecture, active trip, GPX pipeline, env rules, remote operations, content sync, gitignore)
  • §1 environment modes (dev vs. prod settings, cache-on-save behaviour)
  • Language URL prefix gotcha
  • Grav 2.0 config requirements (flex accounts/pages, admin user permissions)

Out of Scope

  • End-user documentation (blog readers) — deferred until external publish decision
  • user/docs/ folder — separate git repo; not restructured here
  • Memory files (~/.claude/projects/*/memory/) — not part of docs/; maintained separately
  • Design/UX wireframes — stay in existing spec files, not reorganized further

Acceptance Criteria

  1. docs/ contains exactly four subdirectories: guides/, reference/, working/, research/
  2. All 32+ existing files are moved to their new paths; no files remain at docs/ root except README.md
  3. docs/working/ no longer exists; content is under working/
  4. Four new guides exist and cover their stated scope
  5. reference/architecture.md exists and covers stack, plugin roles, template hierarchy, and post data flow
  6. docs/README.md exists with persona-based navigation
  7. CLAUDE.md no longer contains §2 local setup block; contains pointer to docs/guides/local-setup.md
  8. All internal cross-references in moved files updated to new paths
  9. Memory files that reference docs/working/ paths updated to docs/working/
  10. CLAUDE.md contains superpowers skill path overrides pointing to docs/working/specs/ and docs/working/plans/
Reference in New Issue View Git Blame Copy Permalink