brain-sync

name	brain-sync
description	Synchronize and maintain the second brain. Performs gap detection, journal rollups, task audits, project discovery, and cross-linking. Use when the user says "sync my brain", "update journals", "brain maintenance", or asks to backfill logs.

Brain Sync

Run these steps in order. Each step builds on the previous.

Step 1: Gap Detection and Backfill

Find missing or empty daily journal entries and prompt the user to fill them.

1. List all files in journal/daily/ to find existing entries.
2. Determine the date range: earliest existing daily entry through today's date.
3. For each weekday in that range, check if a YYYY-MM-DD.md file exists.
   • If missing entirely, add it to the missing list.
   • If the file exists but contains no content beyond the template headings (Log/Links sections are all empty), add it to the sparse list.
4. Gather context for missing/sparse days:
   • Use the user-github MCP (or gh CLI) to search for pull requests updated or created by the user on those days (e.g. pull_requests.list_by_user or gh search prs --author "@me").
   • Use the user-jira MCP to search for issues assigned to the user updated on those days (e.g. issues.search with JQL like assignee = currentUser()).
   • Use the user-slack MCP to search for messages sent by the user on those days (e.g. search.messages with query like from:me on:YYYY-MM-DD).
5. Present the gaps to the user:
   • Group missing/sparse days by week for readability.
   • Provide the gathered context from GitHub, Jira, and Slack as hints for what they worked on.
   • Ask the user what they worked on for each gap, or let them skip days (e.g. PTO, sick days).
   • Ask for approximate timestamps if the user can recall them.
6. For each response, create or update the daily entry using the template from templates/daily.md. Timestamp entries as ### HH:MM under the ## Log section. If the user can't recall a time, use ### --:--. Link any mentioned projects or tasks with [[wiki-links]].

Step 2: Journal Rollups

Synthesize higher-tier summaries from lower-tier entries.

1. Weekly: For each ISO week that has daily entries but no weekly summary (or a stale one), read all dailies for that week and write a synthesized journal/weekly/YYYY-WNN.md using the template from templates/weekly.md. A weekly summary is stale if dailies have been modified after the weekly file's frontmatter date.
2. Monthly: For each month that has weekly summaries, synthesize into journal/monthly/YYYY-MM.md using templates/monthly.md.
3. Yearly: For each year that has monthly summaries, synthesize into journal/yearly/YYYY.md using templates/yearly.md.

Synthesis Method

Use a two-pass approach to avoid recency bias:

1. Extract: Read each source entry individually and extract 2-3 bullet-point highlights from it. Do this for every source before writing any summary.
2. Combine: Merge the per-source highlights into a cohesive summary. Preserve key details and link back to source entries with [[wiki-links]].

Proportional coverage: The final summary must represent all source periods roughly equally. No single week should dominate a monthly summary, and no single month should dominate a yearly summary, unless it was genuinely exceptional — and if so, call that out explicitly.

Chronological anchoring:

• Monthly summaries should reference each constituent week.
• Yearly summaries should organize content by quarter (Q1-Q4) within each section to ensure early-year work is not lost.

Step 3: Task Audit

Check task status and detect untracked tasks.

Audit existing tasks:

1. Read all files in tasks/.
2. Scan task files for Jira issue keys or GitHub PR links.
   • When found, query the respective MCPs (user-jira or user-github) to determine the real-time status of those issues or PRs.
   • If a Jira issue is marked "Done" or "Closed", or a PR is "Merged", prompt the user to automatically update the task status to done.
3. For tasks with status: in-progress or status: todo:
   • Search recent daily entries for mentions of the task name or related keywords.
   • If evidence suggests completion, flag it to the user and ask to confirm updating to done.
   • If no recent mentions exist (>2 weeks), flag as potentially stale.
4. For tasks with status: blocked:
   • Check if recent entries mention resolution of the blocker.
   • Flag for review if so.

Detect untracked tasks:

5. Scan daily entries for implied action items not already linked to a task file. Look for patterns like "need to", "TODO", "should", "have to", "action item", "will do", "next step", "investigate", "fix", "follow up".
6. Cross-reference detected items against existing task files to avoid duplicates.
7. Present untracked tasks to the user, grouped by the journal entry they appeared in. Ask which ones to create as tracked tasks.
8. For confirmed tasks, create files in tasks/ using templates/task.md and add [[wiki-links]] in both the task file and the originating journal entry.

Task status changes are automatically reflected in tasks/_board.base — no manual index update needed.

Step 4: Project Discovery

Detect new projects or project updates from journal content.

1. Read all project overview.md files to build a list of known projects.
2. Scan recent daily/weekly entries for recurring themes, codebases, or workstreams not covered by existing projects.
3. If a potential new project is found:
   • Suggest it to the user with supporting evidence (which entries mention it).
   • On confirmation, create a new project folder and overview.md using templates/project.md. New projects automatically appear in projects/_index.base via their frontmatter.
4. For existing projects, check if recent journal entries contain updates worth reflecting in the project's overview.md (status changes, architectural decisions, new goals). Suggest updates to the user.

Step 5: Cross-Linking

Ensure entries are properly interconnected.

1. Scan daily entries for mentions of project names or task names that aren't [[wiki-linked]]. Add links.
2. Ensure project overview.md files link to relevant recent journal entries and tasks.
3. Ensure task files link back to their parent project.

Step 6: Git Commit

Commit all changes made during the sync.

1. Stage all modified and new files from the sync.
2. Create a commit with message: brain: sync YYYY-MM-DD (using today's date).
3. If many distinct areas were touched, use a multi-line commit body summarizing what changed, e.g.:

   brain: sync YYYY-MM-DD
   
   - backfilled 3 daily entries
   - created weekly rollup W05
   - marked task investigate-pooling as done
   - discovered new project: query-gateway
   

Completion

After all steps, summarize what was done:

• How many gaps were detected and filled
• Which rollups were created or updated
• Task status changes
• New projects discovered
• Links added