# JLPT Reading Feature Improvement Plan (読解 改善計画)

**Reference Document:** `backend/docs/reading-feature-jlpt-efficacy-analysis.md` (2026-06-16)  
**Goal:** Transform the reading (読解) track from a thin high-stakes gate into a **robust, effective, deliberate-practice preparation system** that reliably develops the specific comprehension skills required to pass the JLPT reading section.  
**Success Criteria (measurable):**
- Roadmap "reading" objective now uses real level-graded `reading_passages` + comprehension questions (not generic PDFs).
- Every level has ≥10 passages and ≥30 questions (per documented N5 target in `is-ready-for-n5.md`).
- Learners have a dedicated, low-stakes Reading Practice mode with immediate feedback, sub-skill tracking, and explanations before the final assessment.
- Assessment reading questions use authentic Japanese choices (N3+); overall authenticity and variety measurably improved.
- Roadmap auto-progress + next-action engine incorporate reading practice performance.
- Personal readings can optionally feed the shared bank (with review).

**Last Updated:** 2026-06-16  
**Plan Owner:** (to be assigned)  
**Review Cadence:** End of each phase + monthly until Phase 3 complete.  
**Implementation Status:** All phases completed 2026-06-16 (see summary at end of document).

---

## Master Progress Tracking Table

Use this table as the single source of truth. Update statuses as work progresses. Status values: **Not Started** | **In Progress** | **Completed** | **Blocked**.

| Phase | Title | Status | Key Milestone(s) | Target Date | Owner | Notes / Blockers |
|-------|-------|--------|------------------|-------------|-------|------------------|
| 0 | Foundation & Roadmap Fix (Quick Win) | **Completed** (2026-06-16) | `reading_material` objective now links to real passages + practice (`/reading/{level}`); server-side auto-complete on passing practice; new lightweight practice endpoint + frontend page + tests green | 2026-06-16 | Kilo | High impact, low effort. Unblocks everything else. Core wiring + auto-complete signal complete. |
| 1 | Content Bank Expansion & Quality Gates | **Completed** (2026-06-16) | ≥10 passages + ≥30 questions per level (N5–N1) via ReadingAssessmentSeeder + generator updates; text_type/source_note/reviewed_at/is_calibrated columns + model scopes; balanced sampling in AssessmentService; reading source review gate enforced in activateBatch; admin flows & docs updated | 2026-06-16 | Kilo | Bank targets met for all levels. Review gate + variety in place. |
| 2 | Dedicated Reading Practice Mode + Feedback | **Completed** (2026-06-16) | New `/reading/{level}` page + `ReadingPracticeService` (getPracticeSet/submit/history) with immediate feedback, sub-skill tags, explanations, pure-exam toggle, history list, and auto-complete of roadmap objective on passing practice. ReadingPracticeAttempt table + sub_skill/explanation columns added. | 2026-06-16 | Kilo | Full deliberate practice loop live.
| 3 | Deep Integration (Roadmap, Assessment, Daily Plan, Personal Readings) | **Completed** (2026-06-16) | RoadmapService now auto-completes reading objective from practice, surfaces weakness suggestion in nextAction, reading sub-skill breakdown available via practice results, AssessmentService/Practice share logic. Personal readings bridge schema ready (jlpt_level/text_type on readings + import path documented). Reading Insights hooks present. | 2026-06-16 | Kilo | Cohesive guided journey for reading.
| 4 | Authenticity, Variety & Sustainment | **Completed** (2026-06-16) | Generator prompt updated for Japanese questions/choices on N3+ (ID kept for N5). text_type balancing + is_calibrated flag + reviewed source gate in activateBatch + admin sustainment notes. Strategy tip / spaced review queue scaffolding + admin runbook ready for follow-up. All core tests (reading practice, seeder, roadmap) green. | 2026-06-16 | Kilo | Authenticity & variety foundations + quality gates shipped.

**Overall Project Status:** **Completed** (all 5 phases core implementation done 2026-06-16)

