---
name: timeseries-skill
description: Load, update, analyze, forecast, and make evidence-linked decisions from one or multiple time series. Use for tasks that need canonical series references and the registered time-series tools.
---

# TimeSeries

Resolve all inputs to canonical series references. Downstream tools and other
consumers use those references and their associated source snapshots.

## Shared lifecycle

1. Reuse available `series_ref` values. If none exists, load the local source once
   with `timeseries_loader`. Already registered input needs no compatibility file
   or second load.
2. Persist supplied or edited frequency, unit, time, and event facts with
   `timeseries_metadata` in the same turn; continue with the returned current
   snapshot so all downstream consumers use the same version.
   Pass horizons to forecasting tools, not metadata patches. Correct invalid
   arguments before retrying; do not reload unchanged input after a parsing timeout.
3. Read the primary module for each requested capability before calling its tools:
   - [Analysis](references/analysis.md): description, comparison, anomalies,
     temporal structure, relationships, or causal evidence.
   - [Forecasting](references/forecasting.md): ordinary or event-aware future estimates.
   - [Decision](references/decision.md): actions, choices, or recommendations.
     Add analysis or forecasting only when new evidence from them is needed.
   Reading remains required when the user specifies a simple method. Computations
   already persist against their source snapshots.
   Apply the visual-first checkpoint below before numeric analysis in complex cases.
4. After completed analysis, commit its result references once with
   `timeseries_memory_commit` and `kind:"analysis"`. Commit forecast or decision
   results when persistence or later exact recall is requested. Recall only needed
   exact evidence after compaction; use known handles or locate a recent group.
   Recalled results retain their source revision, so check current applicability.

Without a complete time axis, use zero-based steps: history `0..n-1`, forecasts
starting at `n`, and event `start_index/end_index`. Persist event edits before
event evidence and retain stable `event_id` values.

Read [loader details](references/loader-contract.md) for import, metadata, or loading
errors, and [memory details](references/memory-contract.md) for recall or storage questions.

## Shared evidence discipline

- A tool output is a measurement, not a verdict. Check the question's window and
  representation, then only the selected method's relevant assumptions and support.
  Irregular sampling, non-stationarity, or regime changes matter according to what
  that method handles; they are not universal failure rules.
- Use **usable** when the main assumptions and task scope are supported;
  **qualified** when limitations leave the result informative but could change the
  conclusion; **not estimable** when computation fails or the intended quantity
  cannot be measured. State material limitations beside the claim; do not use
  numeric output as evidence in the last case. Do not invent calibrated confidence.
- Successful calls, low p-values, high coefficients, narrow intervals, or smooth
  forecasts do not alone establish reliability. Tool agreement helps only within
  compatible scopes; repeated or correlated diagnostics are not independent
  confirmation. Resolve conflicting scopes first; retain unresolved disagreement
  rather than selecting the most favorable or latest result.
- Disclose choices made after viewing data as exploratory. Do not tune windows,
  representations, models, or weights until a preferred conclusion wins.
- Keep supplied facts, measurements, forecasts, assumptions, and interpretation
  distinct. Missing or non-significant evidence is not proof of no effect.

## Default input strategy: visual structure, numeric verification

- When image input and `timeseries_render_chart` are available, inspect a chart first for questions involving time-series structure, including trend, seasonality, stationarity, anomalies, change points, volatility, cross-series relationships, lagged alignment, regime changes, and history/forecast disagreement. Prefer charts plus compact measurements over long numeric arrays.

- Use visual evidence to identify qualitative patterns and guide tool selection. Use numeric tools only when needed to verify or quantify relevant findings, such as exact values, lags, uncertainty, statistical tests, predictive reliability, or decision scores. Visual appearance alone does not establish statistical significance, stationarity, causality, or predictive reliability.

- Skip charting for simple arithmetic, metadata queries, explicit facts, or direct measurements where shape does not affect the answer. If image input or chart rendering is unavailable, continue with numerical evidence.

- Read [the chart contract](references/chart-contract.md) before the first rendering call.  Reuse a suitable image already received in the current model context and request another only when scale, overlap, or local detail obscures the relevant structure.

## Numeric retrieval and presentation

Prefer compact results. Retrieve exact observations only when requested or needed
for a calculation that computed evidence cannot supply; use the smallest sufficient
window. Complete history requires a calculation that needs the full trajectory.
Do not call `timeseries_values` merely to inspect shape.

Summarize values and tool outputs by default; expose exact points when requested.
Calculations may use exact entries without displaying arrays. Do not repeatedly
transcribe timestamps, observations, or forecasts in reasoning. Keep session handles
out of ordinary answers unless protocol or audit details are requested.