brand-binary-name-logs

name	§BRAND_BINARY_NAME§-logs
description	Analyze §BRAND_NAME_TITLE§ agents 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.

3. 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:

• Usage Source: terminal is authoritative for aggregate fresh input, cache-create, cache-read, and output usage. Per-turn rows remain envelope-derived; their Turn Usage Source and Coverage lines state whether rows reconcile with terminal aggregates.
• Usage Source: envelope-partial is partial aggregate evidence used when terminal usage is absent. Do not infer unavailable terminal-only values.
• Usage Source: unknown means no usable aggregate usage record exists; displayed zeros may undercount rather than represent measured zero. The role Partial column counts only envelope-partial; check Usage Sources for unknown logs separately.
• Each string- or list-encoded tool_result payload contributes exactly once to content accounting. Ordinary user text remains text rather than a tool result.
• An empty turn has neither meaningful text nor tool activity. Meaningful tool-free text is not empty.
• In SECRET WORDS, breadcrumb applicability is required, not required, or unknown from provider/model evidence. Missing breadcrumbs are a finding only when required; unknown is neutral evidence, not a fabricated result.

Permission/policy friction is operational setup friction, not ordinary task failure. Keep it near the top and separate it from command exit failures. Split policy blocks, missing allowlist entries, shell-shape rejections, filesystem allowlist blocks, sleep/polling blocks, and §BRAND_NAME_TITLE§ project-root mismatches because their fix surfaces differ.

4. Refine the analysis with the bounded query helper, not by manually reading raw log files. Use query-log.py to extract trimmed evidence windows for specific questions, for example:

python3 ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/scripts/query-log.py §BRAND_PROJECT_DIRNAME§/agent-outputs/coder-3-*.txt --around-errors 3 --task architecture-4-code-planning-0-b-repair-0-coding-1
python3 ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/scripts/query-log.py §BRAND_PROJECT_DIRNAME§/agent-outputs/coder-3-*.txt --around-operational-friction 3 --task architecture-4-code-planning-0-b-repair-0-coding-1

• Operational friction is provider-forced foreground timeout/backgrounding, even when is_error is false. Keep it separate from ordinary errors, permission/policy blocks, and deliberate background commands. Refine either query with --max-field and --json when useful.
• Manual raw-log reads are a last resort only when the query helper cannot answer a concrete evidence question; state the gap before doing so.
• When referring to a specific session in your summary, include the log filename (for example coder-1-20260417-171454.txt) so the reader can trace the claim back to the exact source log quickly.

5. Before proposing a fix, check whether the fix is already implemented (e.g. an instruction already exists but agents ignore it):

   • Read one agent prompt of the relevant role in §BRAND_PROJECT_DIRNAME§/agent-prompts/
   • Check the contract files in ~/§BRAND_GLOBAL_DIRNAME§/ (CORE.md, AGENT_TOOLS.md, MULTI_AGENT_MODE.md)

6. Write the final report using skills/§BRAND_BINARY_NAME§-logs/report-format.md.

7. Propose fixes whenever possible.

FALSE POSITIVES:

• Repeated contract reads (~8KB per session): Agents read AGENT_TOOLS.md, GUARDRAILS.md, etc. during initialization. These are usually cache hits — negligible cost. Do not flag as waste unless the same payload is reread for no reason later in the session.
• Rich JSON transcript volume: Provider CLIs may emit full JSONL session transcripts containing runtime envelopes, tool calls, tool results, usage metadata, rate-limit events, and command output. Large §BRAND_PROJECT_DIRNAME§/agent-outputs/*.txt files are not automatically agent reasoning bloat. Attribute volume to avoidable behavior before raising it: broad file reads, repeated large diffs, noisy failing tests, unbounded command output, or repeated tool loops.
• Contract/prompt volume: Contract and guardrail files are stable, load-bearing context and are often cacheable. Do not report their size as waste by itself. Parametric role/task prompts are expected to vary and may not cache well; flag only avoidable duplication, poor ordering that defeats stable-prefix reuse, prompt growth across retries, or dynamic artifacts that should have been referenced instead of embedded.

NOTE: The skill contains a web tool for humans to inspect logs: ~/§BRAND_GLOBAL_DIRNAME§/skills/§BRAND_BINARY_NAME§-logs/tools/§BRAND_BINARY_NAME§-session-analyzer.html