docs: add Mermaid roadmap and update Research Roadmap content

[singyichen]

Summary

• Add color-coded Mermaid gantt chart to both README.md and README.zh-TW.md
• Restructure Research Roadmap content based on senior-technical-writer review
• Update Tech Stack table to include all infrastructure components

Changes

Gantt chart (new)

• 4-phase color-coded timeline (2026-04 ~ 2028-04)
• Phase 1 🔵 · Phase 2 🟣 · Phase 3 🟢 · Phase 4 🟡

Roadmap restructure

• Phase 3 infrastructure shortened to 2 months; backend/frontend parallelized
• Add: academic paper survey, Related Work draft, evaluation criteria, mini user study, demonstration scenarios, demo video, paper outline, advisor review cycle
• Remove: submission/camera-ready milestones (part-time student, no fixed venue)
• Rename Phase 3 → "Development & Validation"; fix month ranges (Phase 3: Month 9–22, Phase 4: Month 22–24)

Tech Stack table

• Add PostgreSQL, Redis, Celery, pytest to both README files

Test plan

• Verify Mermaid gantt renders correctly on GitHub (both README.md and README.zh-TW.md)
• Verify all 4 phases display with correct colors
• Verify checklist month ranges match gantt calendar dates
• Verify Tech Stack table includes all components

🤖 Generated with Claude Code

[qodo-code-review]

Review Summary by Qodo

Add Mermaid roadmap visualization and enhance research roadmap documentation

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Add color-coded Mermaid gantt chart visualizing 24-month research roadmap
• Expand Tech Stack table with PostgreSQL, Redis, Celery, pytest components
• Restructure roadmap phases with detailed milestones and evaluation criteria
• Update phase durations and rename Phase 3 to "Development & Validation"

Diagram

flowchart LR
  A["README Files<br/>English & Traditional Chinese"] -->|"Add Mermaid<br/>Gantt Chart"| B["24-Month<br/>Research Timeline"]
  A -->|"Expand Tech Stack"| C["PostgreSQL, Redis,<br/>Celery, pytest"]
  A -->|"Restructure Phases"| D["4 Phases with<br/>Detailed Milestones"]
  B --> E["Phase 1-4<br/>Color-Coded"]
  D --> F["Updated Month Ranges<br/>& Deliverables"]

Loading

File Changes

1. README.md 📝 Documentation +67/-9

Add Mermaid roadmap and enhance research phases

• Add Mermaid gantt chart with 4 color-coded phases spanning 2026-04 to 2028-04
• Expand Tech Stack table to include PostgreSQL, Redis, Celery, and pytest
• Restructure research roadmap with detailed milestones for all 4 phases
• Update phase durations: Phase 3 now Month 9–22, Phase 4 now Month 22–24
• Add new deliverables: academic paper survey, user study, demo scenarios, advisor review cycle

README.md

---

2. README.zh-TW.md 📝 Documentation +67/-9

Add Mermaid roadmap and enhance research phases (Chinese)

• Add Mermaid gantt chart with 4 color-coded phases in Traditional Chinese labels
• Expand Tech Stack table with PostgreSQL, Redis, Celery, pytest in Chinese terminology
• Restructure research roadmap with detailed milestones translated to Traditional Chinese
• Update phase durations and month ranges matching English version
• Add new deliverables with Chinese translations for academic survey, user study, demo video

README.zh-TW.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. Ambiguous roadmap date ranges ☑ 🐞 Bug ✓ Correctness

Description

The Mermaid gantt uses month-only end dates (e.g., tasks ending at 2026-08) while the Phase
headings state ranges like “Month 1–4”, which can be read as internally inconsistent and misleads
readers mapping months to calendar dates. The same ambiguity appears in both English and zh-TW
READMEs.

Code

README.md[R102-135]

