git:20260824.de5bc5d to git:20260824.a1dbbef

25 added, 15 removed. Audit A to A.

---

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,

Evaluation, Measurement, Worksheet, metrics, and reports.

2. Treat the project as owner of its RecordingSource, Loader, annotations, 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 identity 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;

- Evaluators for effect and Measurers for 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,

- and environment. Do not recollect or rebuild data when the user only asks to inspect an existing

- run.

+ generation identity, 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. Read effect and cost separately. Evaluation is a judgment; Measurement is a factual value.

- 3. Compare both totals and normalized values. Volume can increase total token or time while unit

+ 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 effect and cost separately. Evaluation is a 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.

- 4. Preserve the project's dimensions. `target` identifies what is evaluated; `category` identifies

+ 5. Preserve the project's dimensions. `target` identifies what is evaluated; `category` identifies

a concern such as quality or cost.

- 5. State every label denominator. A wrong-label share among reviewed samples is not whole-system

+ 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.

- 6. Treat `skipped`, `error`, incomplete execution, and missing policy as distinct states. An

+ 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.

- Freeze a reusable Dataset before comparing an agent change. Change one principal lever at a time,

- record the configuration and code identity, define one primary metric plus effect and health

- guardrails, then rerun the same Dataset. Lower cost is an improvement only when effect and

- completion do not regress.

+ For an agent change, freeze the same Case/input workload and evaluation semantics, then let each

+ generation identity 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 Evaluators, Measurers, policies, or report projections.

+ Change one principal agent lever at a time, record the generation identity, 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 runs, data

- health, effect, cost, 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.

+ Report the evaluated project and revision, Dataset identity, current and comparison generator

+ identities and runs, data health, effect, cost, 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.