跳转到内容
IntelliFuture Docs

2026-04-03-yomiya-docs-restructure

Yomiya Docs Restructure Implementation Plan

Section titled “Yomiya Docs Restructure Implementation Plan”

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Reorganize product/YomiyaContentSystem into a reader-friendly dual-layer structure that preserves existing reasoning detail while compressing the default execution path into a few core documents.

Architecture: Keep all existing content, but separate it into execution-layer docs and evidence-layer docs. Build the new directory structure first, then migrate and rewrite entrypoint docs, then relocate legacy and research material with clear role boundaries.

Tech Stack: Markdown, filesystem reorganization, git

Task 1: Create the new top-level directory skeleton

Section titled “Task 1: Create the new top-level directory skeleton”

Files:

  • Create: product/YomiyaContentSystem/00-Start-Here/README.md
  • Create: product/YomiyaContentSystem/10-Current-System/README.md
  • Create: product/YomiyaContentSystem/20-Execution-Spec/README.md
  • Create: product/YomiyaContentSystem/30-Research-and-Evidence/README.md
  • Create: product/YomiyaContentSystem/40-History-and-Decisions/README.md
  • Create: product/YomiyaContentSystem/50-Future-Questions/README.md

Step 1: Create the directories

Run:

Terminal window
mkdir -p \
  product/YomiyaContentSystem/00-Start-Here \
  product/YomiyaContentSystem/10-Current-System \
  product/YomiyaContentSystem/20-Execution-Spec \
  product/YomiyaContentSystem/30-Research-and-Evidence/foundations \
  product/YomiyaContentSystem/30-Research-and-Evidence/competitive-analysis \
  product/YomiyaContentSystem/30-Research-and-Evidence/samples \
  product/YomiyaContentSystem/30-Research-and-Evidence/mapping-notes \
  product/YomiyaContentSystem/40-History-and-Decisions/legacy-specs \
  product/YomiyaContentSystem/40-History-and-Decisions/review-logs \
  product/YomiyaContentSystem/40-History-and-Decisions/split-history \
  product/YomiyaContentSystem/50-Future-Questions

Expected: all new directories exist.

Step 2: Add README stubs for each directory

Each README should explain:

  • what lives in this directory
  • whether it is default reading or support material
  • what it can and cannot override

Step 3: Verify the tree

Run:

Terminal window
find product/YomiyaContentSystem -maxdepth 2 -type d | sort

Expected: the new 00/10/20/30/40/50 structure appears.

Step 4: Commit

Terminal window
git add product/YomiyaContentSystem
git commit -m "docs: add Yomiya doc restructure skeleton"

Task 2: Rewrite the root README as the master navigation page

Section titled “Task 2: Rewrite the root README as the master navigation page”

Files:

  • Modify: product/YomiyaContentSystem/README.md

Step 1: Write the new root README

It must include:

  • the new directory map
  • the default reading path
  • the authority relationship between 00, 10, 20, 30, 40, 50
  • role-based reading routes

Step 2: Verify internal links and wording

Run:

Terminal window
sed -n '1,240p' product/YomiyaContentSystem/README.md

Expected: no references to the retired 01-05 as active top-level structure.

Step 3: Commit

Terminal window
git add product/YomiyaContentSystem/README.md
git commit -m "docs: rewrite Yomiya root navigation"

Task 3: Build the execution-layer action plan

Section titled “Task 3: Build the execution-layer action plan”

Files:

  • Create: product/YomiyaContentSystem/00-Start-Here/yomiya-action-plan.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-delivery-plan.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-execution-spec.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-scope-boundary.md

Step 1: Extract the current actionable conclusions

Capture:

  • Phase 1 current objective
  • current must-do scope
  • role ownership
  • milestone order
  • what is intentionally deferred

Step 2: Write yomiya-action-plan.md

Use concise sections only for execution-facing content. Add references to the deeper docs for details.

Step 3: Verify it can be read standalone

