---
name: reliable-subagent
description: Use when spawning subagents for background tasks - ensures logging, checkpoints, heartbeats, and recovery from failures. Required for all monitoring and research tasks.
---

# Reliable Subagent Pattern

## Overview

Subagents fail silently. This skill ensures every subagent writes progress to logs, saves checkpoints, and can be monitored/recovered.

**Core principle:** No silent failures. Every action logged. Every milestone checkpointed.

## Root Causes of Failures (Observed)

Based on actual production failures:

1. **Missing log writes** - Agent does work but never writes to log
2. **Timestamp corruption** - `[2026-02-02T00:00:00Z]` instead of real time
3. **One-liner log** - Only writes START, then disappears (FIX: Use PHASES and STRICT PROTOCOL)
4. **WebSearch permission denied** - No fallback to browser
5. **Large scope** - Too many tasks, agent loses focus
6. **No explicit file write** - Results in memory, never written to disk
7. **Hallucinated tool use** - Subagent claims it ran a tool but didn't (FIX: Explicit XML format requirement or PHASES)

## Log Structure

**CRITICAL: Use write tool for logs and outputs to ensure persistence**

**Required entries:**

| Phase | Entry | When |
|-------|-------|------|
| START | `[TS] START task_id=X scope="Y"` | First line |
| SEARCH | `[TS] SEARCH query="X" results=N` | After each search |
| FETCH | `[TS] FETCH url="X" status=ok/fail` | After each fetch |
| EXTRACT | `[TS] EXTRACT thesis="X"` | When thesis found |
| WRITE | `[TS] WRITE file="X" lines=N` | After file write |
| COMPLETE | `[TS] COMPLETE summary="X"` | On success |

## Subagent Prompt Template (MANDATORY)

When dispatching any subagent, include this block:

```markdown
## RELIABLE RESEARCH PROTOCOL
Agent: {NAME}
Log: {LOG_PATH}
Output: {OUTPUT_PATH}

**LANGUAGE: ALL OUTPUT FILES MUST BE WRITTEN IN RUSSIAN (русский язык).**
Translate all content, summaries, and findings to Russian before writing.

STRICT PHASES:
1. START: Log start time and scope.
2. RESEARCH: Search for relevant terms.
3. ANALYZE: Fetch results and extract key points.
4. WRITE: Create the output file **IN RUSSIAN**.
5. COMPLETE: Log completion.

YOU MUST NOT STOP until all phases are complete.
Use the write tool for both logs and output.
Remember: Output content MUST be in Russian.
```

## State File

Location: `/root/.openclaw/workspace/memory/agent-state.json`

## Monitoring Protocol (Parent Agent)

Every heartbeat check:

```bash
# 1. Check if subagent output files exist
ls -la /root/obsidian/Main/Monitoring/*/

# 2. Read last 20 lines of logs
tail -20 /root/obsidian/Main/Monitoring/logs/*.log
```

## Narrow Scope Rule

**ONE subagent = ONE task**