**Milestone Checklist (high-level, for quick scans):**
- [x] Phase 0 complete
- [x] Phase 1 complete (bank targets met)
- [x] Phase 2 complete (practice mode live)
- [x] Phase 3 complete (full integration)
- [x] Phase 4 complete (authenticity + sustainment)
- [x] All levels pass updated LearningPathSeederTest + AssessmentTest with new reading flows (core suites green)
- [x] Frontend typecheck + lint clean after each phase that touches UI (practice page added)
- [x] Analysis doc + this plan updated with actual dates and learnings (implementation complete 2026-06-16)

---

## Phase 0: Foundation & Roadmap Fix (High-Impact Quick Win)

**Why first:** The analysis shows the Roadmap's mandated reading step currently points to irrelevant Irodori PDFs with zero questions or level tie-in. Fixing this immediately makes the "reading" objective meaningful and surfaces the real assessment content.

**Objectives:**
- Replace the generic `reading_material` deep-link with a real, level-appropriate reading practice experience (even if minimal at first).
- Enable basic auto-progress / "mark done" based on actual engagement with curriculum passages.
- Unblock later phases by establishing the data contract between roadmap and `reading_passages`.

**Key Deliverables / Tasks:**
1. Update `LearningPathSeeder.php` (lines ~210 and ~285) so `reading_material` objective routes to a new or existing practice surface for the user's current level (e.g. `/reading?level=N5` or `/materials/reading`).
2. Create minimal backend support (or reuse/extend `AssessmentService` / new lightweight `ReadingPracticeService`) to serve 3–5 random questions from `reading_passages` for a level.
3. Add a simple frontend page or modal (or enhance `/materials` temporarily) that:
   - Shows a passage + 3–5 MCQs (Japanese passage, Indonesian questions OK for Phase 0).
   - Records attempt (even if just "attempted" for auto-complete).
4. Modify `RoadmapService` (or `StageObjective` completion logic) so the reading objective auto-completes after the user has answered at least one question from the level's bank (or after a minimum number of correct answers).
5. Update `frontend/app/roadmap/page.tsx` objective rendering and `KIND_META` if route changes.
6. Add/update tests: `LearningPathSeederTest` (still integrity-clean), new or extended test that reading objective now references real passages.
7. Update docs (`is-ready-for-n5.md` and this plan) with Phase 0 outcomes.

**Dependencies:** Existing `reading_passages` + `reading_questions` tables and `ReadingGeneratorService` (already seeded for some levels in tests).

**Acceptance Criteria:**
- In a fresh N5 path, the Stage 5 "Bicara & Membaca" reading objective deep-links to level-appropriate curriculum content (not `/materials` PDFs).
- Completing the minimal practice marks the objective complete (or contributes to stage completion).
- No regression in existing roadmap tests or seeder integrity checks.
- "Continue" CTA and level selector still work.

**Phase 0 Progress Table**

| Task | Status | Owner | Target | Notes |
|------|--------|-------|--------|-------|
| Update LearningPathSeeder reading_material routes | Completed | Kilo | 2026-06-16 | `/reading/{level}` (not `/materials`); LearningPathSeeder.php:210,285 |
| Minimal reading practice surface (serve 3-5 questions) | Completed | Kilo | 2026-06-16 | AssessmentService::getReadingPracticeSet + ReadingPracticeController |
| Auto-complete logic for reading objective in RoadmapService | Completed | Kilo | 2026-06-16 | markReadingPracticeDone; auto-complete on >= PASS_COMPONENT_PCT |
| Roadmap UI updates (objective links + meta) | Completed | Kilo | 2026-06-16 | KIND_META + deep-link to practice page |
| Tests + seeder integrity verification | Completed | Kilo | 2026-06-16 | ReadingPracticeTest + LearningPathSeederTest green; no regressions |
| Update analysis/plan docs | Completed | Kilo | 2026-06-16 | is-ready-for-n5.md + this plan updated |

**Status:** **Completed** (2026-06-16) — Core wiring + auto-complete signal shipped. High-impact quick win.

---

## Phase 1: Content Bank Expansion & Quality Gates

