vault-concepts

What this skill does

# Concepts

Promote recurring themes into canonical concept pages and keep concept
navigation coherent.

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

## Recency Priority

Work the active surface newest-first, ranked by each object's `updated`
frontmatter date (fall back to file modification time when `updated` is absent).
Concentrate scrutiny on the freshest material — recently-touched objects are
where active thinking lives and where new mismatches, overlaps, and gaps appear.
Long-untouched objects are assumed settled and rank lower, but are never
excluded: they remain valid link targets, merge destinations, and canonical
homes, and still get a structural check (broken links, orphaning).

Weight theme detection toward recent notes so emerging themes surface early, but
keep temporal spread as the high-confidence signal: a concept still needs
occurrences across time, not just a recent burst.

## Purpose

Maintain `notes/concepts/` as the durable vocabulary of your vault. Surface
cross-domain patterns and decide when transience deserves permanence.

Concept pages are Portent `Topic` objects. New recurring-theme pages should use
`type: Topic`, `status: organized`, and explicit `related_to` links to the
Projects, Notes, Events, or Responsibilities they help explain.

## Parameters

- `--topic TOPIC` focus on specific theme (optional)
- `--mode report|apply` (default: `report`)

## Thresholds for New Concept Creation

Only create new concept pages when ALL are true:

- Theme appears in 3+ unrelated notes
- Evidence is concrete and linkable
- Destination concept is clear
- Destination Topic object is clear
- Change is additive and low-risk

## Workflow

1. **Scan**: Read active surface (`notes/`, `ideas/`, `projects/`) for recurring
   themes
2. **Detect**: Extract patterns across unrelated notes:
   - Phrases/metaphors that recur
   - Principles or mental models
   - Unresolved questions with traction
3. **Filter**: Remove false positives:
   - Deliberate tag repetition
   - Common filler phrasing
   - Same-project-only repetition
4. **Cluster**: Group related patterns and rank by confidence
5. **Decide** per candidate:
   - Update existing concept page
   - Merge near-duplicate concept pages into one canonical concept
   - Create new concept page (if thresholds met)
   - Defer (insufficient evidence)
6. **Normalize**: Rewrite transient note references to point to canonical
   concepts
7. **Refresh**: Update `index.md` when concept navigation changes
8. **Log**: Append concise operation entry

## Confidence Rubric

- **High**: 3+ unrelated notes with temporal spread
- **Medium**: 2 unrelated notes with strong conceptual overlap
- **Low**: Weak recurrence or same-domain concentration

## Apply Behavior

- **report**: List candidates only, no changes
- **apply**: Update existing concepts; merge high-confidence duplicates; create
  new ones when thresholds met

## Merge Rules

Merge concept pages when they name the same principle, mental model, or durable
vocabulary item. Do not merge broad neighboring concepts just because they are
often linked together.

- Choose the clearest, most established page as canonical.
- Preserve distinct examples, open questions, and source links from merged
  pages.
- Rewrite links from merged pages to the canonical concept.
- Keep aliases when alternate names are likely search terms.
- Report medium-confidence concept overlaps instead of merging them.

## Safety

- Prefer updating existing concepts over creating near-duplicates
- Never delete notes or archive content
- Never merge concept pages that represent different decisions or levels of
  abstraction
- Never modify raw/, processed/, or assets/
- Confirm before creating new concept pages

## Output

Return:

- Concepts created/updated/proposed (with confidence)
- Concepts merged/proposed for merge
- Topic object metadata added or updated
- Evidence links used
- Reference normalization performed
- Index/log update status
- Recommended follow-up actions