Run:

Terminal window
sed -n '1,260p' product/YomiyaContentSystem/00-Start-Here/yomiya-action-plan.md

Expected: a reader can know what to do next without opening five files first.

Step 4: Commit

Terminal window
git add product/YomiyaContentSystem/00-Start-Here/yomiya-action-plan.md
git commit -m "docs: add Yomiya action plan"

Task 4: Move the current system source-of-truth into the new reality layer

Section titled “Task 4: Move the current system source-of-truth into the new reality layer”

Files:

  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-system-source-of-truth.md
  • Destination: product/YomiyaContentSystem/10-Current-System/yomiya-system-source-of-truth.md
  • Modify: product/YomiyaContentSystem/10-Current-System/README.md

Step 1: Move the file

Run:

Terminal window
git mv \
  product/YomiyaContentSystem/02-Current-Execution/yomiya-system-source-of-truth.md \
  product/YomiyaContentSystem/10-Current-System/yomiya-system-source-of-truth.md

Step 2: Update directory README

Clarify that this layer only answers current reality and gap actions.

Step 3: Commit

Terminal window
git add product/YomiyaContentSystem/10-Current-System
git commit -m "docs: move Yomiya source of truth to current system layer"

Task 5: Merge the active execution docs into a single spec

Section titled “Task 5: Merge the active execution docs into a single spec”

Files:

  • Create: product/YomiyaContentSystem/20-Execution-Spec/yomiya-spec.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-execution-spec.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-canonical-naming.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-scope-boundary.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-implementation-spec-core.md
  • Source: product/YomiyaContentSystem/02-Current-Execution/yomiya-frontend-page-architecture.md

Step 1: Draft the merged section structure

Use this order:

  1. role of the document
  2. current phase objective
  3. naming and object definitions
  4. scope boundary
  5. page architecture
  6. key frozen page specs
  7. content intake rules
  8. tag and container rules
  9. title / cover / distribution rules
  10. current minimal engineering direction

Step 2: Copy only active conclusions, not duplicate prose

When the same rule appears more than once, keep the clearest version and add a short pointer to the evidence layer if needed.

Step 3: Verify no critical active rule was lost

Run:

Terminal window
rg -n "Collection|Series|Topic|scene|level|Visibility|Distribution Eligibility|首页|合集详情" \
  product/YomiyaContentSystem/20-Execution-Spec/yomiya-spec.md

Expected: all major active concepts still appear.

Step 4: Commit

Terminal window
git add product/YomiyaContentSystem/20-Execution-Spec/yomiya-spec.md
git commit -m "docs: merge Yomiya active execution spec"

Task 6: Relocate the original execution docs into history

Section titled “Task 6: Relocate the original execution docs into history”

Files:

  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-execution-spec.md
  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-canonical-naming.md
  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-scope-boundary.md
  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-implementation-spec-core.md
  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-frontend-page-architecture.md
  • Move: product/YomiyaContentSystem/02-Current-Execution/yomiya-phase1-delivery-plan.md

Step 1: Move the legacy files to history with stable names

Suggested destination:

  • 40-History-and-Decisions/legacy-specs/

Step 2: Add a short header note to each moved file

The note should say the file is retained as historical source material and no longer serves as the default execution entrypoint.

Step 3: Commit

Terminal window
git add product/YomiyaContentSystem/40-History-and-Decisions/legacy-specs
git commit -m "docs: archive legacy Yomiya execution docs"

Task 7: Relocate foundations and research docs into the evidence layer

Section titled “Task 7: Relocate foundations and research docs into the evidence layer”

