# Reconsider Stats Output Default Behavior for Less Noisy UX

* **Task ID:** stats-output-default-behavior-review_59.stevejs.md
* **Reviewer:** stevejs
* **Area:** code
* **Motivation (WHY):**
  - Current implementation always generates stats files, even when users don't explicitly request them
  - This creates file system noise for users who just want to process files without stats
  - While PRD F-8 requires stats functionality, it doesn't specify that stats must be generated by default
  - Many CLI tools provide optional output features rather than always-on behavior
  - Consider user experience: most users may not need detailed performance stats for routine processing

* **Acceptance Criteria:**
  1. Evaluate whether stats generation should be opt-in rather than always-on
  2. Consider alternative approaches that balance PRD compliance with user experience
  3. Analyze impact on existing workflows and automation scripts
  4. Propose solution that maintains PRD F-8 compliance while reducing unwanted file generation
  5. Ensure any changes don't break existing integration tests or expected behavior

* **Options to Consider:**
  - **Option A (Current)**: Always generate stats, --stats-out controls location
  - **Option B**: Only generate stats when --stats-out is explicitly provided
  - **Option C**: Add separate --no-stats flag to disable default stats generation
  - **Option D**: Use different default (e.g., write to /tmp or skip file creation, just log stats)

* **Investigation Required:**
  1. Review PRD F-8 requirements for strict interpretation vs. implementation flexibility
  2. Survey similar CLI tools to understand common patterns for optional output
  3. Assess whether stats output is primarily for debugging vs. production monitoring
  4. Consider if stats should be part of --no-progress flag or separate concern
  5. Evaluate impact on scripts that may depend on run_stats.json always being created

* **Deliverables:**
  - Analysis of current behavior vs. user expectations
  - Recommendation for improved default behavior
  - Implementation plan if changes are warranted
  - Updated tests to reflect any behavioral changes
  - Documentation updates for changed behavior

* **References:**
  - PRD F-8: Generate per-file stats and aggregate into run_stats.json
  - Current implementation in src/main.rs stats generation logic
  - CLI UX patterns in similar tools (ripgrep, fd, etc.)

## Pre-commit checklist:
- [ ] All deliverables implemented
- [ ] Tests passing (`cargo test`)
- [ ] Claims validated (user experience analysis completed)
- [ ] Documentation updated if needed
- [ ] **ZERO WARNINGS**: `./scripts/validate_warning_free.sh` passes completely
- [ ] **Behavior analysis**: Impact on existing workflows evaluated