Trajectory Grounding Agent

The Trajectory Grounding Agent (atelier-trajectory-grounding) is an internal subagent used by Verify and other Atelier workflows that need to reason about a Claude Code session.

Do not invoke it directly. Atelier calls it when a parent skill needs structured evidence from an agent trajectory file.

When it is used

• Verification needs non-obvious context from the agent’s implementation session
• A workflow needs to inspect tool usage, token counts, errors, file access, or subagent spawning
• A report needs to summarize what happened in a .jsonl session without loading the full file into context
• A parent skill needs session evidence organized around a specific question or acceptance criterion

Input

The agent receives:

• trajectory_file — Absolute path to a Claude Code .jsonl session trajectory.
• question — The specific analysis question to answer.
• focus — A tag that selects the relevant analysis recipe, such as tool usage, token usage, errors, conversation flow, files touched, subagents, verification context, or full session summary.

What it does

1. Selects a jq recipe — Chooses the cookbook query that matches the requested focus.
2. Extracts targeted data — Uses jq against the JSONL file instead of reading the raw trajectory into context.
3. Computes derived values — Calculates summaries such as totals, cache hit rate, counts, timelines, or model usage when needed.
4. Organizes the result — Returns concise markdown with the answer, supporting details, and relevant session metadata.
5. Adapts on format issues — If a query fails, it inspects only a few lines to diagnose the schema before retrying.

Output

The parent skill receives structured markdown containing:

• Question answered — A heading that states the analysis performed.
• File and session metadata — Trajectory path, session ID, model, and turn count when available.
• Result — The primary answer, such as ranked tool counts, token totals, errors, or verification context.
• Details — Supporting data for the parent skill to quote or summarize.

For verification context, the agent focuses on decisions, failed attempts, user redirections, and external references that are not already obvious from the final code or diff.

Quality standards

The agent treats trajectory files as large structured data. It uses jq recipes instead of reading full .jsonl files, avoids writing parser scripts, guards against missing fields, and keeps returned evidence focused on the question.