graduate-insights

name	graduate-insights
description	Review and graduate notes to permanent status using Zettelkasten principles. Consolidates AI extractions and document insights into curated permanent notes.
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","AskUserQuestion","Task"]
user-invocable	true

Graduate Insights

Review candidate notes from holding areas and promote valuable ones to permanent note status following Zettelkasten principles.

Purpose

The knowledge base accumulates insights in multiple holding areas:

• AI Extracted Notes/ - Personal insights from conversations (177 notes)
• Document Insights/ - Research findings from external sources (1,608 notes across 89 sessions)
• Books/ - Per-book scopes (the gems mined from each ingested book; the _book.md hub is a navigation note, not a candidate)
• 00-Inbox/ - Raw captures and staging notes (27 notes)

Without periodic graduation, these insights remain unintegrated. This skill provides a structured review process to:

1. Surface high-value candidates based on retrieval frequency and age
2. Present each for human judgment (the essential step)
3. Graduate worthy notes to 02-Permanent/ with proper formatting
4. Maintain knowledge graph integrity

State Dependencies

Source	Location	Read	Write
Q-values	resources/local-brain-search/data/q_values.json	Yes	No
AI Extracted	Brain/AI Extracted Notes/	Yes	Move
Document Insights	Brain/Document Insights/*/	Yes	Move
Book scopes	Brain/Books/*/	Yes	Move
Inbox	Brain/00-Inbox/	Yes	Move
Permanent Notes	Brain/02-Permanent/	No	Yes
Changelog	Brain/CHANGELOG.md	Yes	Yes

Process

Step 1: Load State and Find Candidates

# Get Q-values for retrieval frequency signals
cat resources/local-brain-search/data/q_values.json

Find candidate notes prioritized by:

1. Q-value > 0 - Notes that have been retrieved and used
2. Age > 14 days - Notes that have had time to prove value
3. Has connections - Notes with wiki-links to permanent notes

Collect up to 5 candidates per session from:

• Brain/AI Extracted Notes/*.md
• Brain/Document Insights/**/*.md (exclude CHANGELOG files)
• Brain/Books/**/*.md (exclude _book.md hubs and CHANGELOG files)
• Brain/00-Inbox/*.md

Step 2: For Each Candidate

Present the following information:

## Candidate [N/5]: [Note Title]

**Source:** AI Extracted Notes | Document Insights ([Session Name]) | Inbox
**Created:** [date from frontmatter or file mtime]
**Age:** [X days]
**Q-Value:** [value or "not tracked"]

### Content Preview
[First 500 characters of note content]

### Existing Connections
[List wiki-links found in the note, indicate which link to permanent notes]

### Semantic Neighbors (if available)
[Run quick search to show 3 most similar permanent notes]

Ask user:

Decision for "[Note Title]":

1. Promote - Graduate to permanent notes
2. Skip - Review again later (note stays in place)
3. Delete - Remove entirely (rare, for duplicates/errors)

Step 3: Handle Promotion

When user chooses Promote:

1. Check for duplicates in 02-Permanent/:

   # Search for similar titles
   grep -r "similar keywords" Brain/02-Permanent/
   

2. Prepare note for graduation:

   • Ensure frontmatter includes:

     ---
     created: [original date]
     updated: [today]
     created_by: [original model if present]
     updated_by: [current model]
     agent_version: 01.25
     provenance: [see rule below]
     graduated_from: [original path]
     graduated_date: [today]
     ---
     

   • Provenance rule (mandatory): default by source - Document Insights/ and Books/ -> encountered; AI Extracted Notes/ or agent synthesis -> ai-inferred. Preserve an existing provenance: value if the candidate already carries one. Per CLAUDE.md's guarded boundary, only set originated or endorsed when the user explicitly says so at the Promote decision - graduation must never silently mint originated.
   • Verify atomic insight format (single clear idea)
   • Ensure wiki-links use [[Note Title]] format
   • Remove source-specific metadata (session info, extraction date)
   • Note: BDG will auto-classify the layer on next bootstrap (insight or framework based on heuristics)

3. Optionally refine: Ask user: "Refine title/content before promoting? (or press Enter to keep as-is)"

4. Move to permanent:

   • Generate clean filename: Brain/02-Permanent/[Title].md
   • Move file (not copy - maintains git history)
   • Verify move succeeded

Step 4: Handle Skip

Note remains in original location. No action needed.

Step 5: Handle Delete

Confirm before deleting:

Are you sure you want to DELETE "[Note Title]"?
This cannot be undone. Type 'yes' to confirm.

If confirmed, remove file.

Step 6: Session Summary

After processing all candidates:

## Graduation Session Complete

**Reviewed:** 5 notes
**Promoted:** X notes
**Skipped:** Y notes
**Deleted:** Z notes

### Promoted Notes:
- [[New Permanent Note 1]] (from AI Extracted Notes)
- [[New Permanent Note 2]] (from Document Insights/Session Name)

### Remaining Candidates
- AI Extracted Notes: [count] notes
- Document Insights: [count] notes
- Inbox: [count] notes

Run `/graduate-insights` again to continue review.

Step 7: Update Changelog

Append to Brain/CHANGELOG.md:

## [DATE] - Insight Graduation Session

**Promoted to Permanent:**
- [[Note 1]] - graduated from AI Extracted Notes
- [[Note 2]] - graduated from Document Insights/[Session]

**Session Stats:** Reviewed 5, Promoted X, Skipped Y

Zettelkasten Graduation Criteria

When reviewing candidates, consider these principles:

Promote If:

• Atomic - Contains ONE clear idea (not a list or summary)
• Evergreen - Will remain true/relevant over time
• Connected - Links meaningfully to existing permanent notes
• Original - Adds unique perspective not already captured
• Actionable - Can inform thinking or decisions

Skip If:

• Ephemeral - Time-sensitive or will become outdated
• Compound - Contains multiple ideas (may need splitting)
• Duplicate - Similar insight exists in permanent notes
• Unripe - Not yet clear how it connects or matters

Delete If:

• Exact duplicate - Same content exists elsewhere
• Error - Extraction mistake or corrupted content
• Obsolete - Information proven wrong or superseded

Outputs

1. Promoted notes in Brain/02-Permanent/ with graduation metadata
2. Updated Brain/CHANGELOG.md with session record
3. Session summary showing graduation statistics

Notes

• Human judgment is essential - This skill surfaces candidates, humans decide
• No automated promotion - Every graduation requires explicit approval
• Batch size is 5 - Keeps sessions focused and completable
• Priority by Q-value - Notes that have been retrieved rank higher
• Recommend weekly cadence - Prevents backlog accumulation

Self-Improvement

After completing this skill's primary task, consider tactical improvements:

• Review execution: Were there friction points, unclear steps, or inefficiencies?
• Identify improvements: Could error handling, step ordering, or instructions be clearer?
• Scope check: Only tactical/execution changes - NOT changes to core purpose or goals
• Apply improvement (if identified):
  • Edit this SKILL.md with the specific improvement
  • Keep changes minimal and focused
• Version control (if in a git repository):
  • Stage: git add .claude/skills/graduate-insights/SKILL.md
  • Commit: git commit -m "refactor(graduate-insights): <brief improvement description>"