reconcile

The weekly operation of the three-op protocol. Scoped to the diff, not the corpus. A full-vault health check doesn’t work at this vault’s size (~6k files); a bounded check of what actually changed does.

When to use

• User runs /reconcile.
• Weekly scheduled routine fires (Sunday default).
• User says “reconcile the week”, “check the recent changes”, “what should I do with this week’s work”.

What this is NOT

• Not a whole-corpus judgment pass. Integration, PARA fit, privacy, synthesis — all touched-set only.
• Whole-corpus mechanical checks (orphans, broken links) are delegated to the deterministic vault-doctor script — reconcile runs it and interprets, never hand-scans the corpus.

The scope discipline is the whole point: LLM judgment stays on the diff; exact checks run as code. If you catch yourself hand-scanning outside the touched-set, stop.

Workflow

1. Frame the week

1. Run vault-tree (depth 2) for structural orientation.
2. Run recent-changes (default 7 days). This is the ground truth for scope.
3. Run python3 7_Agent/skills/vault-doctor/vault-doctor.py — deterministic whole-vault health report (broken links, orphans, frontmatter gaps, empty files). Keep the output for steps 2–3.

The touched-set is: files marked A, M, or R in recent-changes. Deletions are noted but don’t drive further checks (the page is gone).

1.5 Mechanical fixes — apply directly, don’t queue

Reconcile has license to fix mechanical defects without approval, logged in the run’s log entry:

• Broken wikilinks from the vault-doctor report whose source or target intersects the touched-set, where the correct target is unambiguous (a rename, an obvious typo, a path-qualified link that snapped). Fix the link text directly.
• Obvious frontmatter gaps on touched pages (missing created: where the filename has a date, missing lang:).

Ambiguous cases (unclear intended target, judgment-dependent) go in the report as before. Pre-existing broken links outside the touched-set: report the count and worst offenders; don’t mass-edit old prose.

2. Per-page integration check — touched-set only

For each new or substantially-edited page:

• Does it link out? A page with zero outbound wikilinks is usually under-integrated. Propose 1–3 concrete wikilinks to existing pages where the connection is clear.
• Does it fit its folder? Quick PARA sanity check. A project note that landed in 3_Resources/ is a mis-route; surface it.
• Does it collide with another touched page? Two pages created the same week covering the same topic are a consolidation candidate.
• Does it mention terms that exist as notes but aren’t wikilinked? Only check within the touched page — do not scan the corpus for incoming references to it.
• Is it correctly classified for privacy? Check if the note contains personal/introspective content, professional/work-confidential material, or confidential information. If it does and it’s not in 6_Private/ and doesn’t have draft: true, flag it as a privacy mis-route. See Privacy Classification.

3. Move / rename impact

For each R entry:

• Verify inbound wikilinks still resolve. Obsidian resolves by title, so renames within the same title usually work; path-qualified links ([[2_Areas/Old Path|Old Path]]) break and need rewriting.
• Surface any broken inbound refs as a concrete fix list in the report.

4. Promotion & merge candidates

• Promotion: did this week’s edits push an existing page over the canon bar (≥10 inbound, substantial, synthesized, stable-ish)? If yes, propose /crystallize.
• Merge: are two touched pages near-duplicates or heavy overlap? If yes, propose /consolidate.

Three-strike rule (promotions only): check the previous two weekly reports. If the same page has been a promotion candidate in 3 consecutive reports (this one included) and still meets the crystallize bar, don’t propose a fourth time — invoke crystallize in its reconcile-invoked mode, which applies the promotion and posts an FYI notification (git revert is the undo). This prevents the propose→ignore→re-propose loop that leaves _Canon/ empty forever.

Merges never auto-apply — consolidate is destructive-ish (two pages become one) and always keeps its approval flow. Repeat merge candidates just get flagged as (Nth consecutive week) in the report.

5. Synthesis — the generative part

This is the piece that makes reconcile more than a weekly diff viewer:

• Topic clustering. Group the week’s new pages by topic. If ≥3 pages circle one concept, propose a concept / index page that threads them together.
• Answered questions. Read the tail of 7_Agent/questions.md (entries since last reconcile). Cross-check each against the week’s new content. If a question has been answered, note it so the user can prune.
• Spawned questions. New pages often raise questions they don’t answer. Capture those — either as log-question entries or as report bullets.

Keep this section concrete: a proposal is “create Concept X threading A B C”, not “think about X more”.

6. Write report

Write to 7_Agent/reconcile/<YYYY-Www>-reconcile.md:

---
created: YYYY-MM-DD
tags: [agent, reconcile, report]
draft: true
---
 
# Reconcile report — Week YYYY-Www
 
