ADR-072: Recent Files Command with Diff Analysis
Status
Accepted | January 15, 2026
Context
In large monorepo projects with many submodules (74+ in coditect-rollout-master), developers need to quickly understand:
- What files changed recently? - Session context recovery, debugging
- What actually changed in those files? - Code review, impact analysis
- Can we feed changes to MoE review panels? - Automated quality assurance
Existing tools had limitations:
git statusdoesn't show files in submodules from parent repofindrequires manual time filtering and excludes submodules by default- No integrated diff analysis for time-based file sets
- No export format for MoE agent consumption
Decision
Implement /recent command with three distinct capabilities:
1. File Discovery (Core)
┌─────────────────────────────────────────────────────────────────────────────┐
│ /recent File Discovery │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ INPUT: Time filter, type filter, submodule filter │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ find + stat │───▶│ Sort by mtime │───▶│ Display with colors │ │
│ │ (batched) │ │ │ │ (submodule awareness) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │
│ │
│ OUTPUT: File list with modification times, sizes, color-coded paths │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
2. JSON Export
┌─────────────────────────────────────────────────────────────────────────────┐
│ /recent --export │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ OUTPUT: ~/.coditect/recently-modified/ │
│ YYYY-MM-DDTHH-MM-SS_<time>_<submodule-mode>[_type-EXT].json │
│ │
│ { │
│ "export_metadata": { │
│ "exported_at": "2026-01-15T06:08:02Z", │
│ "time_filter": "today", │
│ "include_submodules": true, │
│ "working_directory": "/path/to/project" │
│ }, │
│ "files": [ │
│ { │
│ "filename": "recent.sh", │
│ "path": "submodules/core/coditect-core/scripts/recent.sh", │
│ "submodule": "core/coditect-core", │
│ "size_bytes": 29000, │
│ "created": "2026-01-15T01:23:39-03:00", │
│ "modified": "2026-01-15T04:23:20-03:00" │
│ } │
│ ] │
│ } │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
3. Diff Analysis
┌─────────────────────────────────────────────────────────────────────────────┐
│ /recent --diff Modes │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ MODE 1: --diff (Full diffs) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ For each file: │ │
│ │ 1. Detect git directory (handles submodules) │ │
│ │ 2. Check for uncommitted changes → git diff HEAD │ │
│ │ 3. If clean → show last commit diff with git show │ │
│ │ 4. Color-code output (+green, -red, @@cyan) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ MODE 2: --diff-stat (Statistics only) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ File +Lines -Lines Status │ │
│ │ scripts/recent.sh +450 -12 uncommitted│ │
│ │ commands/recent.md +85 -30 2 hours ago│ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ MODE 3: --diff-review (MoE export) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Output: ~/.coditect/recently-modified/diffs/ │ │
│ │ YYYY-MM-DDTHH-MM-SS_<time>_diff-review.md │ │
│ │ │ │
│ │ Contains: │ │
│ │ - Summary statistics table │ │
│ │ - Detailed diffs in markdown code blocks │ │
│ │ - MoE review instructions with agent recommendations │ │
│ │ - Suggested invocation command │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ MODE 4: --include-new (New file content) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ For untracked (new) files, shows full content as additions: │ │
│ │ │ │
│ │ # new-file.md (NEW FILE - 45 lines) │ │
│ │ --- /dev/null │ │
│ │ +++ b/new-file.md │ │
│ │ @@ -0,0 +1,45 @@ │ │
│ │ +# New Feature... │ │
│ │ │ │
│ │ With --diff-stat: shows line count with "NEW FILE" status │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
4. Absolute Date/Time Range Selection
┌─────────────────────────────────────────────────────────────────────────────┐
│ /recent --date --from --to │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ INPUT: --date YYYY-MM-DD [--from HH:MM] [--to HH:MM] │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ Create temp │───▶│ touch -t to │───▶│ find -newer START │ │
│ │ reference │ │ set timestamps │ │ ! -newer END │ │
│ │ files │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │
│ │
│ DEFAULTS: │
│ --from: 00:00 (start of day) │
│ --to: 23:59 (end of day) │
│ │
│ OUTPUT: Files modified within the specified date/time window │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Implementation: Uses touch -t to create temporary reference files with exact timestamps, then find -newer ref_start ! -newer ref_end to filter files within the range.
Submodule-Aware Git Operations
Key architectural decision: Git commands must run in the correct repository context.
┌─────────────────────────────────────────────────────────────────────────────┐
│ Submodule Git Resolution │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ File: submodules/core/coditect-core/scripts/recent.sh │
│ │
│ ┌───────────────────┐ │
│ │ get_git_dir() │ Walk up directory tree to find .git │
│ │ Returns: │ → submodules/core/coditect-core │
│ └───────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ get_relative_path│ Strip git_dir prefix │
│ │ Returns: │ → scripts/recent.sh │
│ └───────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ git -C $git_dir │ Run git in correct context │
│ │ diff HEAD -- │ → shows changes relative to submodule │
│ │ $relative_path │ │
│ └───────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Command Interface
# Basic usage
/recent # All files from past 7 days
/recent --today # Files modified today
/recent --hours 4 # Last 4 hours
/recent 20 # Limit to 20 files
# Absolute date/time range
/recent --date 2026-01-14 # All files from Jan 14
/recent --date 2026-01-14 --from 09:00 # Jan 14, 9am onwards
/recent --date 2026-01-14 --from 09:00 --to 17:00 # Jan 14, 9am-5pm
/recent --date 2026-01-14 --from 14:00 --to 18:00 --diff # With diffs
# Submodule filtering
/recent --no-submodules # Exclude submodules
/recent --submodules-only # Only submodule changes
# Type filtering
/recent --type md # Only markdown files
/recent --type "ts,tsx" # TypeScript files
# Export
/recent --today --export # JSON export
# Diff analysis
/recent --hours 4 --diff # Full diffs
/recent --today --diff-stat # Statistics only
/recent --hours 24 --diff-review # MoE export
/recent --diff --include-new # Include new file content
# Interactive
/recent -i # Guided menu
MoE Integration
The --diff-review output is designed for consumption by MoE agents:
| Agent | Analysis Focus |
|---|---|
orchestrator-code-review | ADR compliance, multi-agent coordination |
code-reviewer | Quality, security, performance |
llm-judge | Before/after quality scoring |
quality-gate-enforcer | Evidence-based validation |
cloud-architect-code-reviewer | Infrastructure changes |
Suggested Workflow
# 1. Export changes for review
/recent --hours 24 --diff-review
# 2. Invoke MoE review panel
/agent orchestrator-code-review "Review the changes in ~/.coditect/recently-modified/diffs/2026-01-15T06-19-49_24hours_diff-review.md"
Default Behaviors
| Setting | Default | Rationale |
|---|---|---|
| Include submodules | Yes | Most work happens in submodules in monorepos |
| Time window | 7 days | Balance between coverage and performance |
| File limit | None | Show all files for time window |
| Diff mode | Off | Performance - diffs are slower |
Performance Considerations
File Discovery
- Uses
find -print0 | xargs -0 statfor batched operations - Avoids per-file stat calls in loops
- Excludes
.git,node_modules,__pycache__,.venv
Diff Analysis
- Git operations are I/O intensive
- Submodule resolution adds overhead
- Recommend limiting files when using
--diff:/recent --hours 4 --diff 20 # Limit to 20 files
File Structure
~/.coditect/
├── scripts/
│ └── recent.sh # Main script (v2.4.0)
├── commands/
│ └── recent.md # Command documentation
└── recently-modified/
├── 2026-01-15T06-08-02_today_with-submodules.json
├── 2026-01-14_09-00-17-00_with-submodules.json # Date range export
└── diffs/
└── 2026-01-15T06-19-49_24hours_diff-review.md
Future Considerations
Potential Enhancements
- Automatic daily export - launchd service for midnight exports
- Git integration - Pre-flight bottom-up commit before diff analysis
- Semantic diff - AST-aware diffs for code files
- Change impact scoring - Estimate blast radius of changes
Integration Points
| System | Integration |
|---|---|
/cx | Feed recent files to context extraction |
/git-sync | Bottom-up commit before diff |
/session-log | Include recent files in session summary |
| MoE Panel | Automated review of time-based changes |
Consequences
Positive
- Fast file discovery across 74+ submodules
- Time-based change analysis without manual git commands
- MoE integration for automated code review
- JSON export for downstream processing
Negative
- Diff analysis is slower than simple file listing
- Submodule git resolution adds complexity
Neutral
- Requires git for diff features (graceful fallback for non-git files)
- Output can be large for active development periods
References
Decision Made By: CODITECT Architecture Team
Implementation: ~/.coditect/scripts/recent.sh v2.4.0