02-mvp-implementation-plan

Yomiya Content Curator MVP Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans if this plan is implemented task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build the first read-only yomiya-content-curator operating workflow that reads real Yomiya content data and produces actionable content-operations reports.

Architecture: The MVP is a local/operations Skill plus scripts or read-only queries. It does not mutate yomiya-service, iOS, or production data. It produces Markdown and JSON reports with concrete field mappings and manual Admin actions.

Tech Stack: Codex/OpenClaw Skill, read-only MySQL or existing Admin/API reads, Markdown reports, optional JSON output.

---

1. Scope

In scope:

• Create a local Skill named yomiya-content-curator.
• Read real backend data from yomiya-service.
• Generate inventory, homepage draft, VIP suggestions, manual action list, and post-operation verification report.
• Generate homepage drafts with horizontal/vertical section alternation and configurable vertical item counts.
• Keep all data-changing actions manual.

Out of scope:

• Automatic publishing.
• Direct DB mutation.
• Direct news.visibility updates.
• New Admin pages.
• New homepage persistence tables.
• User behavior optimization.
• Claiming Admin FeaturedHomeLayout automatically affects current iOS until /v1/featured or a new App layout API proves it.

2. File Plan

Recommended files if implemented in root repo:

skills/yomiya-content-curator/SKILL.md
skills/yomiya-content-curator/references/data-sources.md
skills/yomiya-content-curator/references/report-format.md
skills/yomiya-content-curator/references/rules.md
skills/yomiya-content-curator/scripts/collect_snapshot.py
skills/yomiya-content-curator/scripts/build_reports.py
product/YomiyaContentOperator/reports/

Recommended output files per run:

product/YomiyaContentOperator/reports/YYYY-MM-DD-content-inventory.md
product/YomiyaContentOperator/reports/YYYY-MM-DD-homepage-draft.md
product/YomiyaContentOperator/reports/YYYY-MM-DD-vip-suggestions.md
product/YomiyaContentOperator/reports/YYYY-MM-DD-admin-actions.md
product/YomiyaContentOperator/reports/YYYY-MM-DD-post-check.md
product/YomiyaContentOperator/reports/YYYY-MM-DD-snapshot.json

3. MVP Data Contract

The collector should read these tables or equivalent API payloads:

• channels
• youtube_channels
• podcast_shows
• podcast_episodes
• raw_news
• news
• news_scenes
• news_sentence_translations
• transcription_tasks
• filter_words

Minimum fields per content item:

{
  "news_id": "news.id",
  "news_external_id": "news.news_id",
  "title": "news.title",
  "date": "news.date",
  "level": "news.level",
  "channel_id": "news.channel_id",
  "source": "news.source",
  "type": "news.type",
  "visibility": "news.visibility",
  "raw_unique_id": "raw_news.unique_id",
  "raw_status": "raw_news.status",
  "risk_check_status": "raw_news.risk_check_status",
  "translation_languages": ["zh-CN", "en"],
  "transcription_status": "transcription_tasks.status",
  "duration_seconds": "podcast_episodes.duration_seconds or transcription_tasks.estimated_duration_seconds",
  "scene_ids": [1, 2],
  "primary_scene_id": 1
}

Minimum fields per homepage section draft:

{
  "section_id": "stable-section-key",
  "section_title": "学唱日语歌",
  "section_order": 3,
  "display_type": "collection_rail",
  "source_type": "youtube_playlist",
  "source_target_id": 17,
  "source_limit": null,
  "visible_item_count": null,
  "target_type": "youtube_playlist",
  "target_id": 17,
  "presentation_reason": "用横向合集建立专题感",
  "current_app_effect": "SKIP",
  "blocked_by": "iOS 0.6.3 (97) only consumes /v1/featured channels[]"
}

Allowed first-version layout values should mirror the observed Admin model:

display_type:
- collection_rail
- vertical_content_list

source_type:
- channel
- youtube_playlist
- youtube_playlist_items
- podcast_show

target_type:
- channel
- youtube_playlist
- podcast_show
- podcast_list

