Instruction Auditor

Contradictions between agent instruction files are the primary cause of silent misbehavior in multi-agent OpenClaw setups. The agent reads all files and the later-read file wins — but which file is read last is non-deterministic across sessions. The only fix is making all files agree.

When Contradictions Are Most Dangerous

• Cron payload vs. HEARTBEAT.md: Cron jobs often contain an inline prompt that overrides the HEARTBEAT.md the agent would otherwise read. If the cron prompt has old instructions, fixing HEARTBEAT.md does nothing.
• AGENTS.md vs. HEARTBEAT.md: AGENTS.md behavioral rules conflict with heartbeat task rules (e.g., report format specified in both places differently).
• Multiple agents sharing a sessions_send target: One agent has strict format rules, another sends freely — the receiving agent sees inconsistency.
• Sub-agent SOUL.md vs. AGENTS.md: Persona/tone specified differently in each file.

Audit Procedure

Step 1 — Discover all agents and their files

# List all agent workspaces
openclaw agents list 2>/dev/null || cat /opt/ocana/openclaw/agents/*/config.json 2>/dev/null

# Find all instruction files
find /opt/ocana/openclaw/workspace -maxdepth 3 \
  -name "AGENTS.md" -o -name "SOUL.md" -o -name "HEARTBEAT.md" \
  -o -name "MEMORY.md" -o -name "IDENTITY.md" | sort

# Find all skill SKILL.md files
find /opt/ocana/openclaw/workspace/skills -name "SKILL.md" | sort

Step 2 — Extract cron job prompts

Cron jobs often contain inline prompts that supersede heartbeat files. Extract them:

openclaw cron list --json 2>/dev/null || openclaw cron list

For each cron job, note:

• Which agent it targets
• Whether it has an inline prompt payload
• If yes: what instructions does it contain?

Also check for inline prompts embedded in openclaw.json or agent config files:

cat /opt/ocana/openclaw/openclaw.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); [print(j) for j in d.get('cron',[])]" 2>/dev/null

Step 3 — Read each agent's full instruction set

For each agent, read ALL of these (they all influence behavior):

1. AGENTS.md — primary behavioral rules
2. SOUL.md — persona and tone
3. HEARTBEAT.md — periodic task instructions
4. Cron job inline prompt (if any — this takes priority over HEARTBEAT.md)
5. Any referenced skill SKILL.md files

Step 4 — Cross-reference for contradictions

Check each pair of sources for the same agent. Flag when:

Step 5 — Report findings

For each contradiction found:

AGENT: <agent-id>
FILES: <file-a> vs <file-b>
ISSUE: <what conflicts>
IMPACT: <what behavior this causes>
FIX: <which file should be authoritative and what to change>

If no contradictions found, report: AUDIT CLEAN — no contradictions found across N files

Step 6 — Apply fixes (with confirmation for destructive changes)

• Safe fixes (adding clarity, tightening format rules): apply directly
• Fixes that change agent behavior significantly: confirm with user first
• After fixes: re-read the changed files and verify consistency

Heartbeat Schedule

Run this audit automatically:

1. Twice daily — add to main agent HEARTBEAT.md (morning + evening)
2. After any instruction change — trigger manually whenever a new agent, cron job, skill, or instruction file is added/modified

Add this to the main agent's HEARTBEAT.md:

## Instruction Audit (twice daily)
Run the `instruction-auditor` skill:
- Scan all agent workspaces and cron jobs
- Cross-reference all instruction files for contradictions
- Report findings to Koren if any contradictions found
- If clean, log result to ~/self-improving/heartbeat-state.md and return HEARTBEAT_OK

Priority Rules (when contradiction is found)

When two files conflict and you can't ask the user, use this priority order:

1. Cron inline prompt — always wins (it's what actually runs)
2. HEARTBEAT.md — beats AGENTS.md for task-specific behavior
3. AGENTS.md — beats SOUL.md for behavioral rules
4. SOUL.md — persona defaults, lowest priority for behavioral rules

Use this to determine which file needs updating to resolve the contradiction.

Common Fixes

Cron prompt overriding HEARTBEAT.md: The cron prompt is the ground truth. Either update the cron prompt to match HEARTBEAT.md, or remove the cron prompt and rely on HEARTBEAT.md. Prefer HEARTBEAT.md as the single source of truth; keep cron prompts minimal (just "run your heartbeat").

Report format in multiple places: Keep format instructions in exactly ONE place. Reference it from others: "See HEARTBEAT.md for report format." Delete duplicates.

sessions_send target inconsistency: Audit every sessions_send call across all agent files. They should all consistently target the right session key.