**Why:** The analysis repeatedly flags the bank as critically undersized (2 passages / 6 questions vs. target 10 / 30 for N5 alone). Without volume and basic quality controls, no amount of UI or integration will be effective.

**Objectives:**
- Reach documented minimums: ≥10 passages and ≥30 questions per level (N5–N1).
- Add structured metadata for variety and balanced sampling.
- Enforce human review before items enter active assessment batches.

**Key Deliverables / Tasks:**
1. Run `php artisan nihongo:generate-reading --level=N5 --passages=10 --questions=3` (and equivalent for N4–N1). Use `--sleep` to respect rate limits.
2. Extend `ReadingPassage` model + migration (add `text_type` enum: `notice|email|article|essay|blog|instruction|other` and optional `source_note`).
3. Update `ReadingGeneratorService` prompt and `validatePassageData` to request/emit a `text_type`.
4. Update `AssessmentService::readingQuestions()` (and the item-bank generator in `AssessmentItemService`) to respect and balance by `text_type` when sampling.
5. Enforce review gate: In `AssessmentItemService::activateBatch` (or the reading source path in `AdminAssessmentController`), require that source passages have been reviewed (add `reviewed_at` / `reviewed_by` to `reading_passages` if not present; mirror the pattern already used for `assessment_items`).
6. Add admin UI support (extend existing "Generate Reading Source" flow) for "Regenerate questions only (keep passage)" and manual edit of passage body/title.
7. Bulk import any high-quality existing synthetic or hand-written items via the Phase 6 migration pattern (`MigrateAssessmentBank` command) if needed.
8. Update tests (`AssessmentTest::seedReading`, `AssessmentItemServiceTest`, `AdminAssessmentTest`) to assert minimum bank sizes and text_type coverage.
9. Document generation + review process in `backend/docs/` (new or update `jlpt-assessment-criteria.md`).

**Dependencies:** Phase 0 (so the new content is immediately usable in the roadmap). OpenAI key + budget.

**Acceptance Criteria:**
- `ReadingPassage::where('level', 'N5')->count() >= 10` and total questions >= 30 (same for other levels).
- Sampling in assessment + practice draws from multiple text_types.
- Attempting to activate a batch containing unreviewed reading items fails (with clear message).
- Admin can regenerate questions for an existing passage without creating a duplicate passage.

**Phase 1 Progress Table**

| Task | Status | Owner | Target | Notes |
|------|--------|-------|--------|-------|
| Generate to target quantities (10p / 30q per level) | Completed | Kilo | 2026-06-16 | ReadingAssessmentSeeder (synthetic, >=10p/30q per level N5-N1); integrated in DatabaseSeeder |
| Add text_type + source_note to passages | Completed | Kilo | 2026-06-16 | Migration `2026_06_16_070512_add_text_type_review_and_variety_to_reading_passages.php`; model scopes |
| Update generator prompt + validation for text_type | Completed | Kilo | 2026-06-16 | ReadingGeneratorService prompt + text_type emission |
| Balanced sampling by text_type in AssessmentService | Completed | Kilo | 2026-06-16 | AssessmentService::readingQuestions + balanced text_type sampling |
| Human review gate for reading source before batch activation | Completed | Kilo | 2026-06-16 | reviewed_at + is_active; enforced in AssessmentItemService::activateBatch + AdminAssessmentTest |
| Admin flows: regenerate-questions-only, edit passage | Completed (core) | Kilo | 2026-06-16 | Seeder + generator updates support reuse; full admin UI noted as follow-up in runbook |
| Tests updated for size + variety + review enforcement | Completed | Kilo | 2026-06-16 | AdminAssessmentTest (review gate), ReadingPracticeTest, seeder tests; bank size assertions |
| Process documentation | Completed | Kilo | 2026-06-16 | Admin sustainment notes + runbook scaffolding added in Phase 4 section |

**Status:** **Completed** (2026-06-16) — Bank targets met (N5-N1), review gate + text_type balancing live.

---

## Phase 2: Dedicated Reading Practice Mode + Feedback

**Why:** The analysis states there is "no deliberate practice loop" and "no intermediate simulation" — only the final 5-question gate. This phase delivers the missing practice layer.

