Vault research

Research

Research a target note, idea, project, or topic. Preserve external sources as traceable source records by default; write summaries only when the user asks for synthesis, assessment, or a concise research brief. Any source used in a summary keeps a complete immutable copy in raw/processed/YYYY-MM-DD/.

Notes tagged external are treated as clipped/imported external sources and are eligible for synthesis while preserving the complete source record.

Portent reference: ../references/portent-knowledge-base-spec.md.

Research briefs are type: Note by default. External changes, meetings, incidents, product launches, or decisions that happened are type: Event. Every synthesized Note or Event should set belongs_to to its primary Project, Responsibility, Operation, or Topic when that context is clear.

Parameters

Target can be:

• note filename (voice-notes-app or voice-notes-app.md)
• relative path (notes/car-search/prd.md)
• absolute path

Optional flags:

• --mode report|apply (default: report)
• --output sources|summary|both (default: sources)

Target Resolution

Resolve target in this order:

1. exact path
2. unique basename match
3. if ambiguous, ask one concise disambiguation question and stop

Workflow

1. Load the target and extract topic/problem and context.
2. Check whether target/source notes carry an external tag.
3. Run three tracks in parallel:
   • competitor landscape
   • community discussions (Reddit/HN/forums)
   • market signals (funding/trends/news)
4. Classify each external source by type, relevance, topic, and confidence.
5. Classify the output as a Portent Note or Event and identify the primary belongs_to relationship when clear.
6. Choose output behavior:
   • sources: create or update source records only
   • summary: write a concise synthesized research block with citations
   • both: preserve source records and write a concise synthesis
7. In apply mode, archive every external source used for synthesis to raw/processed/YYYY-MM-DD/ before writing the synthesis.
8. Place working source records in the closest durable location:
   • projects/active/<project>/research/
   • ideas/<state>/<idea>/research/
   • notes/<topic>/
9. Merge source records into an existing research/source note when they cover the same external source or same research thread.
10. Assign confidence (high|medium|low) for key claims.
11. If writing a summary, keep it clearly separate from owned notes and link back to archived complete source records.
12. Return what was found, where sources were placed, and what was written.

Copy vs Synthesize Decision

Default to --output sources for untagged material. Notes tagged external may use summary or both during processing because the tag explicitly marks them as external clipped sources.

• Use sources for collecting, categorizing, moving, linking, or preserving external records without interpretation.
• Use summary when the user wants an answer or brief and does not need separate working source notes.
• Use both when the user wants synthesis and the sources should remain useful as organized research material.

Never summarize user-authored ideas, project drafts, plans, or notes as part of research unless the user explicitly asks for that specific note to be summarized. Link external findings to those owned notes instead.

Evidence Policy

• Prefer primary sources when available.
• Mark uncertain claims explicitly instead of overstating.
• Keep findings actionable and traceable to sources.
• Do not replace, compress, or rewrite owned project ideas or user-authored notes as a research side effect.
• Treat external as the source-origin signal for synthesis eligibility.
• Merge duplicate external-source records when URL/source identity matches; otherwise link related sources instead of collapsing them.
• Cite archived complete source records from raw/processed/YYYY-MM-DD/ for every synthesized claim or source summary.

Constraints

• Default behavior is report-only and source-first.
• Summary writing requires external, --output summary, --output both, or an explicit user request for synthesis.
• In apply mode, do not write a summary until complete source records have been archived.
• If signal quality is weak, report low confidence and preserve sources without overstating conclusions.
• If target note lacks enough context, ask for clarification before broad search.

Output

Return:

• target note path
• source records found/created and their destination paths
• archived complete source paths under raw/processed/YYYY-MM-DD/
• source records merged and canonical destinations
• findings summary if requested
• Portent output type and belongs_to relationship used or proposed
• confidence highlights
• whether source records or target notes were updated
• suggested follow-up actions