Scope: last 7 days (YYYY-MM-DD → YYYY-MM-DD). N touched pages across <folders>.
 
## Overview
<2–3 sentences: what did the week touch? Any refactors? Any noticeable concentration in one PARA area?>
 
## Integration
- [[Page A]] — new in 2_Areas/X/. Links: [[Y]]. Suggested cross-refs: [[Z]], [[W]].
- [[Page B]] — edits this week but no outbound links. Under-integrated; candidates: [[Y]].
 
## Consolidation candidates
- [[Page A]] + [[Page B]] — both new this week, cover <topic>. Run `/consolidate` if agreed.
 
## Promotion candidates
- [[Page C]] — edits this week pushed it over the bar (N inbound, substantial, synthesized). Run `/crystallize` if agreed.
 
## Privacy mis-routes
- [[Page E]] — contains work-confidential content but is in `2_Areas/`. Move to `6_Private/` or add `draft: true`.
 
## Moves / renames
- `2_Areas/Old.md` → `2_Areas/New.md`. Inbound wikilinks: M (all resolve by title / K need rewriting).
 
## Synthesis
- Three pages this week orbit <topic>: [[A]], [[B]], [[C]]. Consider creating [[Topic]] as a concept page.
 
## Questions
- Answered this week: [[questions.md]] line N — "<question>" → answered by [[Page D]].
- Raised this week: "<new question>" — logged via `log-question`.

Empty sections still show the heading + “none” — it’s an explicit null, not a silent omission.

7. Append to log

Append to log:

## [YYYY-MM-DD] reconcile | Week YYYY-Www
- Touched pages: N
- Substantive items surfaced: K (see [[7_Agent/reconcile/YYYY-Www-reconcile]])
- Notes: <one line on anything unusual this week>

8. Notify — one rolling item, not a stack

Check notifications for prior unwalked reconcile walk-through items. Fold them: delete the old items and append a single rolling action item that lists every outstanding week, oldest first:

- [ ] YYYY-MM-DD — action: Walk through reconcile findings — N weeks outstanding: [[7_Agent/reconcile/YYYY-Www-reconcile|Www]] (K items), [[7_Agent/reconcile/YYYY-Wxx-reconcile|Wxx]] (K items; headline: <one line for the newest week>)

A five-item backlog is what stops the human from triaging at all; one line that says “5 weeks outstanding” is honest and actionable. Also delete any notification items whose referenced files no longer exist (stale), noting them in the log entry.

Skip the new item entirely if the report has zero substantive items and nothing is outstanding.

9. Weekly digest

Run the weekly-digest skill. It reads the report + actual touched pages and writes 0-n private articles in 6_Private/Digest/ about themes that emerged this week. Skip if the diff was empty.

10. Housekeeping — index + log rotation

1. Regenerate the vault index: python3 7_Agent/skills/build-index/build-index.py (see build-index).
2. Quarter check: if this is the first reconcile of a new quarter, rotate log — move the previous quarter’s entries to 7_Agent/log/<YYYY-Qn>.md (same frontmatter, # Operations log — <YYYY-Qn> (archive) heading), leave log.md with its header + the new quarter’s entries, and update the Archives list in log.md’s header.

Rules

• Touched-set only for judgment work. If a judgment check would require scanning pages outside the 7-day window, it doesn’t belong in reconcile. Whole-corpus mechanical checks go through vault-doctor.
• Propose, don’t apply — with two carve-outs. Mechanical fixes (step 1.5) apply directly with a log entry. Promotions hit the three-strike rule (step 4). Everything else — merges, moves, deletions — is a proposal.
• Never delete pages. Even a clearly-wrong routing is a proposal. (Stale notification items pointing at deleted files may be pruned — see step 8.)
• Report is a draft. draft: true keeps it out of Quartz.
• One report per ISO week. If the skill is invoked twice in the same week, overwrite rather than create a second report for that week.
• Cheap to re-run. Everything’s bounded by the 7-day diff, so re-running is fine.

Blocked cases

• Empty diff. No file changes in the window → write a minimal report noting “no activity”, skip the notification, log the run.
• Massive refactor week. If recent-changes reports hundreds of renames (e.g., a sweeping folder reorganization), the integration check is noisy and the synthesis section is more useful than the per-page section. Say so in the Overview and focus on the reorganization’s coherence instead.

Verification

• 7_Agent/reconcile/<YYYY-Www>-reconcile.md exists with all sections populated (or “none”).
• log has a new entry for the run.
• notifications has a new action item pointing at the report (unless the report had zero substantive items).
• git diff shows only: report + log + notifications + regenerated 7_Agent/index.md + any step-1.5 mechanical fixes + any three-strike crystallize move — each of the latter two accounted for in the log entry. No other substantive page edits.