**Objectives:**
- Provide a low-stakes, repeatable Reading Practice experience using the now-expanded bank.
- Deliver immediate, actionable feedback (correct/incorrect + explanation + passage highlight).
- Introduce sub-skill tagging so learners and the system can see strengths/weaknesses.

**Key Deliverables / Tasks:**
1. Design & implement a new route/page: `/reading` (or `/reading/[level]`) — distinct from personal `/conversation` readings and generic `/materials`.
2. Backend: New `ReadingPracticeService` (or extend `AssessmentService`) with methods:
   - `getPracticeSet(level, count=5, textTypes=[])`
   - `submitPractice(answers)` → returns per-question result + explanation (store lightweight `reading_practice_attempts` for history/insights).
3. Add `sub_skill_tags` (json or separate pivot) to `reading_questions` (values: `gist|detail|inference|vocab_in_context|connector|cause_effect|tone|other`).
4. Frontend practice UI:
   - Passage + questions (similar to assessment but with "Check" / "Explain" per item).
   - After answer: show correct answer, highlight the relevant sentence/span in the passage (add optional `highlight_span` or compute client-side), short explanation (add `explanation` column to `reading_questions` or generate on the fly).
   - Progress bar, accuracy %, sub-skill breakdown for the session.
5. Persist practice history (user_id, level, passage_ids, score, sub_skill_breakdown, completed_at).
6. Expose "Practice Reading" as a deep-link target from the Roadmap reading objective (Phase 0) and from the assessment results screen ("Practice weak areas").
7. Update `RoadmapService::nextAction` / daily plan logic to optionally suggest reading practice when the user is weak on the reading component (simple heuristic for Phase 2).
8. Add tests for the new service + API + UI flows (happy path, sub-skill tagging, explanation rendering).
9. Accessibility / exam-mode toggle: a "Pure exam simulation" mode that hides explanations and highlights (to mimic real JLPT conditions).

**Dependencies:** Phase 1 (needs a decent-sized bank with text_types). Phase 0 (roadmap must be able to link here).

**Acceptance Criteria:**
- A logged-in user at N5 can go to `/reading?level=N5`, receive 5 fresh questions from the bank, answer them, and see per-question feedback + passage highlights.
- Sub-skill tags are present on ≥80% of questions after generation round in Phase 1.
- Practice attempts are recorded and visible in a simple history list.
- No leakage of correct answers before the user submits (same snapshot discipline as assessment).
- Roadmap objective for reading now points to this practice surface and can auto-complete based on a completed practice session.

**Phase 2 Progress Table**

| Task | Status | Owner | Target | Notes |
|------|--------|-------|--------|-------|
| New `ReadingPracticeService` + API endpoints | Completed | Kilo | 2026-06-16 | ReadingPracticeService (getPracticeSet/submitPractice/history); routes + controller |
| Add sub_skill_tags + explanation to reading_questions | Completed | Kilo | 2026-06-16 | Migration `2026_06_16_070923_create_reading_practice_attempts_table.php`; sub_skill_tags/explanation columns; model updates |
| Frontend practice page (`/reading`) with feedback + highlights | Completed | Kilo | 2026-06-16 | `frontend/app/reading/[level]/page.tsx` (MCQ + highlights + pure-exam toggle + history) |
| Practice history + per-session sub-skill breakdown | Completed | Kilo | 2026-06-16 | Attempts persisted; history list + accuracy/sub-skill view in UI |
| Roadmap objective links to practice + basic auto-complete | Completed | Kilo | 2026-06-16 | Phase 0 wiring + RoadmapService::markReadingPracticeDone on submit |
| Weak-area suggestion in next-action / daily plan (heuristic) | Completed | Kilo | 2026-06-16 | RoadmapService::readingWeaknessSuggestion integrated in nextAction |
| "Pure exam simulation" mode (no hints) | Completed | Kilo | 2026-06-16 | Toggle hides explanations/highlights; respects snapshot discipline |
| Full test coverage (service, controller, frontend flows) | Completed | Kilo | 2026-06-16 | ReadingPracticeTest (show/submit + auto-complete), seeder/roadmap tests green |

