Review session work and propose knowledge captures for human review. Scans git commits, changed files, and patterns used across repos to generate structured knowledge items. Includes review workflow to approve/reject/edit pending captures before persisting to the knowledge base.
Review session work and propose knowledge captures for human review. Scans git commits, changed files, and patterns used across repos to generate structured knowledge items. Includes review workflow to approve/reject/edit pending captures before persisting to the knowledge base.
allowed-tools
Bash, Read, Write, Edit, Glob, Grep
Knowledge Capture Skill
Reviews work done in the current session and proposes knowledge items for human review before persisting to the knowledge base.
Usage
/capture # Review today's session work
/capture week # Review the past week
/capture 2026-01-15 # Review a specific date
/capture review # Process pending captures (approve/reject/edit)
/capture review all # Process all pending captures in batch
/capture review --batch # Quick batch mode: approve high, skip low
/capture status # Show pending/approved/rejected counts
/capture status --week # Detailed stats for last 7 days
/capture status --tiers # Include tier breakdown (warm/cold/icebox)
/capture archive <file> # Manually archive knowledge to cold storage
/capture icebox "idea"# Park an idea in the icebox
/capture icebox list # List parked ideas
/capture decay # Check for items ready to decay
/capture promote
/capture search <query>
/capture search --tier warm
/capture suggest
# Check for cold items ready to promote
# Search knowledge across all tiers
"stx"
# Filter by tier
# Context-aware suggestions for current repo
Subcommands
/capture (default) - Generate Captures
Scans git activity and generates new captures to ~/logs/captures/pending/.
/capture review - Process Pending
Interactive workflow to review pending captures:
List pending - Show all captures awaiting review
Present each - Display content, metadata, confidence
Ask action - Approve, reject, or edit
Process - Persist approved, archive rejected
Options:
review - Process one capture at a time
review all - Batch process all pending captures
review --batch - Quick batch mode for efficient processing
status --week - Detailed stats with category breakdown and weekly trend
status --month - 30-day detailed view
status --tiers - Include tier breakdown (warm/cold/icebox)
Uses capture-stats.ts helper for statistics.
/capture archive - Move to Cold Storage
Manually archive knowledge items that are outdated or rarely needed:
/capture archive nuggets/old-api.md # Archive specific file
/capture archive patterns/deprecated-*.md # Archive by pattern
/capture archive nuggets/clarity.md --reason "superseded by new version"
Archived files:
Move to archive/{category}/ preserving structure
Add archive metadata (date, reason, original path)
Remain searchable but don't pollute active knowledge
Can be promoted back if accessed frequently
/capture icebox - Park Ideas
Park ideas that aren't ready for the knowledge base:
/capture icebox "Consider using Deno for scripts"# Add new idea
/capture icebox list # List all parked ideas
/capture icebox get 3 # View specific idea
/capture icebox delete 3 # Remove idea
/capture icebox promote 3 # Promote to capture
Icebox is for:
Unvalidated ideas
Future possibilities
Low-priority improvements
Speculative patterns
Unlike archive (validated knowledge that decayed), icebox holds ideas that never reached warm tier.
/capture decay - Check Stale Items
Find warm-tier items that haven't been accessed in 90+ days:
/capture decay # Show decay candidates
/capture decay --dry-run # Preview what would move
/capture decay --execute # Actually move to archive
/capture decay --days 60 # Custom threshold
Uses decay-check.ts helper. Decay is not automatic - run periodically or with /capture status.
/capture promote - Check Cold Items
Find archived items that should return to warm tier:
/capture promote # Show promotion candidates
/capture promote --execute # Actually move back to warm
Items are promoted when accessed 3+ times while in cold storage.
/capture search - Search Knowledge
Search across all knowledge tiers with tier-aware ranking:
Recent git activity: Keywords from last 7 days of commits
Key files: Clarinet.toml, package.json, wrangler.toml, etc.
Outputs:
Highly relevant items (strong type/keyword match)
May be useful items (partial matches)
Archived items that might need warm loading
Uses context-suggest.ts helper. Run at session start to orient with relevant knowledge.
What It Does
Scans git activity - Commits across repos in ~/dev/ for the date range
Identifies patterns - New techniques, debugging approaches, common scenarios
Generates captures - Structured markdown files with category and confidence
Writes to pending - Saves to ~/logs/captures/pending/ for review
Output Format
Each capture is a markdown file in ~/logs/captures/pending/:
2026-02-01-clarity-try-unwrap.md
File structure:
---category:nugget|pattern|runbook|decisionconfidence:high|medium|lowsource:session|git-diff|pattern-matchrepos: [repo1, repo2]
date:2026-02-01---
# Clarity: Use try! for Error Propagation`try!`unwrapsaresponseandpropagatestheerrortothecaller.Preferover`unwrap!`whenyouwantthecallertohandleerrors.## Example(define-public(transfer(amountuint))(try!(stx-transfer?amounttx-senderrecipient))(oktrue))## ContextObservedinaibtcdev/aibtc-contractsduringsessionreview.Commit:abc123"fix: propagate transfer errors properly"
Review Workflow
Approve
When approved, the capture is:
Moved to ~/logs/captures/approved/
Persisted to the knowledge base at ~/dev/whoabuddy/claude-knowledge/
Destination by category:
Category
Destination
Action
nugget
nuggets/{topic}.md
Append to existing or create new
pattern
patterns/{name}.md
Create new file
runbook
runbook/{task}.md
Create new file
decision
decisions/{nnnn}-{name}.md
Create with next ADR number
Reject
When rejected, the capture is:
Moved to ~/logs/captures/rejected/
Reason added to frontmatter
Rejection reasons:
Duplicate of existing knowledge
Too specific (not reusable)
Needs more validation
Not accurate
Custom reason
Edit
When editing:
Display current content
Ask what to change (content, category, confidence)
Apply edits
Then approve or reject
Categories
Category
Description
Destination
nugget
Quick fact or gotcha
nuggets/{topic}.md
pattern
Recurring solution
patterns/{name}.md
runbook
Procedural workflow
runbook/{task}.md
decision
Architecture choice
decisions/{nnnn}-{name}.md
Confidence Levels
high: Clear, verified, immediately useful
medium: Probably useful, might need refinement
low: Tentative, needs validation
Session Review Logic
The skill analyzes:
Git Commits
# Find today's commits across all reposfor repo in ~/dev/*/*/.git; do
git -C "$(dirname $repo)"log --oneline --since="midnight" --author="$(git config user.email)"done
Changed Files
Look for new techniques or patterns in diffs
Note files that were heavily edited (debugging, refactoring)
Pattern Recognition
Debugging sessions (multiple commits to same file)
New feature work (new files added)
Refactoring (renames, restructuring)
Integration work (config file changes)
Integration
After work sessions: Run /capture to review the day
With /daily: Optionally call capture at end of daily summary
Morning review: /capture review to process pending items
With /daily-brief: Surfaces pending capture count
Workflow
See runbook/knowledge-capture.md in the knowledge base for full workflow documentation.
Files
Location
Purpose
~/logs/captures/pending/
Captures awaiting review
~/logs/captures/approved/
Reviewed and persisted
~/logs/captures/rejected/
Rejected with reason
~/dev/whoabuddy/claude-knowledge/
Knowledge base destination
Knowledge Tiers
Tier
Description
Location
Loaded
Hot
Always loaded
~/.claude/CLAUDE.md Quick Facts
Every session
Warm
On-demand
nuggets/, patterns/, runbook/
When relevant
Cold
Archived
archive/
Rarely, manual
Icebox
Parked ideas
icebox/
Never auto-loaded
Tier Transitions
Warm -> Cold (Decay): Items not accessed in 90 days move to archive
Cold -> Warm (Promotion): Items accessed 3+ times while archived return to warm
Warm -> Icebox: Manual; for ideas not ready for knowledge base
Icebox -> Warm: Manual promotion when idea is validated
Tips
Run at end of work session when context is fresh
Higher confidence for explicit learnings (debugging gotchas)
Lower confidence for inferred patterns (might be one-off)
Captures are proposals - human reviews before persistence
Don't capture sensitive info (credentials, internal URLs)
Review pending captures in morning (with daily-brief) or before EOD
Example Session
Generating Captures
> /capture
Reviewing session work for 2026-02-01...
Found 12 commits across 3 repos:
- aibtcdev/aibtc-contracts: 5 commits (Clarity patterns)
- whoabuddy/moltbook: 4 commits (TypeScript, Hono)
- stacks-network/docs: 3 commits (documentation)
Generated 3 captures:
1. [nugget] Clarity: stacks-block-height vs block-height
Confidence: high
Source: aibtcdev/aibtc-contracts commit "fix: use current block height"
2. [pattern] Hono middleware error handling
Confidence: medium
Source: moltbook pattern observed across 3 files
3. [runbook] Deploying Clarity contracts to testnet
Confidence: low
Source: Inferred from commit sequence
Captures written to ~/logs/captures/pending/
Use /capture review to approve/reject.
Reviewing Captures
> /capture review
Pending captures: 3
---
## Capture 1/3: Clarity: stacks-block-height vs block-height
Category: nugget
Confidence: high
Source: aibtcdev/aibtc-contracts
Content:
Use `stacks-block-height` instead of `block-height` for current block.
`block-height` is legacy and deprecated.
---
Action? [a]pprove / [r]eject / [e]dit / [s]kip
> a
Approved! Persisted to nuggets/clarity.md
---
## Capture 2/3: Hono middleware error handling
...
Helper Scripts
The skill uses TypeScript helpers for stats and candidate generation:
capture-stats.ts
Compute capture statistics for status reporting:
bun ~/.claude/skills/capture/capture-stats.ts # Quick summary
bun ~/.claude/skills/capture/capture-stats.ts --week # Last 7 days detailed
bun ~/.claude/skills/capture/capture-stats.ts --month # Last 30 days detailed
bun ~/.claude/skills/capture/capture-stats.ts --tiers # Include tier stats
bun ~/.claude/skills/capture/capture-stats.ts --json # Output as JSON
bun ~/.claude/skills/capture/access-tracker.ts record <path> # Record an access
bun ~/.claude/skills/capture/access-tracker.ts query <path> # Get access info
bun ~/.claude/skills/capture/access-tracker.ts list # All tracked items
bun ~/.claude/skills/capture/access-tracker.ts list --stale # Items ready for decay
bun ~/.claude/skills/capture/access-tracker.ts list --cold-active # Cold items to promote
Access log stored at ~/dev/whoabuddy/claude-knowledge/.access-log.json.
decay-check.ts
Check for and execute tier transitions:
bun ~/.claude/skills/capture/decay-check.ts # Report decay candidates
bun ~/.claude/skills/capture/decay-check.ts --dry-run # Preview changes
bun ~/.claude/skills/capture/decay-check.ts --execute # Move files to archive
bun ~/.claude/skills/capture/decay-check.ts --days 60 # Custom threshold
bun ~/.claude/skills/capture/decay-check.ts --promote # Check promotion candidates
bun ~/.claude/skills/capture/decay-check.ts --promote --execute # Execute promotions
capture-candidates.ts
Auto-generate capture candidates from git activity:
bun ~/.claude/skills/capture/capture-candidates.ts # Today's activity
bun ~/.claude/skills/capture/capture-candidates.ts 2026-02-01 # Specific date
bun ~/.claude/skills/capture/capture-candidates.ts --week # Last 7 days
bun ~/.claude/skills/capture/capture-candidates.ts --json # Output as JSON
Pattern matching:
Fix commits -> high confidence nuggets
Same file edited 3+ times -> debugging session nuggets
bun ~/.claude/skills/capture/knowledge-search.ts "clarity"# Search all tiers
bun ~/.claude/skills/capture/knowledge-search.ts "stx" --tier warm # Filter by tier
bun ~/.claude/skills/capture/knowledge-search.ts "api" --category patterns # Filter by category
bun ~/.claude/skills/capture/knowledge-search.ts --rebuild-index # Rebuild search index
bun ~/.claude/skills/capture/knowledge-search.ts --json # Output as JSON
Search index stored at ~/dev/whoabuddy/claude-knowledge/.search-index.json.
Index auto-rebuilds if older than 1 hour.
context-suggest.ts
Context-aware knowledge suggestions based on working directory:
bun ~/.claude/skills/capture/context-suggest.ts # Current directory
bun ~/.claude/skills/capture/context-suggest.ts ~/dev/org/repo # Specific repo
bun ~/.claude/skills/capture/context-suggest.ts --json # Output as JSON
Detects project types and surfaces relevant knowledge from all tiers.
Daily Workflow Integration
Morning (with /daily-brief)
The daily-brief skill surfaces:
Pending capture count
Recently approved captures (last 7 days)
Prompt to run /capture review if pending > 0
Evening (with /daily)
After generating daily summary, optionally run capture:
/daily && /capture # Generate summary, then scan for captures
/daily --capture # Integrated capture at end (optional)
Weekly Review
Use stats to track capture health:
/capture status --week # See approval rate, trends, categories
