heavy-duty-watcher

Org-wide GitHub review agent for the heavy-duty organization.

Runs as bot grok-bot-andresmgsl. Every 15 minutes it discovers open Issues/PRs where this bot is assignee or requested reviewer across all heavy-duty/* repos, reads the full discussion, and posts structured reviews until it agrees (Approve) or still has blockers (Request changes).

Not a drive-by bot. No unsolicited comments. No merge/close/reassign unless an operator asks.

---

Features

• Org-wide scope — one watcher for every repo under heavy-duty
• Strict collaboration rules — clear Verdict/Status, specific, non-redundant, blockers vs nits
• Stateful de-dupe — tracks per-item head SHA and last action (owner/repo#pr:N)
• Dual durability — Grok durable schedulers and local tmux loops
• Reboot recovery — scripts/restore.sh rebuilds tmux + resumes the agent
• Hourly health watchdog — verifies poll loop, gh auth, freshness; self-heals

---

Quick start

git clone https://github.com/grok-bot-andresmgsl/heavy-duty-watcher.git
cd heavy-duty-watcher
gh auth status          # bot account with org access
./scripts/install-live.sh
./scripts/restore.sh    # after reboot: always this

Arm durable schedulers from a live Grok session using prompts in docs/SCHEDULER_PROMPTS.md.

---

Repository layout

heavy-duty-watcher/
├── README.md                 ← you are here
├── POLL_INSTRUCTIONS.md      ← authoritative review rules (read every cycle)
├── config/
│   ├── state.template.json
│   └── watcher.env.example
├── scripts/
│   ├── discover.sh           ← org-wide actionable list
│   ├── poll-once.sh          ← one headless poll (Grok)
│   ├── poll-loop.sh          ← every 15m
│   ├── health-check.sh
│   ├── health-loop.sh        ← every 1h + self-heal
│   ├── restore.sh            ← reboot recovery (tmux)
│   └── install-live.sh       ← deploy under ~/heavy-duty-watcher
├── docs/
│   ├── ARCHITECTURE.md
│   ├── OPERATIONS.md
│   ├── SCHEDULER_PROMPTS.md
│   └── REVIEW_PLAYBOOK.md
└── logs/                     ← runtime (gitignored)

---

How a poll works

discover (org search)
   → for each match
        read ALL comments + reviews + diff + checks
        compare head SHA / prior bot comments (state.json)
        if material change:
            post Verdict: Request changes | Comment | Approve
        else:
            silent
   → update state.json + logs/poll.log

Full rules: POLL_INSTRUCTIONS.md.

---

Documentation map

Doc	Audience
POLL_INSTRUCTIONS.md	Agent — must follow every cycle
docs/ARCHITECTURE.md	Design / durability model
docs/OPERATIONS.md	Humans operating the watcher
docs/SCHEDULER_PROMPTS.md	Copy-paste durable task prompts
docs/REVIEW_PLAYBOOK.md	Review style examples

---

After reboot

~/heavy-duty-watcher/scripts/restore.sh

Creates/attaches tmux session heavy-duty-watcher with:

Window	Role
grok	Interactive agent (resume session when possible)
poll-loop	Headless 15m polls
health-loop	Hourly health + self-heal
tools	Manual shell

---

Safety

• Only comments when assigned or review-requested
• Never merges, closes, force-pushes, or reassigns by default
• Secrets are not stored in this repo — use gh auth on the host

---

License

MIT — see LICENSE.