Freshness Report
Generate a comprehensive freshness report for all secondbrain entities.
Prerequisites
Verify secondbrain is initialized:
-
Check for .claude/data/config.yaml
-
If not found, indicate no secondbrain project found
Workflow
Step 1: Load Configuration
Read .claude/data/config.yaml to get:
-
All enabled entities
-
Freshness thresholds per entity
-
Monthly partitioning settings
Step 2: Analyze Each Entity
For each enabled entity:
-
Load all records
-
Check date fields (created, date, date_updated)
-
Compare against freshness threshold
-
Categorize by staleness level:
-
Critical (2x threshold): Needs immediate attention
-
Stale (1x threshold): Should be reviewed
-
Warning (0.75x threshold): Approaching staleness
Step 3: Generate Report
Format by entity and urgency:
Freshness Report
Generated: 2026-01-15 10:30
Summary
| Entity | Critical | Stale | Warning | OK |
|---|---|---|---|---|
| ADRs | 2 | 5 | 3 | 12 |
| Tasks | 0 | 8 | 4 | 15 |
| Notes | 1 | 3 | 6 | 25 |
| Discussions | 0 | 2 | 1 | 10 |
Total needing attention: 30 items
Critical (Needs Immediate Attention)
ADRs (2 items)
| ID | Title | Status | Age |
|---|---|---|---|
| ADR-0003 | API Gateway Selection | proposed | 95 days |
| ADR-0007 | Database Migration | draft | 78 days |
Notes (1 item)
| ID | Title | Age |
|---|---|---|
| 2025-10-01-legacy-system | Legacy System Overview | 106 days |
Stale (Should Review)
Tasks (8 items)
| ID | Title | Status | Priority | Age |
|---|---|---|---|---|
| TASK-0012 | Update documentation | in_progress | medium | 45 days |
| TASK-0015 | Fix login bug | todo | high | 42 days |
| ... |
Recommended Actions
-
ADR-0003: 95 days in "proposed" status
- Action: Review and move to admitted/rejected
-
ADR-0007: 78 days in "draft" status
- Action: Complete draft or cancel
-
TASK-0012: 45 days in progress
- Action: Check if blocked, update status
-
2025-10-01-legacy-system: 106 days old note
- Action: Archive or update content
Step 4: Offer Remediation
For each critical/stale item, offer specific actions:
-
Draft ADRs: Complete or cancel
-
Proposed ADRs: Review and decide
-
In-progress tasks: Check if blocked
-
Old notes: Archive or refresh
-
Stale discussions: Mark resolved or schedule follow-up
Step 5: Update Last Check
Update .claude/data/config.yaml :
meta: last_freshness_check: 2026-01-15T10:30:00
Staleness Thresholds
Default thresholds (configurable per entity):
Entity Default Critical
ADRs 30 days 60 days
Tasks 14 days 28 days
Notes 30 days 60 days
Discussions 7 days 14 days
Status Exceptions
Skip items with terminal statuses:
-
ADRs: implemented, tested, rejected, canceled
-
Tasks: done, completed, canceled
-
Notes: archived
-
Discussions: archived
Output Formats
Summary Only
Freshness Summary
- Critical: 3 items need immediate attention
- Stale: 18 items should be reviewed
- Warning: 13 items approaching staleness
Run with --detailed for full breakdown.
Full Report
Complete breakdown with tables and recommendations (default).
JSON Export
{ "generated": "2026-01-15T10:30:00", "summary": { "critical": 3, "stale": 18, "warning": 13, "ok": 62 }, "by_entity": { "adrs": { "critical": 2, "stale": 5, ... }, ... }, "items": [...] }
Tips
-
Run weekly — Set calendar reminder for freshness reviews
-
Address critical first — Focus on oldest items
-
Archive liberally — Better to archive than ignore
-
Update thresholds — Adjust based on your workflow pace
-
Check after sprints — Good time to clean up stale items