Summary
specsmith watch falls back to polling mode (5s interval) when watchdog is not installed, printing:
watchdog not installed — using polling mode. For faster detection: pip install watchdog
For projects that use specsmith watch in their governance workflow, this means unnecessary CPU usage and slower drift detection.
Suggestion
Consider one or more of these approaches, in order of preference for project architecture:
1. Include watchdog in specsmith's own dependencies (recommended)
Since specsmith watch is a first-class command, watchdog should be a runtime dependency of specsmith itself rather than an optional suggestion. Most CI and developer environments can accommodate it.
2. Add watchdog to generated [dev] extras in docs/SPECSMITH.yml scaffold
When specsmith initialises a new project (or syncs governance), it could add watchdog>=4.0 to the project's [dev] optional dependencies automatically — making it part of the standard pip install -e .[dev] flow.
3. Upgrade the suggestion message
At minimum, change the warning to be more actionable — e.g. suggest adding it to pyproject.toml [dev] extras rather than just a bare pip install, so it persists across environments.
Context
Encountered while using specsmith watch in a governed Python project (ctt-neural). We resolved it by manually adding watchdog>=4.0 to [project.optional-dependencies].dev in pyproject.toml, but this is something every project using specsmith governance would need to do independently.
Environment
- specsmith 0.11.5
- Python 3.12, Windows 11 / PowerShell 7.5.5
watchdog 6.0.0 (once installed, watch works correctly with native OS watchers)
Summary
specsmith watchfalls back to polling mode (5s interval) whenwatchdogis not installed, printing:For projects that use
specsmith watchin their governance workflow, this means unnecessary CPU usage and slower drift detection.Suggestion
Consider one or more of these approaches, in order of preference for project architecture:
1. Include
watchdogin specsmith's own dependencies (recommended)Since
specsmith watchis a first-class command,watchdogshould be a runtime dependency of specsmith itself rather than an optional suggestion. Most CI and developer environments can accommodate it.2. Add
watchdogto generated[dev]extras indocs/SPECSMITH.ymlscaffoldWhen specsmith initialises a new project (or syncs governance), it could add
watchdog>=4.0to the project's[dev]optional dependencies automatically — making it part of the standardpip install -e .[dev]flow.3. Upgrade the suggestion message
At minimum, change the warning to be more actionable — e.g. suggest adding it to
pyproject.toml [dev]extras rather than just a bare pip install, so it persists across environments.Context
Encountered while using
specsmith watchin a governed Python project (ctt-neural). We resolved it by manually addingwatchdog>=4.0to[project.optional-dependencies].devinpyproject.toml, but this is something every project using specsmith governance would need to do independently.Environment
watchdog6.0.0 (once installed, watch works correctly with native OS watchers)