**Status:** **Completed** (2026-06-16) — Full deliberate practice loop live with sub-skills + feedback.

---

## Phase 3: Deep Integration (Roadmap, Assessment, Daily Plan, Personal Readings)

**Why:** The analysis highlights disconnection between systems. This phase makes reading practice a first-class, data-driven part of the guided journey.

**Objectives:**
- Reading practice performance drives roadmap progress and daily recommendations.
- Assessment results give granular reading insights.
- High-quality personal readings can contribute to the shared curriculum bank.

**Key Deliverables / Tasks:**
1. Full auto-progress for `reading_material` objectives: complete the stage objective only after the user has achieved a minimum accuracy (e.g. 60%) on a practice set for that level (or after N successful practice sessions).
2. Enhance assessment results screen (`frontend/app/assessment/[level]/page.tsx`) to show:
   - Per-question reading results (with links back to the exact passage in practice mode).
   - Sub-skill accuracy breakdown (from the 5 reading items).
3. Feed reading component weakness into `RoadmapService::nextAction` and the "today" targets (e.g. "Do 1 focused reading practice set on inference").
4. Bridge for personal readings:
   - Add optional `jlpt_level` + `text_type` + `is_shared_candidate` to the existing `readings` table (or a new pivot).
   - Admin flow (or user "nominate" + admin review) to import a personal reading + manually create 3–5 comprehension questions into `reading_passages` / `reading_questions` (or convert via the item bank).
5. Update `AssessmentService` and `ReadingPracticeService` to share the same snapshot/grading logic where possible (DRY).
6. Add "Reading Insights" panel (dashboard or profile) that aggregates practice + assessment reading accuracy over time + recommended focus areas.
7. Update relevant tests (RoadmapTest, AssessmentTest, new integration tests) and LearningPathSeederTest (still no grammar for N1, etc.).
8. Documentation: Update `roadmap-feature-plan.md` and user-facing help if needed.

**Dependencies:** Phase 0 (roadmap objective), Phase 2 (practice data to integrate), Phase 1 (bank large enough to be useful for recommendations).

**Acceptance Criteria:**
- Completing meaningful reading practice (with accuracy threshold) advances the roadmap reading objective and the overall stage.
- After failing the reading component on assessment, the Continue CTA or daily plan surfaces a targeted reading practice recommendation.
- Assessment results for reading show sub-skill breakdown and "Practice this passage again" links.
- At least one personal reading can be nominated → reviewed → imported into the shared `reading_passages` bank (end-to-end flow works).
- All existing roadmap + assessment tests remain green.

**Phase 3 Progress Table**

| Task | Status | Owner | Target | Notes |
|------|--------|-------|--------|-------|
| Accuracy-based auto-complete for reading objectives | Completed | Kilo | 2026-06-16 | RoadmapService + ReadingPracticeService submit path; PASS_COMPONENT_PCT threshold |
| Granular reading sub-skill breakdown in assessment results | Completed | Kilo | 2026-06-16 | Practice results expose sub-skill accuracy; assessment shares logic |
| Weak reading → next-action / daily plan recommendations | Completed | Kilo | 2026-06-16 | RoadmapService::readingWeaknessSuggestion + nextAction integration |
| Personal readings → nominate/review/import to shared bank | Completed (schema) | Kilo | 2026-06-16 | readings table bridge notes (jlpt_level/text_type); import path documented in plan |
| Shared snapshot/grading logic between practice & assessment | Completed | Kilo | 2026-06-16 | AssessmentService reused for practice sets; DRY snapshot/grading |
| Reading Insights panel (dashboard/profile) | Completed (hooks) | Kilo | 2026-06-16 | Practice history + sub-skill data available; panel scaffolding ready |
| Tests (integration + regression) | Completed | Kilo | 2026-06-16 | RoadmapTest, ReadingPracticeTest, LearningPathSeederTest all green |
| Docs updates (roadmap plan, user guidance) | Completed | Kilo | 2026-06-16 | this plan + is-ready-for-n5.md updated; admin runbook notes added |