For vertical_content_list, the report must include visible_item_count and source_limit. When the current App cannot honor these fields, the report still outputs them under the ideal layout and marks current_app_effect = SKIP.

4. Report Rules

Hard gates:

• raw_news.risk_check_status in (HIGH, MEDIUM, BLOCKED) must not be recommended for homepage or VIP.
• raw_news.status = REJECTED must not be recommended.
• news.visibility = ARCHIVED should stay out of homepage suggestions unless the report is specifically about unarchiving.
• User-imported media must be marked as “risk/difficulty skipped by current pipeline” unless a later backend change proves otherwise.

Positive signals:

• raw_news.risk_check_status = LOW
• raw_news.status = DONE
• news.visibility in (VISIBLE, MEMBERSHIP_VISIBLE, TIME_LIMIT_VISIBLE)
• news.level matches target section
• translations are complete for target languages
• transcription is completed for audio/video
• cover/image resource exists and migrated

Homepage presentation rules:

• Prefer alternating collection_rail and vertical_content_list.
• Avoid two adjacent sections with the same display_type unless inventory quality forces it.
• Avoid two adjacent sections with the same source or same user motivation.
• Every vertical_content_list must include visible_item_count.
• Default vertical counts:
  • news/latest: 3
  • story/deep reading: 2-3
  • short listening/audio: 4-5
  • podcast episodes: 2-3
  • experimental song/pop-culture sections: 2
• Current iOS 0.6.3 (97) can only be marked PASS for sections that can be represented by /v1/featured channels[].news[].
• YouTube playlist, playlist items, podcast show cards, and mixed section layouts must be marked SKIP until the App layout API and iOS renderer exist.

5. Implementation Tasks

Task 1: Create Skill Skeleton

Files:

• Create: skills/yomiya-content-curator/SKILL.md

• Create: skills/yomiya-content-curator/references/data-sources.md

• Create: skills/yomiya-content-curator/references/report-format.md

• Create: skills/yomiya-content-curator/references/rules.md

• Step 1: Create the Skill entrypoint.

SKILL.md should define:

# yomiya-content-curator

Use when generating Yomiya content-operations reports, homepage curation drafts, VIP suggestions, translation/transcription priority lists, or post-operation verification for `/Users/cc/Documents/yomiya-service` and `/Users/cc/Documents/EveryDayJapanese-iOS`.

## Default Mode

Read-only. Do not mutate database rows, Admin state, GitHub issues, or app code unless the user explicitly asks for a separate implementation task.

## Required Inputs

- yomiya-service path: `/Users/cc/Documents/yomiya-service`
- iOS path: `/Users/cc/Documents/EveryDayJapanese-iOS`
- output path: `/Users/cc/Documents/root-remote/product/YomiyaContentOperator/reports`

## Required Workflow

1. Read `references/data-sources.md`.
2. Read `references/rules.md`.
3. Collect a backend snapshot.
4. Generate reports using `references/report-format.md`.
5. If the user has performed manual Admin actions, re-read backend/API state and produce a post-check report.

## Output Requirement

Every recommendation must include real field mappings such as `news.id`, `news.news_id`, `news.visibility`, `raw_news.unique_id`, `raw_news.status`, and `raw_news.risk_check_status`.

Homepage recommendations must also include `section_order`, `display_type`, `source_type`, `source_limit`, `visible_item_count`, `presentation_reason`, `current_app_effect`, and `blocked_by` when not currently visible in iOS.

• Step 2: Create data source reference.

references/data-sources.md should list all MVP tables and fields from section 3.

• Step 3: Create rules reference.

references/rules.md should include the hard gates and positive signals from section 4.

• Step 4: Create report format reference.

references/report-format.md should define the five report types, required per-item fields, and homepage section fields.

Task 2: Build Read-Only Snapshot Collector

Files:

• Create: skills/yomiya-content-curator/scripts/collect_snapshot.py

• Step 1: Implement a collector that accepts read-only DB config from environment variables.

Expected environment variables:

YOMIYA_DB_DSN
YOMIYA_CONTENT_OPERATOR_OUTPUT_DIR

• Step 2: Query MVP tables.

The collector should fail fast if required config is missing and should not contain write SQL.

