| name | proactive-system-scan |
| version | 1.0.0 |
| category | devops |
| description | Multi-faceted system scan to discover work, issues, and improvement opportunities when the user gives an open-ended request like "find work" or "look for things that need doing." Runs doctor, cron health, git status, system health, and governance checks in parallel. |
| author | Hermes Cortex |
| license | MIT |
| platforms | ["linux","macos"] |
Proactive System Scan — Finding Work Without a Task
When the user asks you to "find work," "look for issues," or "what needs
doing," don't wait for a specific task — survey the system across multiple
dimensions and report what you find.
This is different from survey-before-action (check before modifying)
and cortex-preflight (check before a known change). This is a discovery
scan to identify opportunities when no change is planned yet.
The Scan Sequence
Run these checks in parallel (no data dependencies between them):
1. Doctor status
python3 ~/hermes-cortex/ops/scripts/manage/cortex-doctor.py --quiet
Signals: ❌ must-fix, ⚠️ should-fix, ℹ️ informational.
Common doctor failures and fixes:
| Failure | Root cause | Fix |
|---|
❌ AGENTS.md (<repo>) | check_dev_repo_agents(). File mtime >1 day older than latest git HEAD timestamp | git diff HEAD~10..HEAD --name-only, merge new patterns, touch AGENTS.md |
⚠️ Symlinks | Broken .governance-generic.json → stale session lock | rm <broken-symlink> |
❌ Repo sync | Local behind origin/main | git pull --rebase |
❌ Hook: pre-commit (content) / ❌ Checksum: pre-commit | .hermes-cortex/hooks/pre-commit and ops/scripts/pre-commit-score out of sync | cp ops/scripts/pre-commit-score .hermes-cortex/hooks/pre-commit && cp ops/scripts/pre-commit-score ~/.hermes-cortex/hooks/pre-commit |
❌ Deploy sync | Repo ahead of deployed state after push | Resolves on next automated cortex-update (nightly cron) or run cortex-update.sh (close governance lock first — the deploy cleans it) |
2. Cron health
cronjob(action='list')
Check each job for: last_status not "ok", paused without reason, stale
next_run_at, or missing expected jobs (compare against install script
uninstall arrays).
3. Git status
cd ~/hermes-cortex && git status --short
git log --oneline origin/main..HEAD
4. System health
df -h / | tail -1
free -h | head -2
uptime
5. Governance health
Use mcp__loop_governance__cycle_stats() — look for PENDING cycles
(unreviewed), high repeat counts on a task (stuck loops), or low
feedback rates.
6. Bus queues (orchestrator only)
Check for stuck messages in bus queues (via PGMQ tooling or bus script
inspection).
Reporting
Organize by severity:
🔴 Must Fix — <doctor ❌ failures or critical issues>
🟡 Should Fix — <doctor ⚠️ warnings, minor drift>
🟢 Already Good — <key systems confirmed healthy>
ℹ️ Notes — <observations, trends, work-in-progress>
## Action Taken
- <what was already fixed>
- <what needs user input>
When to Use
- User says "find work" / "look for issues" / "what needs doing"
- Session starts with a vague/open-ended request
- Before starting a new project phase — know the baseline
- After
git pull or cortex-update — verify nothing broke
Anti-Patterns
- ❌ Scanning only one subsystem — misses systemic issues
- ❌ Reporting without offering to fix — be proactive
- ❌ Skipping because "everything was fine yesterday"
- ❌ Fixing one thing and stopping when others remain
- ❌ Not running the doctor — it catches what you'd miss manually