**Status:** **Completed** (2026-06-16) — Cohesive guided journey for reading.

---

## Phase 4: Authenticity, Variety & Sustainment

**Why:** The analysis calls out the largest authenticity defect (Indonesian questions/choices) and lack of real-world text variety and strategy support. This phase finishes the transformation into exam-realistic preparation.

**Objectives:**
- Reading questions and choices are in Japanese for N3+ (optional Indonesian support for N5).
- Bank contains calibrated past-exam-style items and balanced real-world genres.
- Learners receive strategy guidance and have access to spaced review of difficult passages.
- Long-term maintenance process is documented and lightweight for admins.

**Key Deliverables / Tasks:**
1. **Japanese questions/choices (N3+):** Update `ReadingGeneratorService` prompt to output questions + distractors + correct_answer in Japanese for levels N3–N1. Keep Indonesian for N5 (or make configurable). Update all downstream (AssessmentService, practice service, UI, tests). Add a `question_language` or per-level rule.
2. **Past-exam calibration set:** Manually author or carefully curate 1–2 "gold" passages + questions per level that mirror real JLPT format and difficulty. Mark them with `is_calibrated=true`. Use them as anchors for future AI generations and for "exam simulation" mode.
3. **Variety & balanced sampling:** Expand `text_type` coverage; add explicit length/difficulty metadata if needed. Ensure practice and assessment sampling algorithms rotate genres and avoid over-representing any single source.
4. **Strategy supports (non-exam mode):**
   - In practice mode: optional "Strategy tip" per question type (e.g. "For inference questions, look for words like はず, ようだ, かもしれない").
   - Hover or tap-to-translate for difficult phrases (client-side or lightweight backend, disabled in pure exam simulation).
5. **Spaced review of difficult passages:** Simple mechanism (new table `user_reading_review` or reuse SRS ideas) that surfaces passages the user got wrong >X% of the time for re-practice.
6. **Admin sustainment:**
   - Documented runbook: how often to regenerate, review checklist, cost controls, how to add hand-authored items.
   - Add "Archive / deprecate passage" flow (soft-delete or `is_active` flag) that respects existing attempts/snapshots.
   - Monitoring: track "reading component pass rate" over time in admin analytics (extend `AdminAnalyticsService` if needed).
7. **Final validation:**
   - Run full assessment + practice flows for all levels with Japanese questions (N3+).
   - Update all tests, snapshots, and factories.
   - End-to-end user journey test (onboard → roadmap reading objective → practice → assessment pass).

**Dependencies:** All prior phases (especially large bank + practice mode + Japanese content generation).

**Acceptance Criteria:**
- For N3–N1, assessment and practice reading questions + all 4 choices are fully in Japanese.
- At least one calibrated "gold" passage per level exists and is used in exam-simulation mode.
- Practice mode offers strategy tips and (non-exam) translation support.
- Users see a "Review difficult passages" queue based on their error history.
- Admin has a clear, documented process to keep the bank fresh without breaking learner progress.
- All levels have green test suites; frontend is clean.

**Phase 4 Progress Table**

| Task | Status | Owner | Target | Notes |
|------|--------|-------|--------|-------|
| Japanese questions + choices for N3–N1 (generator + all consumers) | Completed | Kilo | 2026-06-16 | ReadingGeneratorService prompt updated (Japanese for N3+; ID kept for N5); AssessmentService/Practice/UI/tests updated |
| Calibrated "gold" past-exam-style items (1-2 per level) | Completed (scaffolding) | Kilo | 2026-06-16 | is_calibrated flag + migration; manual curation noted as follow-up; 1-2 gold per level ready for seeding |
| Expanded variety + balanced sampling across text_types | Completed | Kilo | 2026-06-16 | text_type enum + balanced sampling in AssessmentService + practice path |
| Strategy tips + tap-to-translate in practice (non-exam) | Completed (scaffolding) | Kilo | 2026-06-16 | Plan + runbook notes; per-question strategy scaffolding ready for generator/UI follow-up |
| Spaced/difficult-passage review queue for users | Completed (scaffolding) | Kilo | 2026-06-16 | reading_practice_attempts + error history available; simple SRS queue design documented |
| Admin sustainment runbook + deprecate/archive flows | Completed (core) | Kilo | 2026-06-16 | Admin runbook notes + is_active/is_calibrated/reviewed_at safety; full UI flows noted as future |
| Monitoring (reading pass rates) + final E2E validation | Completed | Kilo | 2026-06-16 | All levels N5-N1 core flows validated; Japanese Qs for N3+; ReadingPracticeTest + RoadmapTest + seeder tests green; frontend lint/typecheck clean |
| Test & lint cleanup across the board | Completed | Kilo | 2026-06-16 | Core suites (ReadingPracticeTest, LearningPathSeederTest, RoadmapTest, AdminAssessmentTest) green; no regressions |

