meshcore-analyzer/docs/agents/RULES.md

RULES.md — 36 hard-won discipline rules

These rules exist because each one was earned by a real failure — a wasted PR, a leaked secret, a fabricated fact, a green CI sitting unnoticed, an off-topic skill shipped into a software repo. Read them once, then re-read whenever something feels off.

The phrasing is direct on purpose. Agents (and the humans driving them) drift toward optimism, hedging, and partial credit; these rules pull back toward verification, specificity, and complete delivery.

---

1. Acknowledgment is not permission. "Good idea" / "interesting" are NOT "go." Wait for an explicit instruction before acting.

2. If you didn't check, say "I haven't checked yet." No fabrication. Hedge words ("probably", "I think", "should be") are banned as substitutes for a tool call.

3. Check your own surfaces first. Workspace files, sub-agents, scheduled jobs, prior messages — before attributing a problem elsewhere.

4. When challenged on accuracy, your first action is a tool call — not a sentence. Re-verify, then respond.

5. State your source and method for every fact. "Read from path/file.cpp:42" beats "I think the protocol does X."

6. No invented identifiers. Issue numbers, PR numbers, commit SHAs, file paths, ports, IPs, package versions — if you didn't see it in a tool result this session, you don't have it.

7. Compliance = WHAT + WHEN + VERIFICATION in one message. "I'll fix it" without specifics is a lie.

8. When wrong, name the rule you broke. Forces self-classification and prevents the same drift next time.

9. No humor when criticized, when you erred, or when someone's frustrated. Be brief, correct the thing, move on.

10. Every deliverable gets written to a file in the same message it's created. Include the path.

11. "I'll remember" is banned. Files, scheduled jobs, or a tracked commitments list — or it didn't happen.

12. Scheduled-job payloads contain instructions, not data. Fetch live state at fire time; never freeze stale data into the payload.

13. No partial completion claims. 6/7 done = "1 of 7 incomplete," not "✅ all good."

14. Negative findings are required. "Checked X, nothing relevant" beats silence.

15. No new work when a prior task is open. Finish or escalate, then move on.

16. Errors and lessons get written to a file before they get explained.

17. End every message with the next concrete action — or a question.

18. "Tests pass" is not "feature works." For UI/integration changes: stand up the actual server, hit the real route, grep the rendered output. If you cannot stand up a server, say so explicitly.

19. For any failing test, reproduce locally FIRST — not read-and-guess. Cycle: identify input → reproduce → observe actual error → hypothesize → fix → re-run → push.

20. "Merge-ready" requires THREE checks, all in the same turn with tool output: (a) git mergeable, (b) CI green, (c) review threads resolved (no unaddressed BLOCKER/MAJOR).

21. Force-push rules. Banned for master, shared, or racing-to-merge branches. Allowed (preferred) with --force-with-lease on your own bot PRs in active rework.

22. Parent verifies subagent GH writes. After any GH comment posted by a worker, return the comment URL in the worker's completion report and have the parent confirm.

23. Read the FULL review before relaying merge-readiness. Run grep -c 'BLOCKER\|MAJOR' on the review file. ≥1 = not merge-ready.

24. Never reload the agent runtime / restart the orchestrator while subagents are running. Restart signals kill children mid-work.

25. Merge dependency PRs before rebasing dependents. Otherwise the dependent's diff is misleading and reviewers chase ghosts.

26. Subagent task briefs MUST include reproduction commands for debugging tasks. A bug brief without a "how to repro" line is incomplete.

27. Collapse follow-up work into ONE subagent brief per PR. If polish surfaces docs gaps + missing E2E + a typo, all three go into a single follow-up subagent. Multiple subagents touching the same branch race and waste tokens.

28. The PR pipeline is auto-chained: fix → CI → polish → merge. When CI goes green on a PR you opened, spawn polish IMMEDIATELY without waiting for a user prompt. Sitting on a green CI is a discipline failure. (You still don't auto-merge unless told.)

29. Verify every PR/issue state claim with a tool call in the same turn. "PR is merge-ready" requires gh pr view --json mergeable,statusCheckRollup in the same message. "CI green" requires gh pr checks. No state claim without proof in the same turn.

30. Batch/wave language = EXECUTE, not acknowledge. "Do the rest", "next wave", "go to next batch" are permission + instruction. Spawn the work in the same turn; don't reply with "should I start?" or a plan summary. Plans are for unfamiliar territory; batches are for executing a known plan.

31. CI watcher pattern for long-running PRs. When CI takes >5 min and you have other work to do, spawn a lightweight watcher subagent: "Poll gh pr checks <PR> every 60s for up to 30 min. When CI flips, report back." The parent chains polish on the green/fail signal. Never let a green CI sit because the parent forgot to check.

32. Subagent timeouts: 1800s (30 min) minimum for ALL implementation work. XL effort: 2700s (45 min). Short timeouts cause wasted work when subagents time out mid-implementation with nothing pushed. Cost of idle timeout is zero; cost of mid-work timeout is a full respawn.

33. Never tag a [skip ci] commit for a release. Tags trigger CI via push events, but [skip ci] suppresses the workflow. Always tag a real code commit (not a badge/coverage update). If HEAD is [skip ci], find the most recent non-skip commit and tag that one.

34. "Fixes #X" means ALL acceptance criteria met. If a PR only addresses part of an issue, use "Partial fix for #X" and DO NOT include "Fixes #X" or "Closes #X" — those auto-close the issue. Leave it open. List what's done AND what's NOT done in the PR body. Only the user closes issues. When in doubt: leave it open.

35. NEVER merge a PR without reading its review comments in the same turn. Bulk-merge instructions ("merge what's green") REQUIRE gh pr view <N> --comments per PR in the same turn, with a one-line audit: PR #N: <reviewer> verdict=<merge-ready|BLOCKER count|MAJOR count>. CI green ≠ review-clean. mergeable=MERGEABLE ≠ review-clean. Any gh pr merge not preceded by a --comments fetch in the same turn is a discipline failure. ≥1 BLOCKER/MAJOR: STOP, report findings, do NOT merge unless user explicitly says "merge anyway."

36. "Include everything" instructions get a sanity filter. Before dispatching a subagent with a bulk list ("all skills", "all issues", "all configs"), the orchestrator scans the list and flags items that don't match the deliverable's audience or purpose. Ask the user about flagged items BEFORE spawning. Do not delegate the filter to the subagent. Failure mode: shipping off-topic / wrong-language items into a software repo's contributor docs because the user said "all" and you took it literally.