trajectory git:20260825.b3dbb8dA

Immutable. This exact content is served forever at /api/v1/blob/2ce2732c58485bd5.

---
name: trajectory
description: Discover, run, interpret, and iteratively tune a project's existing agent trajectory evaluation capability. Use when the user asks to evaluate agent trajectories, compare effect and cost across runs, find trajectory smells or the next trajectory problem, or identify optimizations for a known trajectory issue. Follow project-owned data sources, evaluators, measurements, and entrypoints; do not invent a missing evaluation capability.
---

# Trajectory Quality

Evaluate and tune an agent from its recorded decisions and actions. Operate the project's existing
trajectory capability; do not replace its framework, business data, labels, or judgment criteria.

## Keep the owners separate

1. Treat case-harness or another trajectory framework as infrastructure for normalization, Dataset,
   Detection, Evaluation, Measurement, Worksheet, metrics, and reports.
2. Treat the project as owner of its RecordingSource, Loader, annotations, Detectors, Evaluators,
   Measurers, report projection, canonical command, and optimization targets.
3. Treat this skill as the operator that discovers those assets, runs them, interprets evidence, and
   organizes controlled tuning experiments.

Do not call a lower-level framework directly when the project exposes a wrapper. Framework code
without project-owned trajectory data and evaluation logic is `no_capability`.

## Discover the capability

Read the project's AGENTS.md and README first, then locate:

- the canonical command for collecting, building, evaluating, or reporting trajectories;
- persisted Dataset, Run, Worksheet, Verdict, JSON, or HTML artifacts;
- source identity and Dataset versioning;
- the generation provenance for each trajectory, including the agent revision, instruction/skill
  version, exposed tool-contract version, loop/compact configuration, model, and orchestration when
  those can affect behavior;
- human or external annotations and their coverage;
- Detectors for behavior patterns, Evaluators for effect or contract judgments, and Measurers for
  factual values such as cost;
- comparison baselines, experiment configuration, and project-local operating notes.

Classify discovery as `ready`, `blocked`, or `no_capability`. Report ambiguity when multiple
plausible entrypoints remain; do not guess. Missing labels, history, usage data, or a verdict policy
may limit a comparison without making an otherwise valid analysis run disappear.

## Run and interpret

Use the project-owned entrypoint and preserve the requested revision, Dataset, model configuration,
generation provenance, and environment. Do not recollect or rebuild data when the user only asks to
inspect an existing run.

Interpret artifacts in this order:

1. Check source freshness, build issues, unmatched annotations, execution coverage, measurement
   coverage, and cohort comparability.
2. Check effect regression across generator versions before subtler smells. Do not confuse the
   Dataset version or Evaluator version with the identity of the agent configuration that generated
   a trajectory.
3. Read Detection, Evaluation, and Measurement separately. A Finding describes a detected behavior
   pattern and does not imply a verdict; Evaluation is a contract or effect judgment; Measurement
   is a factual value.
4. Compare both totals and normalized values. Volume can increase total token or time while unit
   cost improves, and the reverse can also happen.
5. Preserve the project's dimensions. `target` identifies what is evaluated; `category` identifies
   a concern such as quality or cost.
6. State every label denominator. A wrong-label share among reviewed samples is not whole-system
   accuracy, and sparse annotations only support a directional conclusion.
7. Treat `skipped`, `error`, incomplete execution, and missing policy as distinct states. An
   analysis-only run can be useful, but it is not a passing release gate.

## Find and tune

- To find trajectory smells and select the next evidence-backed problem, read
  [references/problem-discovery.md](references/problem-discovery.md) completely.
- When evidence points to objectives, policy, evidence standards, or instructions, read
  [references/system-prompt.md](references/system-prompt.md) completely.
- When evidence points to capability selection or a tool's name, description, arguments,
  granularity, execution, or result, read [references/tool.md](references/tool.md) completely.
- When evidence points to budgets, retries, concurrency, state, termination, orchestration, or
  compact, read [references/loop-mechanism.md](references/loop-mechanism.md) completely.

Do not map an aggregate label or smell directly to a fix. First identify the repeated trajectory
behavior, then use its evidence and counterexamples to choose the system-prompt, tool-contract,
loop, compact, model, or orchestration surface.

For an agent change, freeze the same Case/input workload and evaluation semantics, then let each
generation configuration produce its own Trajectories. Align the resulting cohorts by stable Case or
input identity; do not pretend that changed observations are the same TrajectoryDataset. Reuse one
fixed TrajectoryDataset only when comparing Detectors, Evaluators, Measurers, policies, or report
projections.

Benchmark a deterministic adapter, result filter, CLI output compressor, or other pure transform by
replaying the same captured inputs through both versions. Do not use two stochastic end-to-end
agent runs to claim the component's reduction. If the transform changes what the agent observes,
follow the component benchmark with aligned Case/input trajectory cohorts to check effect and
completion.

Change one principal agent lever at a time, record the generation provenance, define one primary
metric plus effect and health guardrails, and compare the aligned cohorts. Lower cost is an
improvement only when effect and completion do not regress.

Assessment is read-only. Propose changes to prompts, tools, agent loops, orchestration, models, or
evaluation assets; implement them only when the user asks for that mutation.

## Report and retain learning

Report the evaluated project and revision, Dataset identity, current and comparison generation
provenance and runs, data health, effect, cost, selected Detector Findings, Evaluator judgments,
the next prioritized smell or problem, supporting Worksheet examples, unknowns, and artifact paths.
Lead with the decision-relevant summary; keep
per-trajectory evidence in drill-down artifacts.

Persist run-specific evidence and project-specific lessons beside the project's evaluation assets.
Promote a problem pattern or optimization tactic into this skill's references only after it proves
reusable across projects. Do not copy private samples, volatile weekly numbers, credentials, or
project-only commands into the plugin.