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 personal library → read papers + cited writing

The first personal-first research workspace foundation — useful with zero AI, zero collab/billing.

Feature☑ Foundation scopeStatus
reference-managerSource truth · Library search/listing · full-text availability · import target · read/cite anchorBuilding · library substrate
import door.bib import into citeable Source truthNext · .bib only
paper-readeropen a Library PDF in a large branded readerVerify · Read v1
note-editorproduction Note CRUD · basic location/move · structured TipTap body · save/reopen · generic slash commandsNext · needs design docs
note-citations/cite from Library · citation nodes · live References · CSL/style framework + switchNext · style framework pinned
Foundation read loop: sign up → .bib import or existing Library source has available full text → open the Library paper in Paper Reader Read v1 → the PDF is readable in a large branded reader with honest unavailable states.
Foundation write/cite loop: 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.
Paper Reader Read v1 is Foundation visual accepted Playwright pending — uploading/importing references is not enough; the user must be able to open and read the paper. Read v1 validates reading; Mark v2 highlight → note → jumpback stays later.
‖ 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 · Paper Reader Mark v2 · 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
Next
can build in parallel with import — production notes, CRUD, basic location/move, TipTap editor, generic slash commands; no sharing UX
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
Next
after Note Editor + Import Door/RM — /cite a Library paper → live reference list → CSL/style framework + style switch; the non-AI writing bicycle
Style framework acceptance pinned
Pull 5Gate 5Effort 3Rev 4
depends on Note Editor + reference-manager; CSL/style proof 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; live eyeball passed; Mark v2 adds highlight → note → jumpback
Visual accepted · Read v1Playwright pendingMark 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/.

LayerPrefix / fileManagesTime
VisionDIRECTION-why we exist / where to gorarely changes
DesignDESIGN-cross-feature laws a FEAT obeysrevised, never ships
FeatureFEAT-<name>one buildable unit (+ Scope ☑/☐)ships complete
BoardROADMAP.mdranking + Now + disciplinealways rolling
Help (outward)help/ · MkDocswhat a user can do today · en/zh-Hans/zh-Hant · on shiptracks 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.
Next FEAT planning
For planning-only work, scope + acceptance/QA + dependencies are enough. Backend/frontend implementation sections may stay deferred until Building.
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.