secondbrain-freshness

name	secondbrain-freshness
description	This skill should be used when the user asks for "freshness check", "freshness report", "what needs attention", "stale items", "review backlog", or mentions wanting to see what secondbrain content needs review or updating.

Freshness Report

Generate a comprehensive freshness report for all secondbrain entities.

Prerequisites

Verify secondbrain is initialized:

1. Check for .claude/data/config.yaml
2. 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:

1. Load all records
2. Check date fields (created, date, date_updated)
3. Compare against freshness threshold
4. 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

1. **ADR-0003:** 95 days in "proposed" status
   - Action: Review and move to admitted/rejected

2. **ADR-0007:** 78 days in "draft" status
   - Action: Complete draft or cancel

3. **TASK-0012:** 45 days in progress
   - Action: Check if blocked, update status

4. **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

1. Run weekly — Set calendar reminder for freshness reviews
2. Address critical first — Focus on oldest items
3. Archive liberally — Better to archive than ignore
4. Update thresholds — Adjust based on your workflow pace
5. Check after sprints — Good time to clean up stale items