+    dateFormat  YYYY-MM
+    axisFormat  %b %Y
+
+    section Phase 1 · Problem Definition
+    Tool survey (Label Studio, CodaBench)         :p1a, 2026-04, 2026-06
+    UX interview & pain-point questionnaire       :p1d, 2026-05, 2026-07
+    Academic paper survey (Related Work)          :p1e, 2026-05, 2026-08
+    Define system contributions                   :p1b, 2026-06, 2026-07
+    Study Demo Paper examples from target venue   :p1c, 2026-07, 2026-08
+
+    section Phase 2 · System Design
+    Core module planning                          :p2a, 2026-08, 2026-09
+    General-purpose task template design          :p2b, 2026-09, 2026-11
+    Tech stack documentation                      :p2c, 2026-10, 2026-11
+    Data flow & leakage prevention design         :p2d, 2026-11, 2026-12
+    Preliminary Related Work draft                :p2e, 2026-10, 2026-12
+
+    section Phase 3 · Development & Validation
+    Project infrastructure & CI                   :p3a, 2026-12, 2027-02
+    Backend — FastAPI + DB + Celery               :p3b, 2027-02, 2027-07
+    Frontend — React annotation UI                :p3c, 2027-04, 2027-09
+    Automated scoring & leaderboard               :p3d, 2027-07, 2027-11
+    Domain validation & user feedback             :p3e, 2027-09, 2027-12
+    Mini user study (SUS questionnaire)           :p3g, 2027-11, 2028-01
+    Demonstration scenarios & demo video          :p3h, 2027-11, 2028-02
+
+    section Phase 4 · Paper & Demo
+    Paper outline & section drafts                :p4a, 2028-01, 2028-03
+    Advisor review & revision cycle               :p4b, 2028-03, 2028-04
+    System demonstration preparation              :p4c, 2028-03, 2028-04
+```
+
### Phase 1 — Problem Definition & Tool Survey (Month 1–4)
- [ ] Survey existing platforms (e.g., Label Studio, CodaBench) and identify pain points in setup, usability, and workflow integration

Evidence

In README.md the gantt is configured with dateFormat YYYY-MM and Phase 1 tasks extend to
2026-08, but immediately below the Phase 1 checklist heading claims “Month 1–4”; without day-level
boundaries or an explicit note that end months are exclusive, readers can reasonably interpret this
as Phase 1 extending into Month 5. README.zh-TW.md mirrors the same structure and dates.

README.md[87-110]
README.md[134-146]
README.zh-TW.md[87-110]
README.zh-TW.md[134-146]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Mermaid gantt uses `dateFormat YYYY-MM`, which makes task end dates ambiguous at month boundaries and can appear inconsistent with the textual “Month X–Y” phase ranges.
### Issue Context
Both `README.md` and `README.zh-TW.md` include the same gantt structure and month-range headings.
### Fix approach
Pick one of these and apply consistently to both files:
1) Switch to day-precision boundaries (recommended):
 - Change to `dateFormat YYYY-MM-DD`
 - Use explicit month-boundary dates (e.g., `2026-04-01` to `2026-08-01`) so it’s clear the end date is a boundary.
2) Keep `YYYY-MM` but add a short note under the chart clarifying that end months are exclusive month-boundaries.
3) Adjust the textual “Month X–Y” ranges to match how the chart is intended to be read.
### Fix Focus Areas
- README.md[87-162]
- README.zh-TW.md[87-162]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Unclear tech stack status ☑ 🐞 Bug ⚙ Maintainability

Description

The Tech Stack tables present PostgreSQL/Redis/Celery/pytest as the project stack without clarifying
whether these are planned vs. implemented, while the roadmap frames this as a Phase 2 “decision” and
CI explicitly accounts for missing backend/frontend code. This can cause contributor confusion about
what actually exists in the repo today.

Code

README.md[R65-68]

+| **Database** | PostgreSQL |
+| **Cache / Queue** | Redis |
+| **Async Tasks** | Celery |
+| **Testing** | Playwright (E2E) + pytest |

Evidence

README.md lists infrastructure components in the Tech Stack table, but the roadmap includes an
explicit Phase 2 action to document/ratify the tech stack (suggesting a decision point rather than
implemented reality). Additionally, CI comments/conditions explicitly state backend/frontend jobs
are skipped when key project files don’t exist yet, indicating the repo may be in a
pre-implementation stage.

README.md[59-68]
README.md[141-146]
.github/workflows/ci.yml[18-26]
.github/workflows/ci.yml[145-152]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The README Tech Stack table can be read as describing currently implemented components, but other repo docs/CI suggest parts of the implementation may not exist yet.
### Issue Context
The roadmap already treats the stack as something to be documented/ratified in Phase 2.
### Fix approach
In both READMEs, clarify the table’s intent, for example:
- Rename header to “Target Tech Stack” / “Planned Tech Stack”, or
- Add a one-line note below the table: “Tech stack reflects the current design decision; implementation is tracked in Phase 3.”
### Fix Focus Areas
- README.md[59-70]
- README.zh-TW.md[59-70]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more