vault-compact

# Vault Compact Reduce repeated thinking across the active vault. This skill is for semantic overlap, not just exact duplicate text: compact passages when they do the same job in the knowledge system. Portent reference: `../references/portent-knowledge-base-spec.md`. Prefer compaction when files represent the same Portent object or repeat the same claim for the same object. Do not merge merely because objects share a Topic. Preserve `belongs_to` and `related_to` metadata when absorbing files. ## 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). Seed overlap-candidate groups from recent files. When a recent note overlaps an older canonical one, keep the older established note as the canonical destination, consistent with the Canonical Destination Rules below. ## Command ``` vault-compact [--scope notes|ideas|projects|all] [--mode report|apply-safe|apply] [--aggression conservative|normal|aggressive] ``` ## Parameters - `--scope notes|ideas|projects|all` (default: `all`) - `--mode report|apply-safe|apply` (default: `report`) - `report`: identify overlap and propose canonical destinations only - `apply-safe`: apply high-confidence local compaction only - `apply`: also merge high-confidence cross-file overlap when provenance and links can be preserved; delete absorbed curated files when appropriate - `--aggression conservative|normal|aggressive` (default: `conservative`) - `conservative`: exact/near-duplicate sections and obvious repeated claims - `normal`: same-claim overlap with unique examples preserved - `aggressive`: broader synthesis; appropriate for shipped/archived project compaction or when explicitly requested ## What Counts As Overlap Compact when multiple passages are doing the same job: - repeated thesis or framing - duplicated audience/problem/value-prop language - duplicated project status or next-action text - same source summary in multiple curated notes - same idea split across multiple idea notes - concept explanation repeated instead of linked to the concept page - stale restatement that is superseded by a clearer canonical section - shipped project launch artifacts, drafts, and research that have served their temporary purpose Do not compact just because notes share keywords. ## Unit Of Judgment Compare passages as claim-like units: - thesis - audience - problem - product idea - decision - evidence - example - caveat - open question - next action - implementation detail - source summary If two units make the same claim, collapse them. If one adds a distinct example, decision, caveat, source, audience, or implementation detail, preserve that detail. ## Workflow 1. Read `AGENTS.md`, then `index.md`. 2. Confirm the scoped directories: - `notes/` - `ideas/` - `projects/` 3. Exclude `raw/`, `raw/processed/`, `raw/assets/`, and `archive/` unless the user explicitly asks for an audit that includes archived curated material. 4. Use qmd first for semantic retrieval: - `qmd query` for themes and semantic overlap - `qmd search` for exact phrases, titles, URLs, and aliases - `rg` for migration residue, raw strings, and link rewrites 5. Build candidate groups by canonical topic, project, idea, source, or claim. 6. Classify each group by Portent object identity, confidence, and compaction action. 7. In `report` mode, stop after a compact report. 8. In `apply-safe` mode, apply only local, high-confidence edits inside one file or obvious link substitutions to canonical concept notes. 9. In `apply` mode, apply high-confidence cross-file compaction only when all unique content and provenance can be retained. 10. Delete absorbed curated files only after the canonical destination preserves their unique claims, examples, decisions, and provenance. 11. Update `updated:` frontmatter on edited curated notes where practical. 12. Run `qmd update` after any edits, moves, or deletions. 13. Append one concise line to `log.md` for every material vault change. ## Compaction Actions - `dedupe`: remove exact or near-exact repeated paragraphs, bullets, or sections. - `collapse`: replace equivalent claims with one sharper canonical statement and preserve unique examples, caveats, evidence, and decisions below it. - `route`: replace repeated local explanation with a wikilink to the canonical note or section. - `merge-plan`: propose a merge, canonical destination, unique content to preserve, and link rewrites; do not edit. - `absorb-delete`: after a successful merge, remove curated source files whose useful content now lives in the canonical destination. - `link-only`: add or propose a relationship link because notes are related but distinct. ## Confidence Rubric ### High Confidence - Same source URL or same clipped source identity. - Same title, slug, project, or idea identity. - Same Portent object identity or same claim serving the same object. - One note explicitly continues, replaces, or supersedes another. - Passages make the same claim with compatible meaning. - Differences are examples, wording, or ordering, not substance. - Canonical destination is obvious. High-confidence items may be compacted in `apply-safe` when local to one file, or in `apply` when cross-file provenance and links can be preserved. ### Medium Confidence - Same broad thesis with a meaningful caveat in one passage. - Same product shape but slightly different audience or monetization. - Same concept repeated across notes but no existing canonical destination. - Canonical destination is plausible but not obvious. Medium-confidence items become merge plans or concept-promotion candidates. ### Low Confidence - Same broad domain only. - Similar vocabulary but different use cases. - Similar AI-generated structure but different actual content. - Different lifecycle states or strategic decisions. Low-confidence items should remain separate; propose links only when useful. ## Canonical Destination Rules ### Notes - Prefer canonical concept pages under `notes/concepts/` for repeated theses. - Prefer existing topic notes over creating new notes. - External clipped notes are evidence, not owned synthesis. Preserve source identity and do not absorb complete external text into owned notes. - Repeated source summaries should cite complete source records under `raw/processed/YYYY-MM-DD/` when used for synthesis. - Preserve `belongs_to` and `related_to` metadata when compacting or absorbing notes. ### Ideas - Keep the canonical idea in its lifecycle location under `ideas/`. - Preserve distinctions in audience, wedge, pricing, validation status, and kill criteria. - If two ideas share a product shape but differ in customer or strategy, do not merge; create a comparison or shared concept link instead. ### Projects - Keep project PRDs, plans, decisions, research, and postmortems separate unless one is clearly obsolete or duplicative. - Canonical project state should live in Portent frontmatter, the main project PRD, README, or active index navigation according to the local convention. - Do not merge active, paused, shipped, and rejected rationales into one generic project summary; lifecycle context matters. - For shipped projects, run heavier compaction after the shipping transition. Merge temporary launch materials, tweet drafts, old outlines, research snippets, and implementation leftovers into one canonical shipped project record when they no longer serve active execution. - Shipped project compaction may delete absorbed curated files after the merged record preserves unique outcomes, lessons, market notes, source links, and reusable copy. ## Synthesis Rules Conservative synthesis is allowed only when: - source passages agree - no distinct decision, caveat, example, or evidence point is lost - provenance links remain intact - the new wording is more precise than the repeated wording - the edit reduces repeated thinking rather than merely shortening the note Prefer this shape: ``` Canonical claim. Supporting examples: - example from note A - example from note B Evidence: - [[raw/processed/YYYY-MM-DD/source|Complete Source Record]] ``` Avoid flattening useful nuance into generic summaries. ## Safety - Never edit anything under `raw/`. - Never delete source evidence. - Never delete curated files until their unique content has been merged into a canonical destination and inbound links have been updated. - Never compact distinct ideas because they share keywords. - Never replace a source record with a summary. - Never remove unresolved questions, decisions, caveats, or examples unless they are duplicated elsewhere in the same canonical destination. - Never merge across lifecycle states without preserving the lifecycle meaning. - Default to `report` when confidence is not high. - Keep all edits reviewable and list touched files. ## Output Return: - Scope, mode, and aggression used - Candidate groups with canonical destination, confidence, and rationale - Applied changes by file and compaction action - Preserved unique claims, examples, evidence, and decisions - Deferred merge plans with required user decisions - Link-only relationships proposed or applied - Absorbed files deleted, with canonical destination - Files intentionally skipped and why - `qmd update` status - `log.md` entry status ## Example Report Shape ```markdown ## Compact Report ### Applied - `notes/concepts/example.md`: collapsed repeated thesis under `## Core Claim` and preserved two unique examples. ### Merge Plans - Canonical: `ideas/incubating/example-prd.md` - Candidates: `ideas/fleeting/example.md`, `notes/app-marketing/example-positioning.md` - Confidence: medium - Rationale: same product shape, but audience differs. - Preserve: pricing caveat, validation question, source link. ### Skipped - `projects/active/example/prd.md` vs `projects/paused/example/prd.md` - Reason: same project name but different lifecycle state and decision context. ### Maintenance - `qmd update`: not run in report mode - `log.md`: not updated in report mode ```