[plan] Improve fsnotify file watching implementation

[github-actions]

Overview

This tracking issue covers improvements to the fsnotify-based file watching functionality in the compile --watch command, based on the analysis from the Go Fan report.

Source: Discussion #5175

The current implementation is solid (8.5/10 rating) but has opportunities for enhancement:

• Reducing event noise (Chmod filtering)
• Better error handling and user feedback
• Platform-specific optimizations
• Handling burst events more gracefully

Planned Tasks

The improvements are organized by priority:

Priority 1: Quick Wins

1. Filter out Chmod events to reduce processing noise
2. Improve subdirectory watch error handling with better logging
3. Document FSNOTIFY_DEBUG environment variable for troubleshooting

Priority 2: Feature Enhancements

4. Handle event overflow errors with user-friendly messages
5. Add platform-specific optimizations (buffered watcher, Windows buffer size)

Context

• Current implementation: pkg/cli/compile_command.go:753-931
• Module version: fsnotify v1.9.0
• Assessment: Well-architected, production-ready, but room for polish

References

• Go Fan Report: Discussion [go-fan] Go Module Review: fsnotify #5175
• Module docs: https://github.com/fsnotify/fsnotify
• Spec file: specs/mods/fsnotify.md

AI generated by Plan Command for discussion #5175