Files:

  • Move: product/YomiyaContentSystem/01-Foundations/*
  • Move: product/YomiyaContentSystem/05-Content-Ops-and-Competitive-Research/*

Step 1: Move foundations docs

Suggested mapping:

  • 01-Foundations/yomiya-research.md -> 30-Research-and-Evidence/foundations/
  • 01-Foundations/yomiya-content-strategy.md -> 30-Research-and-Evidence/foundations/
  • 01-Foundations/yomiya-engineering-gap-analysis.md -> 30-Research-and-Evidence/foundations/

Step 2: Move research docs

Suggested mapping:

  • 播客与视频内容统一分析标准.md -> 30-Research-and-Evidence/mapping-notes/
  • 播客与视频竞品统一样本清单.md -> 30-Research-and-Evidence/samples/
  • Mirra播客排查与运用.md -> 30-Research-and-Evidence/competitive-analysis/

Step 3: Add short role notes where useful

Make clear that these are evidence-layer materials and do not override execution-layer docs.

Step 4: Commit

Terminal window
git add product/YomiyaContentSystem/30-Research-and-Evidence
git commit -m "docs: move Yomiya research into evidence layer"

Task 8: Relocate history and future docs to their new homes

Section titled “Task 8: Relocate history and future docs to their new homes”

Files:

  • Move: product/YomiyaContentSystem/03-History-and-Governance/*
  • Move: product/YomiyaContentSystem/04-Open-Questions-and-Future/*

Step 1: Move review logs and split history

Suggested mapping:

  • review logs -> 40-History-and-Decisions/review-logs/
  • split plan -> 40-History-and-Decisions/split-history/
  • old implementation spec -> 40-History-and-Decisions/legacy-specs/

Step 2: Move future docs

Suggested mapping:

  • open questions -> 50-Future-Questions/open-questions.md
  • future phases -> 50-Future-Questions/future-phases.md

Step 3: Commit

Terminal window
git add product/YomiyaContentSystem/40-History-and-Decisions product/YomiyaContentSystem/50-Future-Questions
git commit -m "docs: relocate Yomiya history and future docs"
Section titled “Task 9: Remove the obsolete layer directories and repair links”

Files:

  • Modify: all moved markdown files with cross-links
  • Delete directories after emptying: 01-Foundations, 02-Current-Execution, 03-History-and-Governance, 04-Open-Questions-and-Future, 05-Content-Ops-and-Competitive-Research

Step 1: Update all internal references

Run:

Terminal window
rg -n "01-Foundations|02-Current-Execution|03-History-and-Governance|04-Open-Questions-and-Future|05-Content-Ops-and-Competitive-Research" product/YomiyaContentSystem

Expected: every old path is intentionally updated or removed.

Step 2: Delete empty legacy directories

Run:

Terminal window
find product/YomiyaContentSystem -maxdepth 1 -type d | sort

Expected: only the new 00/10/20/30/40/50 layout remains.

Step 3: Commit

Terminal window
git add product/YomiyaContentSystem
git commit -m "docs: finalize Yomiya doc structure rewrite"

Task 10: Final verification pass

Section titled “Task 10: Final verification pass”

Files:

  • Verify: product/YomiyaContentSystem/**/*

Step 1: Verify default reading flow

Run:

Terminal window
sed -n '1,220p' product/YomiyaContentSystem/README.md
sed -n '1,260p' product/YomiyaContentSystem/00-Start-Here/yomiya-action-plan.md
sed -n '1,260p' product/YomiyaContentSystem/10-Current-System/yomiya-system-source-of-truth.md
sed -n '1,260p' product/YomiyaContentSystem/20-Execution-Spec/yomiya-spec.md

Expected: the four core docs together give a complete execution path.

Step 2: Verify the evidence layer still preserves detail

Run:

Terminal window
find product/YomiyaContentSystem/30-Research-and-Evidence \
  product/YomiyaContentSystem/40-History-and-Decisions \
  product/YomiyaContentSystem/50-Future-Questions -type f | sort

Expected: all key source material still exists.

Step 3: Verify git status

Run:

Terminal window
git status --short

Expected: only intended documentation changes remain.

Step 4: Commit

Terminal window
git add product/YomiyaContentSystem
git commit -m "docs: verify Yomiya restructure"