/analyze-trajectory

name: analyze-trajectory
description: Diagnose a recurring failure (STUCK task, clustered CI error, frequent reverts) by dispatching sub-agents to digest CI logs without bloating main context. Returns one root-cause diagnosis.
tools: [bash, read_file, sub_agent, shared_state]
core: true
origin: creator

Analyze Trajectory

You are doing a **deep dive** into a recurring failure pattern. The harness's pre-computed `YOUR TRAJECTORY` block surfaces *that* something is recurring; this skill helps you understand *why* and produce a focused diagnosis.

This skill exists because raw GitHub Actions logs are too large and noisy to digest in your main context window. The pattern (Recursive Language Model — see Reithan's reference in issue #226) is: keep your root context small, dispatch a sub-agent to read the raw logs, and have the sub-agent return a 1-3 sentence summary. Recurse if the summary surfaces a deeper question.

When to use

Trigger this skill when ANY of these hold:

• `YOUR TRAJECTORY` flagged a `STUCK` task (≥3 attempts in window, 0 successes)
• A CI error fingerprint appeared `≥2×` in the recurring-errors section
• Multiple revert commits appeared across recent sessions (the trajectory's "Reverts in window" line shows the count)
• A specific issue (e.g. `#205`) has been mentioned in multiple session journals without resolution

When NOT to use

• The trajectory looks healthy. Don't spelunk for problems that aren't there — that's just burning sub-agent budget.
• The failure is well-understood already (you already know the cause from journal/learnings). Skip straight to the fix.
• You're inside Phase B (implementation) and the failure is the task you're currently doing — fix it directly, don't recurse.

Procedure

1. Frame the question (single sentence)

Examples of well-framed questions:

• *"Why does the evaluator phase fail with 'AnthropicError: rate_limit_exceeded' on sessions day-53, day-55, and day-56?"*
• *"Why was the task 'Add /fallback flag' reverted on 6 separate sessions? What's the recurring blocker?"*
• *"What does run 4321 look like at the moment of failure?"*

A good question names a specific event (run id, session day, error fingerprint) and what you want to know about it. Don't ask vague questions like *"what's wrong with my trajectory?"*

2. Identify the artifact

For each question, pick exactly one artifact to fetch:

• **CI failure** → run id from the trajectory's CI errors section. `gh run view <id> --log-failed` (drop `--repo`; gh auto-detects from the local clone's origin remote, which is the right one)
• **Reverted task** → commit SHA of the revert. `git show <sha>` and the next-newer commit's full diff
• **Session-level wreckage** → audit.jsonl from that session. **Note**: `$YOYO_AUDIT_DIR` is set by the harness ONLY inside `scripts/skill_evolve.sh` (a different invocation than evolve.sh). When loaded inside a normal evolve session, you must fetch the audit-log branch yourself first:

  git fetch --depth 50 origin audit-log:audit-log
  AUDIT_WT=$(mktemp -d)
  git worktree add "$AUDIT_WT" audit-log
  ls "$AUDIT_WT/sessions/" | tail -10
  # ... read what you need ...
  git worktree remove --force "$AUDIT_WT"

3. Decide: direct read or sub-agent?

Estimate the artifact size first:

gh run view <id> --log-failed 2>/dev/null | wc -c

• **< 5KB**: read it directly with `read_file` or `bash`. Skip sub-agent — the cost isn't worth it.
• **≥ 5KB**: dispatch a sub-agent. Don't load raw logs into your main context.

3.5. Handle large artifacts (token-aware chunking)

Before dispatching a sub-agent, estimate whether the artifact fits in a single sub-agent's context:

estimated_tokens = artifact_bytes / 4

**If estimated_tokens ≤ 30,000** (roughly half a sub-agent's context window): proceed to Step 4 as normal — single sub-agent dispatch.

**If estimated_tokens > 30,000**: the artifact is too large for one sub-agent to digest reliably. Split and fan out:

1. **Split into chunks** of ~20,000 tokens (~80,000 bytes) with 2,000-token (~8,000 byte) overlap between consecutive chunks. The overlap ensures error context that spans a chunk boundary isn't lost.

2. **Store each chunk separately** in shared state:

   shared_state set key="trajectory.run-<id>.chunk-1" value="<first 80KB>"
   shared_state set key="trajectory.run-<id>.chunk-2" value="<next 80KB, starting 8KB before the split>"
   ...

3. **Dispatch one sub-agent per chunk** with the prompt:

   You are analyzing CHUNK <N> of <M> from a CI log.

   The chunk is stored in shared state under key "trajectory.run-<id>.chunk-<N>".
   Read it with: shared_state get key="trajectory.run-<id>.chunk-<N>"

   Question: <your single-sentence question from step 1>

   Reply with ONLY a JSON object (no markdown fences, no prose):
   {
     "summary": "1-3 sentences on what this chunk reveals about the failure",
     "key_lines": ["relevant line 1", "relevant line 2"],
     "chunk_relevant": true,
     "confidence": "high|medium|low"
   }

   If this chunk contains no information relevant to the question, set chunk_relevant to false
   and keep summary/key_lines minimal.

4. **Merge chunk results** — after all chunk sub-agents return, store their combined results in shared state and dispatch one final merge sub-agent:

   shared_state set key="trajectory.run-<id>.chunk-results" value="<JSON array of chunk responses>"

Merge sub-agent prompt:

   You are merging analyses from <M> chunks of a single CI log.

   The chunk analyses are stored in shared state under key "trajectory.run-<id>.chunk-results".
   Read them with: shared_state get key="trajectory.run-<id>.chunk-results"

   Original question: <your single-sentence question from step 1>

   Synthesize the chunk analyses into a single diagnosis.
   Reply with ONLY a JSON object (no markdown fences, no prose):
   {
     "summary": "1-3 sentences explaining the root ca