Vault Research

---
name: vault-research
description:
  Use when a vault note, idea, project, or topic needs external sources,
  competitor research, discussion evidence, or market signals
---

# 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