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

docs: mark documentation restructure plan as complete

Browse Source
This commit is contained in:
Mischa
2026-06-21 14:10:32 +02:00
parent 7c63e98f5a
commit 72afc73065
1 changed files with 49 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/working/plans/2026-06-21-documentation-restructure.md
+49 -49
View File
@@ -1,6 +1,6 @@
# Documentation Restructure 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.
> **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 (`- [x]`) syntax for tracking.
**Goal:** Restructure `docs/` from an organic flat layout into a type-first hierarchy (`guides/`, `reference/`, `working/`, `research/`) serving two personas: Mischa and Claude.
@@ -25,7 +25,7 @@
- Create directories: `docs/guides/`, `docs/reference/`, `docs/working/specs/`, `docs/working/plans/`, `docs/working/qa/`, `docs/working/milestones/`, `docs/research/`
- Move: all 49 existing files under `docs/` to their new locations
- [ ] **Step 1: Create the new directory tree**
- [x] **Step 1: Create the new directory tree**
```bash
mkdir -p /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides
@@ -37,7 +37,7 @@ mkdir -p /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/working/mi
mkdir -p /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/research
```
- [ ] **Step 2: Move specs/ and plans/ (bulk)**
- [x] **Step 2: Move specs/ and plans/ (bulk)**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -53,7 +53,7 @@ for f in docs/working/plans/*.md; do
done
```
- [ ] **Step 3: Move milestone specs**
- [x] **Step 3: Move milestone specs**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -63,7 +63,7 @@ git mv docs/working/milestones/milestone-3.md docs/working/milestones/milestone-
git mv docs/working/milestones/milestone-4.md docs/working/milestones/milestone-4.md
```
- [ ] **Step 4: Move QA docs**
- [x] **Step 4: Move QA docs**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -71,7 +71,7 @@ git mv docs/qa-test-plan.md docs/working/qa/test-plan.md
git mv docs/qa-results.md docs/working/qa/results.md
```
- [ ] **Step 5: Move remaining working/ docs**
- [x] **Step 5: Move remaining working/ docs**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -82,7 +82,7 @@ git mv docs/production-todo.md docs/working/production-todo.md
git mv docs/summary.md docs/working/summary.md
```
- [ ] **Step 6: Move research docs**
- [x] **Step 6: Move research docs**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -91,7 +91,7 @@ git mv docs/research-findpenguins.md docs/research/findpenguins.md
git mv docs/research-story-editing.md docs/research/story-editing.md
```
- [ ] **Step 7: Move design system to reference/**
- [x] **Step 7: Move design system to reference/**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -99,14 +99,14 @@ git mv docs/design/design-spec.md docs/reference/design-system.md
rmdir docs/design # now empty
```
- [ ] **Step 8: Move posting pipeline to guides/ (base for Task 4)**
- [x] **Step 8: Move posting pipeline to guides/ (base for Task 4)**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
git mv docs/guides/posting.md docs/guides/posting.md
```
- [ ] **Step 9: Verify — no files remain at docs/ root, no docs/working/ exists**
- [x] **Step 9: Verify — no files remain at docs/ root, no docs/working/ exists**
```bash
find /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs -maxdepth 1 -type f
@@ -122,7 +122,7 @@ ls /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/working/plans/ |
# Expected: 19 (18 original + this plan)
```
- [ ] **Step 10: Commit**
- [x] **Step 10: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -139,28 +139,28 @@ git commit -m "docs: restructure docs/ into guides/ reference/ working/ research
After the moves, links inside plan and spec files still point to old paths like `docs/working/plans/...` and `docs/working/milestones/milestone-1.md`. This task fixes them all.
- [ ] **Step 1: Replace docs/working/specs/ references**
- [x] **Step 1: Replace docs/working/specs/ references**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
grep -rl "docs/working/specs/" docs/ | xargs sed -i 's|docs/working/specs/|docs/working/specs/|g'
```
- [ ] **Step 2: Replace docs/working/plans/ references**
- [x] **Step 2: Replace docs/working/plans/ references**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
grep -rl "docs/working/plans/" docs/ | xargs sed -i 's|docs/working/plans/|docs/working/plans/|g'
```
- [ ] **Step 3: Replace docs/working/ catch-all (any remaining bare references)**
- [x] **Step 3: Replace docs/working/ catch-all (any remaining bare references)**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
grep -rl "docs/working/" docs/ | xargs sed -i 's|docs/working/|docs/working/|g'
```
- [ ] **Step 4: Replace milestone spec references**
- [x] **Step 4: Replace milestone spec references**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -170,14 +170,14 @@ grep -rl "docs/milestone-3-spec" docs/ | xargs sed -i 's|docs/milestone-3-spec\.
grep -rl "docs/milestone-4-spec" docs/ | xargs sed -i 's|docs/milestone-4-spec\.md|docs/working/milestones/milestone-4.md|g'
```
- [ ] **Step 5: Replace posting-pipeline reference**
- [x] **Step 5: Replace posting-pipeline reference**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
grep -rl "docs/posting-pipeline" docs/ | xargs sed -i 's|docs/posting-pipeline\.md|docs/guides/posting.md|g'
```
- [ ] **Step 6: Fix references inside CLAUDE.md**
- [x] **Step 6: Fix references inside CLAUDE.md**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -186,7 +186,7 @@ sed -i 's|docs/working/plans/|docs/working/plans/|g' CLAUDE.md
sed -i 's|docs/working/|docs/working/|g' CLAUDE.md
```
- [ ] **Step 7: Verify no old paths remain**
- [x] **Step 7: Verify no old paths remain**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -198,7 +198,7 @@ grep -r "docs/posting-pipeline" docs/ CLAUDE.md
# Expected: no output
```
- [ ] **Step 8: Commit**
- [x] **Step 8: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -213,7 +213,7 @@ git commit -m "docs: fix all internal cross-references after restructure"
**Files:**
- Create: `docs/README.md`
- [ ] **Step 1: Write docs/README.md**
- [x] **Step 1: Write docs/README.md**
Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/README.md` with this content:
@@ -250,14 +250,14 @@ Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/README.md`
**Raw research input** → [`research/`](research/)
```
- [ ] **Step 2: Verify**
- [x] **Step 2: Verify**
```bash
cat /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/README.md
# Expected: the full content above, no truncation
```
- [ ] **Step 3: Commit**
- [x] **Step 3: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -274,7 +274,7 @@ git commit -m "docs: add README.md navigation index"
The moved `posting-pipeline.md` is a technical reference. Reformat it as a step-by-step guide for Mischa, preserving all factual content, adding a quick-start at the top and a troubleshooting section at the bottom.
- [ ] **Step 1: Rewrite docs/guides/posting.md**
- [x] **Step 1: Rewrite docs/guides/posting.md**
Replace the full content of `docs/guides/posting.md` with:
@@ -396,7 +396,7 @@ Every entry supports these frontmatter fields:
→ Run `make fix-perms` to restore container file ownership.
```
- [ ] **Step 2: Verify**
- [x] **Step 2: Verify**
```bash
grep -c "Quick start" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/posting.md
@@ -406,7 +406,7 @@ grep -c "Troubleshooting" /home/mischa/Nextcloud/Projects/travel-blog-intotheeas
# Expected: 1
```
- [ ] **Step 3: Commit**
- [x] **Step 3: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -421,7 +421,7 @@ git commit -m "docs: rewrite posting guide as user-facing step-by-step"
**Files:**
- Create: `docs/guides/gpx-manager.md`
- [ ] **Step 1: Write docs/guides/gpx-manager.md**
- [x] **Step 1: Write docs/guides/gpx-manager.md**
Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/gpx-manager.md` with this content:
@@ -513,7 +513,7 @@ GPX files are registered as a valid media type in `user/config/media.yaml`, so G
No manual linking is needed — upload and it appears.
```
- [ ] **Step 2: Verify**
- [x] **Step 2: Verify**
```bash
grep -c "slugif" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/gpx-manager.md
@@ -523,7 +523,7 @@ grep -c "Komoot" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/gu
# Expected: >= 3
```
- [ ] **Step 3: Commit**
- [x] **Step 3: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -538,7 +538,7 @@ git commit -m "docs: add GPX manager guide"
**Files:**
- Create: `docs/guides/trip-switching.md`
- [ ] **Step 1: Write docs/guides/trip-switching.md**
- [x] **Step 1: Write docs/guides/trip-switching.md**
Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/trip-switching.md` with this content:
@@ -551,10 +551,10 @@ When you start a new trip, **two files must be updated together** — if only on
## Checklist
- [ ] Update `user/config/site.yaml` → `active_trip`
- [ ] Update `user/pages/02.post/post-form.md` → `pageconfig.parent`
- [ ] Create the new trip page tree (see below)
- [ ] Run `make content-push` to push the changes to production
- [x] Update `user/config/site.yaml` → `active_trip`
- [x] Update `user/pages/02.post/post-form.md` → `pageconfig.parent`
- [x] Create the new trip page tree (see below)
- [x] Run `make content-push` to push the changes to production
---
@@ -634,7 +634,7 @@ After pushing, check:
3. Map at `/trips/<new-slug>/map` shows the correct (empty or GPX-only) state
```
- [ ] **Step 2: Verify**
- [x] **Step 2: Verify**
```bash
grep -c "checklist\|Checklist" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/trip-switching.md
@@ -644,7 +644,7 @@ grep -c "pageconfig.parent" /home/mischa/Nextcloud/Projects/travel-blog-intothee
# Expected: >= 2
```
- [ ] **Step 3: Commit**
- [x] **Step 3: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -660,7 +660,7 @@ git commit -m "docs: add trip switching guide"
- Create: `docs/guides/local-setup.md`
- Modify: `CLAUDE.md` — replace §2 with pointer; add superpowers skill path overrides
- [ ] **Step 1: Write docs/guides/local-setup.md**
- [x] **Step 1: Write docs/guides/local-setup.md**
Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/local-setup.md` with this content:
@@ -780,7 +780,7 @@ languages:
Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites.
```
- [ ] **Step 2: Replace CLAUDE.md §2 with pointer and add skill path overrides**
- [x] **Step 2: Replace CLAUDE.md §2 with pointer and add skill path overrides**
In `CLAUDE.md`, replace the entire `## 2. Local development setup` section (from `## 2.` through the end of the Language URL prefix block) with:
@@ -797,7 +797,7 @@ Plans: `docs/working/plans/YYYY-MM-DD-<topic>.md`
The brainstorming and writing-plans skills default to `docs/working/`; these lines override that default.
```
- [ ] **Step 3: Verify CLAUDE.md**
- [x] **Step 3: Verify CLAUDE.md**
```bash
grep -c "Local development setup" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/CLAUDE.md
@@ -814,7 +814,7 @@ grep -c "First-time setup after cloning" /home/mischa/Nextcloud/Projects/travel-
# Expected: 0
```
- [ ] **Step 4: Verify local-setup.md**
- [x] **Step 4: Verify local-setup.md**
```bash
grep -c "make setup" /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/guides/local-setup.md
@@ -824,7 +824,7 @@ grep -c "include_default_lang" /home/mischa/Nextcloud/Projects/travel-blog-intot
# Expected: 1
```
- [ ] **Step 5: Commit**
- [x] **Step 5: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -839,7 +839,7 @@ git commit -m "docs: extract local setup guide from CLAUDE.md; add skill path ov
**Files:**
- Create: `docs/reference/architecture.md`
- [ ] **Step 1: Write docs/reference/architecture.md**
- [x] **Step 1: Write docs/reference/architecture.md**
Create `/home/mischa/Nextcloud/Projects/travel-blog-intotheeast/docs/reference/architecture.md` with this content:
@@ -993,7 +993,7 @@ Rendered as route polyline on map
| `CLAUDE.md` | Project rules and always-loaded context for Claude |
```
- [ ] **Step 2: Verify**
- [x] **Step 2: Verify**
```bash
grep -c "Plugin roles\|Template hierarchy\|GPX data flow\|Data flow for a post" \
@@ -1001,7 +1001,7 @@ grep -c "Plugin roles\|Template hierarchy\|GPX data flow\|Data flow for a post"
# Expected: 4
```
- [ ] **Step 3: Commit**
- [x] **Step 3: Commit**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -1018,7 +1018,7 @@ git commit -m "docs: add architecture overview reference"
Four memory files still reference `docs/working/` paths. Update them to `docs/working/`.
- [ ] **Step 1: Identify affected lines**
- [x] **Step 1: Identify affected lines**
```bash
MEMORY_DIR="/home/mischa/.claude/projects/-home-mischa-Nextcloud-Projects-travel-blog-intotheeast/memory"
@@ -1026,7 +1026,7 @@ grep -n "docs/superpowers" "$MEMORY_DIR/MEMORY.md" "$MEMORY_DIR/feedback-plan-ex
"$MEMORY_DIR/project-story-mode-and-maplibre.md" "$MEMORY_DIR/project-homepage-redesign.md"
```
- [ ] **Step 2: Apply sed replacements**
- [x] **Step 2: Apply sed replacements**
```bash
MEMORY_DIR="/home/mischa/.claude/projects/-home-mischa-Nextcloud-Projects-travel-blog-intotheeast/memory"
@@ -1038,7 +1038,7 @@ for f in "$MEMORY_DIR/MEMORY.md" "$MEMORY_DIR/feedback-plan-execution-gap.md" \
done
```
- [ ] **Step 3: Verify no old paths remain in memory**
- [x] **Step 3: Verify no old paths remain in memory**
```bash
MEMORY_DIR="/home/mischa/.claude/projects/-home-mischa-Nextcloud-Projects-travel-blog-intotheeast/memory"
@@ -1046,7 +1046,7 @@ grep -r "docs/superpowers" "$MEMORY_DIR/"
# Expected: no output
```
- [ ] **Step 4: Commit memory project memory update to docs repo**
- [x] **Step 4: Commit memory project memory update to docs repo**
Memory files are not in the git repo, so no commit needed. But update the memory pointer in MEMORY.md to reference the plans stored at their new location.
@@ -1058,7 +1058,7 @@ grep "plans\|specs\|superpowers\|working" \
# Expected: all plan/spec references point to docs/working/, none to docs/working/
```
- [ ] **Step 5: Final verification — complete restructure**
- [x] **Step 5: Final verification — complete restructure**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast
@@ -1088,7 +1088,7 @@ grep "docs/working/specs\|docs/working/plans" CLAUDE.md
# Expected: 2 lines
```
- [ ] **Step 6: Commit final state**
- [x] **Step 6: Commit final state**
```bash
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast