Shubo · Roadmap

Snapshot of ROADMAP.md · 2026-06-17 · the markdown is canonical (regenerate after edits)

file-based Linear · DIRECTION / DESIGN / FEAT / ROADMAP / HELP

▶ To decide what's next, read this board — the Now cycle + the ranked backlog — and open a single FEAT- only when it's the in-flight one. Never read every FEAT to choose (that's how focus is lost). Closed FEATs archive, so the board stays a short list of in-flight work — a focused board, not a pile of stale tickets.

Now — current cycle

▶ FOUNDATION · personal-first

Light up file import → library → cited writing

The first end-to-end personal-first writing path — useful with zero AI, zero collab/billing.

Feature	☑ Foundation scope	Status
reference-manager	CSL-JSON Source truth · CRUD · dedup · enrich · Library search/listing · import target	Building · biblio spine
import door	.bib import into citeable Source truth	Next · .bib only
note-editor	production Note CRUD · structured TipTap body · save/reopen · generic slash commands	Next · needs design docs
note-citations	/cite from Library · citation nodes · live References · style switch	Next · C0 render spike ready

End-to-end acceptance: sign up → .bib import works → Library rows with CSL truth are visible/searchable → create a note → write in the production editor → /cite Library papers → generated References section updates → switch style → save/reopen. No AI call is required.

Critical-path planning bar: only the MVP slices that block this Foundation loop need to be plan-ready now. Good non-critical subfeatures stay in deferred candidates with priority, or in explicitly non-blocking parallel tracks.

‖ Parallel track (@pinglin) · Dynamic Organization M0 M0 ✓ done — pure backend substrate (the facet_tag layer + outbox/reconciler; no LLM, no UI) landed on main: the cross-service reconciler converges against a live stack and the gate passes (invariant harness: no-re-embed · never-moves · reconciler-converges · undo-exact), proven by a live e2e. M1 next (the auto-tagger); M1–M8 stay post-Foundation unless Grounded Assist needs a specific consumer contract earlier.

Not in Foundation acceptance: full onboarding route ①/③ · add your work · PDF upload/import · RIS/CSL-JSON parity beyond .bib · RM AI-index bridge · First Warm Library Ask · warm chips · Zotero/deep connectors · Grounded AI Write · Dynamic Organization M1-M8 · all Share Era features · billing. Parallel work must not block Foundation.

Backlog — ranked, foundation before leaves

FOUNDATION non-AI cited writing

Free to validate. The user can complete writing without any AI call.

1Reference Library

Building · foundation substrate

now, the root — R0/R1 landed; full-text availability + listing + OA landed; .bib Import Door alignment is next; AI-index bridge is Grounded Assist, not Foundation

Plan ready · .bib import targetLater · AI-index bridge

Pull 5Gate 5Effort 3Rev 5

2Note Editor

can build in parallel with import — production notes, CRUD, TipTap editor, generic slash commands

Needs design docs

Pull 4Gate 4Effort 4Rev 5

blocks Note Citations, Grounded AI Write, Submission Export, Manuscript Review

3Import Door

Next · one door only

narrow onboarding slice — .bib import; PDF upload/import, RIS/CSL-JSON parity, and route ①/③/add-your-work later

Plan ready · Route ②

Pull 5Gate 4Effort 4Rev 5

depends on reference-manager Source truth; does not block Note Editor

4Note Citations

after Note Editor + Import Door/RM — /cite a Library paper → live reference list → style switch; the non-AI writing bicycle

C0 render spike plan-ready

Pull 5Gate 5Effort 3Rev 4

depends on Note Editor + reference-manager; C0 can de-risk in parallel but cannot ship first

5Paper Reader

Building · Read v1

parallel — Read v1 opens a Library PDF in a large branded reader; Mark v2 adds highlight → note → jumpback

Plan ready · Read v1Mark v2 later

Pull 5Gate 4Effort 3Rev 4

does not block non-AI cited writing

6Grounded AI Write

Grounded Assist · needs design pass

Grounded Assist — after Note Editor + Note Citations + RM AI-index/RAG; AI suggestions emit citation nodes; first AI command contract is not plan-ready

Not plan ready

Pull 5Gate 5Effort 2Rev 4

depends on Note Editor + Note Citations + RM AI-index/RAG + Dynamic Organization consumer contract

7Submission Export

Manuscript Finish · design pinned

Manuscript Finish — after Note Citations; cited note/draft → docx/LaTeX/venue handoff

Pull 4Gate 3Effort 2Rev 3

depends on Note Editor + Note Citations (cited note/draft model)

8Manuscript Review

Manuscript Finish · design pinned

Manuscript Finish — after Grounded AI Write; claim/citation audit (unsupported claims, weak evidence, misattribution)

Pull 4Gate 3Effort 2Rev 4

depends on Note Citations + Grounded AI Write (a cited note/draft + source provenance)

9Dynamic Organization

Building · M0 ✓ done, M1 next

auto-tags the library for search/filter + smart-folder views — folders stay user-owned, Shubo only tags; M0 substrate builds in parallel with Foundation, M1–M8 follow unless Grounded Assist needs a consumer contract earlier (@pinglin)

M0 ✓ doneM1 next · M2-M8 laterGrounded Write dep ratified

Pull 4Gate 4Effort 2Rev 4

depends on reference-manager + Import Door (a populated library) · full onboarding not required · obeys DESIGN-faceted-organization

10First Warm Library Ask

Next · activation

activation/RAG proof after Import Door + RM full-text Part 2/R3 — readiness rollup, manual Library Ask, source fragments, and scope disclosure

Plan ready · Slice 1Slice 2 chips later

Pull 3Gate 2Effort 3Rev 5

good-to-have for onboarding activation; not the writing spine

11Full Onboarding

Building · later acquisition

route ① OpenAlex/ORCID claim → My work shipped; route ③ topic and add-your-work later

Pull 3Gate 2Effort 3Rev 5

not a Foundation blocker; the narrow Import Door owns cited-writing entry

SHARE ERA collaboration layer

Gated after personal-first is complete. Share verbs unlock these.

12Real-time Collaboration

Next · designed

when share lands — the collaboration base (Hocuspocus + Yjs)

Pull 3Gate 5Effort 3Rev 5

depends on personal-first complete

13Comments

Next · designed

right after collab — "share to comment", anchors free from Yjs

Pull 4Gate 3Effort 4Rev 5

depends on collaboration (Yjs anchor layer)

14Notification Center

Next · designed

with comment — mention/reply triggers; self-built center + Sonner toast

Pull 3Gate 3Effort 4Rev 5

depends on collaboration (event source)

Deferred candidates — good subfeatures, not Foundation blockers

Large features compress to a minimal MVP first. Useful subfeatures outside that MVP stay visible here with priority, instead of bloating the active acceptance bar. They do not need full implementation planning until they enter a critical path or a ranked slot.

Medium · PDF upload/import

After Foundation, accept user PDFs. First design metadata/cite-truth extraction, duplicate handling, attachment pairing, and failure UX.

Low · RIS / CSL-JSON parity

After .bib ships, add .ris and CSL-JSON file support through the same parser/import module and ImportSources path.

Low · bioRxiv / medRxiv URLs

Parse canonical preprint URLs into DOI form; keep DOI/arXiv as the Foundation path.

Dependency map — blockers and parallel work (no time scale)

Foundation writing path — follow the arrows

Already cleared: RM core. It is no longer a Foundation blocker; it stays in the lanes below only as context.

Import Door

citeable Source truth

Note Editor

base writer

→

Note Citations

cited-writing payoff

Import Door and Note Editor can build in parallel. Note Citations is where they merge. AI-index and Library Ask are activation/RAG work below; they do not block the non-AI cited-writing bicycle.

Reference Librarynon-AI core · root

RM corecleared

Import Doorneeds RM

.bib importblocker

Note Editorbase writer

notes + slashparallel

Note Citationsneeds Notes + RM

/cite + refsmerge

RM AI-index Bridgeactivation/RAG

AI-index bridgeAI layer

First Warm Library Askactivation

manual Library Askgood-to-have

Paper Readerneeds RM full text

Read → Markparallel

Dynamic Organization‖ parallel · @pinglin

Dyn Org M0/M1parallel

Grounded AI Writeneeds citations + RAG

AI draft + citesneeds plan

Submission Exportneeds Note Citations

docx / LaTeX

Manuscript Reviewneeds grounded write

claim / citation audit

personal-first complete · share verbs unlock

Collaborationafter personal-first

Collaboration

Commentsneeds collab

Comments

Notificationneeds collab

Notification

Cleared prerequisite Current Foundation writing blocker Writing payoff target Parallel · not blocking Foundation Later planned personal feature Needs design pass · not plan-ready Share Era ← left = dependency depth, not time

Status — just three (keep PM simple)

Next→ Building→ Shipped→ archive/ · closed

Next = queued (raw idea → fully-designed; readiness shows in the FEAT's own filled sections). Building = being built now (the active named stage). Shipped = a user can actually do the thing — that, not a green backend, is the bar; only Shipped triggers a help article (R7). Design-done and code-green (e.g. RM's R0) are Scope ☑ facts inside the FEAT, never board states. A finished FEAT closes to archive/ (self-labeled Shipped ✓) with the repo's docs/ + help/ as its living record. The board shows only: what's shipped, what's building, what's next.

System map — five concepts (frame → work → outward truth)

Two former "layers" were cut to stay simple: archive/ is a state (Retired), not a doc type — see Status above; and inward "how it works" is not a planning prefix — it lives in each repo's docs/ / docs/invariants/ next to the code (the quality gate), so planning owns only the outward help/.

Layer	Prefix / file	Manages	Time
Vision	`DIRECTION-`	why we exist / where to go	rarely changes
Design	`DESIGN-`	cross-feature laws a FEAT obeys	revised, never ships
Feature	`FEAT-<name>`	one buildable unit (+ Scope ☑/☐)	ships complete
Board	`ROADMAP.md`	ranking + Now + discipline	always rolling
Help (outward)	`help/` · MkDocs	what a user can do today · en/zh-Hans/zh-Hant · on ship	tracks shipped

Discipline — R1–R7 (the system stays alive)

R1 · discovery before creation

Discuss a feature → first check it's in a FEAT; if not, create one + register in ROADMAP. A conclusion that stays in chat didn't happen.

R2 · single source of truth

A decision/scope lives in one doc (its FEAT/DESIGN); ROADMAP only references.

R3 · status freshness

Code lands → mark the FEAT ☑→✓, update status, roll Now. A board that lies is worse than none.

R4 · stage rolling

Active stage end-to-end green → check the next ☐ batch → roll Now to the next named stage. One cycle at a time.

MVP compression

Big feature → name the smallest useful MVP in Now; move good-but-not-now subfeatures to backlog with high / medium / low priority.

Critical-path planning

Only MVP slices blocking the active loop must be plan-ready. Other subfeatures stay backlog, parallel, or later-stage until they compete for a ranked slot.

R5 · prefix / extract-DESIGN + archive-on-close

Hit a decision bigger than the feature (constrains others) → extract a DESIGN the FEAT references. Two things archive: dropped/superseded (✗) and fully-closed FEATs (✓, once the repo docs/ + help/ exist). The bloat valve — the live board shows only in-flight work.

R6 · no BUG-/IMPROVEMENT-

Improvement = a ☐ item or a new FEAT; a bug worth fixing is just fixed.

R7 · HELP on ship

When a user-facing feature ships: confirm the repo's docs/invariants reflect it (inward — already required by the quality gate) + write the help-center article (outward, en/zh-Hans/zh-Hant) from the user's POV. Tracks shipped reality — never pre-written from the roadmap.

⚙ enforced by

the shubo-planning skill — fires whenever a feature/scope is discussed.

Generated snapshot · canonical source ROADMAP.md
Upstream constraints (DESIGN): research-workspace-journey · billing-subscription