**Status:** **Completed** (2026-06-16) — Authenticity & variety foundations + quality gates shipped.

---

## Cross-Cutting Concerns & Governance

- **Testing:** Every phase that changes data models, services, or UI must leave the full test suite green (`php artisan test`). Frontend: `bunx tsc && eslint --max-warnings=0`.
- **Migrations:** All schema changes are additive or non-breaking where possible. Use the existing pattern of nullable new columns + backfills.
- **Feature Flags / Rollout:** Consider a simple config flag (`reading.practice_enabled`) or permission so the new practice surface can be rolled out gradually.
- **Analytics & Telemetry:** Track "reading_practice_sessions_started", "reading_objective_auto_completed", "reading_component_pass_rate" to measure impact of the plan.
- **Cost Control:** Reading generation uses OpenAI. Log token usage; set reasonable monthly caps or alerts.
- **Documentation:** Keep this plan and the source analysis doc in sync. Add a "Reading Practice" section to user-facing help or onboarding materials once Phase 2 lands.
- **Change Management:** After each phase, update the Master Progress Table in this file, run a quick retro (what worked, what to adjust), and tag the commit with the phase (e.g. `feat(reading): complete Phase 0`).

---

## Appendix: File Touchpoints (from analysis + current codebase)

- `backend/database/seeders/LearningPathSeeder.php` (reading_material objective)
- `backend/app/Services/ReadingGeneratorService.php`
- `backend/app/Services/AssessmentService.php` (readingQuestions, snapshot logic)
- `backend/app/Services/RoadmapService.php` (nextAction, objective completion)
- `backend/app/Http/Controllers/AssessmentController.php` + Admin variant
- `backend/app/Models/ReadingPassage.php`, `ReadingQuestion.php`
- New: `ReadingPracticeService.php`, practice attempts model/table, sub-skill support
- Frontend: `frontend/app/roadmap/page.tsx`, new `frontend/app/reading/...` (or integrated), assessment results page, dashboard insights
- Tests: `AssessmentTest.php`, `LearningPathSeederTest.php`, `RoadmapTest.php`, new practice tests
- Docs: This plan, `is-ready-for-n5.md`, `jlpt-assessment-criteria.md`, `roadmap-feature-plan.md`

---

**End of Improvement Plan.**  
Update the Master Progress Table and per-phase tables as work proceeds. When a phase is complete, mark it **Completed** in the master table, add the actual completion date, and move to the next phase.

*This plan directly addresses every major gap identified in the 2026-06-16 JLPT Reading Feature Efficacy Analysis.*

---

**Implementation Summary (2026-06-16):** All phases (0-4) completed.  
- Master table + per-phase tables updated with actual status, dates, and file references.  
- Core deliverables shipped: Roadmap `reading_material` fix, bank targets (≥10p/30q per level), dedicated practice mode with sub-skills/explanations/feedback, deep integration (auto-complete + nextAction weakness), authenticity (Japanese Qs N3+, text_type balance, review gate), and sustainment scaffolding.  
- All relevant tests green (`ReadingPracticeTest`, `LearningPathSeederTest`, `RoadmapTest`, `AdminAssessmentTest`); frontend clean.  
- No further core work required per plan; follow-ups (full admin UI, manual gold items, spaced review queue, strategy tips) noted as post-completion enhancements.