§BRAND_BINARY_NAME§-logs

SCOPE: The logs in §BRAND_PROJECT_DIRNAME§/agent-outputs/ and task state in §BRAND_PROJECT_DIRNAME§/state.yaml (nowhere else unless told otherwise explicitly). The prompt may filter more specifically, e.g. a specific role, task, status, or time range.

OBJECTIVE: Find recurring task, review, integration, tool, context, and setup frictions; correlate state symptoms with log evidence; propose fixes.

PROTOCOL:

1. For supervisor lifecycle questions (registration, claiming, retry, shutdown, or automatic merge), first inspect bounded evidence from matching supervisor-{role}-*.stdout.log and .stderr.log files. A successful detached spawn confirms these files are open before returning; failures before that readiness point are reported synchronously to the spawning command or TUI and may not have a supervisor log. These masked runtime logs are not provider transcripts: do not pass them to analyze-log.py. Correlate their timestamps and task IDs with state history, then use the provider logs only if the question crosses into agent-session behavior.

2. Start provider-session analysis by running the analyzer:

python3 ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/scripts/analyze-log.py §BRAND_PROJECT_DIRNAME§/agent-outputs/coder-*.txt        # all coder agents
python3 ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/scripts/analyze-log.py §BRAND_PROJECT_DIRNAME§/agent-outputs/coder-1-*.txt # single agent
python3 ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/scripts/analyze-log.py --summary-by-role §BRAND_PROJECT_DIRNAME§/agent-outputs/*.txt

By default, run the analyzer per role. Use --summary-by-role when you need cross-role aggregate token, tool, MCP, error, and skill-invocation totals. Its Usage Sources and Partial columns show aggregate provenance, while OPERATIONAL FRICTION groups events by category and role and includes example source logs.

1. Inspect §BRAND_PROJECT_DIRNAME§/state.yaml for task-level frictions before drawing conclusions:

python3 ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/scripts/analyze-state.py §BRAND_PROJECT_DIRNAME§/state.yaml

• tasks with review_cycles_total >= 4
• tasks whose status is INTEGRATION_FAILED, BLOCKED, SUPERSEDED, or ABANDONED
• if review_cycles_total is missing, count task history events named rejected or review_verdict_rejected

Lifecycle churn outranks aggregate log noise:

• Treat any task with review_cycles_total >= 4 or counted rejection events

  = 4 as a P1 finding by default, even if its current status is MERGED.

• Do not let high tool-error counts, token volume, or eventual merge status bury repeated review/retry cycles. A merged high-churn task is unhealthy convergence unless the evidence proves the retries were expected.
• If analyzer counts and current task fields disagree, report both numbers and explain the likely distinction (for example, history/attempt total vs current review_cycles field). Prioritize using the higher history count until disproven by bounded evidence.
• The highest-churn task must appear first in the summary table and in cross-correlation before setup/tool/context frictions.

Report sections: session header, permission/policy friction, token summary, content breakdown, top items by size, tool usage, empty turns, skill invocations, secret-word/init breadcrumb detection, turn timeline, tool result breakdown, MCP usage, efficiency insights, and struggle sequences. Rich format adds per-turn context growth, top longest turns, cost breakdown with system-prompt replay cost, and MCP server status. Sparse logs have aggregate usage only; do not infer exact per-turn growth or cost. Context-fill percentages are authoritative only when the provider records context-window metadata. Do not infer historical window size or compaction thresholds from the analyzer process environment.

Interpret corrected rich-log diagnostics as follows: