small-scripts/specs/unreflected-logs.spec.md

unreflected-logs

Purpose

Scan project directories for session logs that have not yet been processed by /reflect-logs, showing a per-project summary.

Usage

unreflected-logs [OPTIONS] [DIRECTORY]

Arguments

Argument	Default	Description
DIRECTORY	. (current directory)	Root directory to scan

Flags

Flag	Short	Description
--dryrun	-n	List discovered projects without checking log status
--help	-h	Show usage information

Behaviour

1. Discovery phase: Walk DIRECTORY recursively, looking for directories that contain a memory/log/ subdirectory. Each such directory is a "project". Stop descending into memory/ and node_modules/ directories.

2. Check phase: For each discovered project: a. List all *.md files in memory/log/. b. Read .reflection-state.json from the project root (sibling to memory/). If it doesn't exist, all logs are unreflected. c. A log file is "reflected" if its path (relative, as log/<filename>) appears as a key in the processed object of the reflection state file. d. Count reflected and unreflected logs.

3. Report phase: Print a summary:

   • Projects with unreflected logs get a section showing:
     • Project path (relative to DIRECTORY)
     • Count: N unreflected / M total logs
     • List of unreflected log filenames
   • Projects with all logs reflected are listed in a summary line (count only).
   • Total line at the end: N unreflected logs across M projects

4. Exit code:

   • 0 — no unreflected logs found anywhere
   • 1 — at least one unreflected log exists

Dryrun Behaviour

When --dryrun is passed:

• Perform the discovery phase only
• Print each discovered project path (relative to DIRECTORY), one per line
• Prefix output with [dryrun] Would check N projects:
• Exit code is always 0

Edge Cases

Scenario	Handling
No projects with memory/log/ found	Print "No projects with session logs found in " and exit 0
memory/log/ exists but is empty	Skip project (no logs to report)
.reflection-state.json missing	Treat all logs as unreflected
.reflection-state.json malformed	Warn to stderr, treat all logs as unreflected
processed key missing from state	Treat all logs as unreflected
Permission denied on subdirectory	Skip with warning to stderr, continue scanning

Examples

All reflected

Scanned 4 projects in ~/dev/claude

✓ All logs reflected across 4 projects.

Some unreflected

Scanned 4 projects in ~/dev/claude

── projects/claude-foundations ──
   1 unreflected / 4 total logs
   - 2026-03-15.225345.md

── small-scripts ──
   2 unreflected / 3 total logs
   - 2026-03-14.091200.md
   - 2026-03-15.142300.md

✓ 2 projects have all logs reflected.

Total: 3 unreflected logs across 2 projects

Dryrun

[dryrun] Would check 4 projects:
  ~/dev/claude/projects/claude-foundations
  ~/dev/claude/projects/cluster-bootstrap
  ~/dev/claude/small-scripts
  ~/dev/claude/octopus/customer-issue-sync