3c77f85403
- /log: end-of-session capture of decisions, gotchas, open questions to memory/log/ - /reflect-logs: processes session logs into topic memory files with staleness detection - /distill-best-practices: cross-project best practices extraction with interactive proposals - README.md: updated skill table with all three new skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
5.0 KiB
Markdown
122 lines
5.0 KiB
Markdown
---
|
|
name: reflect-logs
|
|
description: >
|
|
Process session logs into structured memory. Reads unprocessed logs from memory/log/,
|
|
extracts lessons into topic memory files (gotchas, process-lessons, decisions, etc.),
|
|
updates MEMORY.md index, and flags stale entries. Run periodically or after several sessions.
|
|
allowed-tools: Read, Edit, Write, Glob, Grep, Bash(md5sum *), Bash(ls *), Bash(cat *), Bash(date *), Bash(find *), Bash(git log *), Bash(git diff *), Bash(head *)
|
|
---
|
|
|
|
# Reflect Logs Skill
|
|
|
|
You are processing session logs into structured, topic-based memory files.
|
|
|
|
## Pre-gathered context
|
|
|
|
### Reflection state
|
|
!`cat .reflection-state.json 2>/dev/null || echo "{}"`
|
|
|
|
### Available log files
|
|
!`ls -1t memory/log/ 2>/dev/null || echo "No logs found"`
|
|
|
|
### Current MEMORY.md index
|
|
!`cat MEMORY.md 2>/dev/null || echo "No MEMORY.md found"`
|
|
|
|
### Existing memory topic files
|
|
!`ls -1 memory/ 2>/dev/null || echo "No memory directory"`
|
|
|
|
### Settings
|
|
!`cat ~/dev/claude/projects/claude-foundations/settings.yaml 2>/dev/null || echo "No settings file found"`
|
|
|
|
### Recent git log (for staleness detection)
|
|
!`git log --oneline -30 2>/dev/null || echo "Not a git repo"`
|
|
|
|
## Instructions
|
|
|
|
### Step 1: Identify unprocessed logs
|
|
|
|
Compare `memory/log/` contents against `.reflection-state.json`:
|
|
- A log is **new** if its filename is not in the `processed` map
|
|
- A log is **changed** if its filename exists but the md5sum differs from the stored hash
|
|
- Respect `max_logs_per_run` from settings (default: 10) — process oldest first
|
|
|
|
To compute hashes, run `md5sum memory/log/<filename>` for each file and compare against the stored values.
|
|
|
|
If there are no unprocessed logs, say so and stop.
|
|
|
|
### Step 2: Read and categorise
|
|
|
|
Read each unprocessed log file. Group the extracted content by destination:
|
|
|
|
**Routing rules:**
|
|
- Gotchas tagged `[topic]` → `memory/gotchas-<topic>.md` (e.g., `[k8s]` → `memory/gotchas-k8s.md`)
|
|
- Decisions → `memory/decisions.md`
|
|
- Process Notes → `memory/process-lessons.md`
|
|
- Key Context that represents a stable pattern → `memory/process-lessons.md` or a new topic file
|
|
- Open Questions that were resolved across sessions → note the resolution, don't carry forward
|
|
|
|
If a `[topic]` tag doesn't match any existing gotchas file, create a new `memory/gotchas-<topic>.md` file following the format of existing ones (title heading, individual gotcha subheadings with 2-4 line explanations).
|
|
|
|
### Step 3: Update memory files
|
|
|
|
For each destination file:
|
|
|
|
1. **Read** the existing content using the Read tool
|
|
2. **Deduplicate**: Do NOT add entries that already exist in substance, even if worded differently. Check for semantic overlap, not just string matching.
|
|
3. **Append** new entries in the same style as existing content:
|
|
- Gotcha files: `## Heading` with 2-4 lines of explanation including symptom and fix
|
|
- Process lessons: Imperative rule format ("Always X before Y", "Never assume Z")
|
|
- Decisions: `## Heading` with rationale paragraph
|
|
4. If creating a new topic file, include a top-level `# <Topic> Gotchas` heading and make it self-contained
|
|
|
|
### Step 4: Staleness detection
|
|
|
|
Scan existing entries in the memory topic files you touched (not all files — only the ones relevant to this run):
|
|
|
|
- **Version-based**: If an entry mentions a specific version (e.g., "Cilium 1.19.1", "chart v39.x"), check `git log` for version bumps past that number. If found, add `<!-- STALE? Project has upgraded past <version> -->` as a comment after the entry.
|
|
- **Fix-based**: If an entry describes a workaround for a bug, grep recent log files and git commits for keywords suggesting the bug was fixed upstream. If found, flag it.
|
|
- **Automation-based**: If a process lesson describes a manual sequence, check if a script in `scripts/` now handles it. If so, flag or update the entry.
|
|
|
|
Print all flagged items in the summary so the user can confirm removal.
|
|
|
|
### Step 5: Update MEMORY.md index
|
|
|
|
If any new topic files were created:
|
|
- Add a one-line entry to the appropriate section of MEMORY.md
|
|
- Follow the existing format: `- [Title](memory/filename.md) -- Description`
|
|
- Make the description specific and searchable — it's used to decide what to read
|
|
|
|
### Step 6: Update reflection state
|
|
|
|
Write `.reflection-state.json` with updated hashes:
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"last_run": "<ISO-8601 timestamp>",
|
|
"processed": {
|
|
"log/YYYY-MM-DD.HHMMSS.md": "<md5hash>",
|
|
...existing entries...
|
|
}
|
|
}
|
|
```
|
|
|
|
Preserve existing entries. Add new ones for the logs just processed. Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp.
|
|
|
|
### Step 7: Summary
|
|
|
|
Print:
|
|
- Number of logs processed
|
|
- New entries added (listed by destination file)
|
|
- Stale entries flagged (with the reason)
|
|
- Any new topic files created
|
|
- Any open questions resolved
|
|
|
|
## Quality checks
|
|
|
|
- Every new entry must be **actionable or informative** — no filler
|
|
- Gotchas include **symptom AND fix**, not just "X was tricky"
|
|
- Process lessons are phrased as **rules** ("Always X before Y")
|
|
- New entries match the **formatting style** of existing entries in the target file
|
|
- Deduplication is by **substance**, not exact string match
|