graduate-insights

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

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>"