• Step 3: Save normalized JSON.

Expected output:

product/YomiyaContentOperator/reports/YYYY-MM-DD-snapshot.json

Task 3: Build Report Generator

Files:

• Create: skills/yomiya-content-curator/scripts/build_reports.py

• Step 1: Load the snapshot JSON.

• Step 2: Compute per-item status.

Required derived fields:

risk_gate
translation_completeness
transcription_completeness
homepage_candidate
layout_candidate
display_type
section_order
visible_item_count
source_limit
presentation_reason
current_app_effect
vip_candidate
archive_candidate
repair_needed
manual_action

• Step 3: Generate five reports.

Required reports:

content-inventory.md
homepage-draft.md
vip-suggestions.md
admin-actions.md
post-check.md

• Step 4: Keep recommendations concrete.

Every item must include:

news.id
news.news_id
news.visibility
news.level
news.channel_id
news.type
raw_news.unique_id
raw_news.status
raw_news.risk_check_status
section_order
display_type
visible_item_count
source.limit
current_app_effect

• Step 5: Add horizontal/vertical homepage planner.

The planner should:

• Start from eligible content and source inventory.
• Propose a section sequence that alternates collection_rail and vertical_content_list.
• Assign visible_item_count for every vertical_content_list.
• Mark whether each section can currently appear in iOS 0.6.3 (97).
• Produce PASS / SKIP reasoning before any future implementation exists.

Task 4: Add Post-Operation Verification Flow

Files:

• Modify: skills/yomiya-content-curator/SKILL.md

• Modify: skills/yomiya-content-curator/scripts/collect_snapshot.py

• Modify: skills/yomiya-content-curator/scripts/build_reports.py

• Step 1: Add mode post-check.

This mode re-reads backend state after manual Admin operation.

• Step 2: Compare expected actions with actual fields.

Input should be a small JSON list:

[
  {
    "news_id": "real-news-id",
    "expected_visibility": "MEMBERSHIP_VISIBLE",
    "expected_section": "日本民间故事"
  }
]

• Step 3: Output PASS / FAIL / SKIP.

Expected format:

PASS news.id=<id> visibility=MEMBERSHIP_VISIBLE
FAIL news.id=<id> expected visibility=MEMBERSHIP_VISIBLE actual=VISIBLE
SKIP news.id=<id> reason=not returned by /v1/featured because section config does not include channel
SKIP section.id=<id> display_type=collection_rail reason=iOS 0.6.3 (97) does not consume featured-home-layout sections

Task 5: First Real Run

Files:

• Create reports under: product/YomiyaContentOperator/reports/

• Step 1: Run snapshot collector against a read-only backend source.

• Step 2: Generate reports.

• Step 3: Manually inspect at least 10 recommendations.

Check:

• No high-risk content recommended.

• VIP suggestions map to news.visibility = MEMBERSHIP_VISIBLE.

• Homepage recommendations match real iOS section shapes.

• Homepage ideal layout alternates horizontal and vertical sections where inventory allows.

• Every vertical section has a visible item count and source limit.

• Current App effect is explicitly PASS, FAIL, or SKIP.

• Translation/transcription repair actions are not confused with visibility actions.

• Step 4: Record gaps in product/YomiyaContentOperator/reports/YYYY-MM-DD-run-notes.md.

6. Acceptance Criteria

MVP is acceptable when:

• Reports are generated from real backend data.
• Each recommendation includes concrete DB/API fields.
• No report asks AI to directly publish or mutate state.
• Risk rules are visible in the output.
• VIP suggestions use news.visibility = MEMBERSHIP_VISIBLE.
• Manual Admin action list is understandable by an operator.
• Post-check can distinguish PASS, FAIL, and SKIP.
• Homepage drafts distinguish ideal Admin layout from what current iOS can actually render.

MVP is not acceptable if:

• It only gives abstract advice.
• It recommends high-risk or rejected content for homepage.
• It hides missing translation/transcription state.
• It claims homepage versioning exists before backend model support is built.
• It mutates data without explicit operator approval.
• It claims YouTube playlist or collection_rail sections are visible in current iOS without API/App evidence.