viexp/docs/workflows/research-workflow.md

Research workflow

How research artifacts are collected, analyzed and turned into decisions — the pipeline that feeds every architectural choice in viexp.

Lifecycle

question → TMP/Research.md note (status: inbox)
        → sources collected (table filled)
        → findings summarized (status: in-progress)
        → synthesis article in articles/ (status: analyzed)
        → decision in decisions/ (ADR) + tasks/issues
        → archived (status: archived) once superseded

1. Capture. Any open question gets a Research note immediately (title = the question domain, e.g. djvu-preview-options). One question per note — small notes beat monoliths.
2. Collect. Every source goes into the sources table with a one-line takeaway. Screenshots and PDFs go to attachments/; paste links, not walls of copied text.
3. Analyze. Distill findings into bullets; mark confidence: low|medium|high. Open questions move to follow-up notes, not into the article.
4. Synthesize. Cross-note comparisons become Article notes (e.g. the file-manager comparison). The article states recommendations, not just facts.
5. Decide. Every recommendation that changes the architecture becomes an ADR (Decision template) — short, dated, linked back to the research notes.
6. Act. ADRs spawn Task notes → Gitea issues (see workflows/gitea-workflow).

Weekly review (Friday, 15 min)

• Process all status: inbox notes: promote, merge or archive.
• Update ADRs whose status changed during the week.
• Check that every active sprint task has a linked issue and vice versa.

Obsidian mechanics used

• Templates (TMP/) keep structure uniform; headings are predictable, so folding works.
• Properties (type, status, tags, sprint) power the tag pane and search, e.g. ["type": "research", "status": "inbox"].
• Backlinks / graph show which decisions depend on which research.
• Attachments are centralized in docs/attachments/ (set in Obsidian settings).