@oqtopus-team/pi-qdash 0.1.4 → 0.1.6

package/extensions/tools/timeseries.ts

@@ -0,0 +1,211 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { QDashClient } from "@oqtopus-team/qdash-client";
+import { Type } from "typebox";
+
+import {
+  compareTimeseries,
+  csvInspectionText,
+  inspectExternalCsv,
+  loadExternalCsvSeries,
+  timeseriesComparisonText,
+  type CsvTimeFormat,
+  type ExternalCsvSpec,
+  type NumericTimeseries,
+} from "../lib/timeseries-analysis.js";
+import type { TimeseriesInvestigationContext } from "../lib/investigation-context.js";
+import { toTextToolResult } from "../lib/results.js";
+import { timeseriesPoints } from "../lib/timeseries-plot.js";
+
+type ComparisonToolParams = {
+  profile?: string;
+  configPath?: string;
+  useEnv?: boolean;
+  chipId?: string;
+  startAt?: string;
+  endAt?: string;
+  withinHours?: number;
+  qdashSeries?: Array<{ parameter: string; qid?: string; tag?: string; label?: string; unit?: string; scale?: number; offset?: number }>;
+  csvSeries?: Array<ExternalCsvSpec & { timeFormat?: CsvTimeFormat }>;
+  resampleMinutes?: number;
+  smoothingWindowMinutes?: number;
+  detrend?: string;
+  normalize?: string;
+  maxInterpolationGapMinutes?: number;
+  periodSearch?: { minMinutes: number; maxMinutes: number; stepMinutes?: number };
+  includeAlignedData?: boolean;
+  useInvestigationContext?: boolean;
+};
+
+export type TimeseriesToolDependencies = {
+  makeClient: (params: { profile?: string; configPath?: string; useEnv?: boolean }) => Promise<QDashClient>;
+  defaultChipId: (client: QDashClient, chipId?: string) => Promise<string>;
+  investigationContext?: () => TimeseriesInvestigationContext | undefined;
+};
+
+export function registerTimeseriesComparisonTool(pi: ExtensionAPI, dependencies: TimeseriesToolDependencies): void {
+  pi.registerTool({
+    name: "qdash_inspect_timeseries_csv",
+    label: "QDash Inspect Timeseries CSV",
+    description: "Inspect a local CSV schema and numeric/time characteristics before mapping it into a QDash timeseries comparison. Read-only; never uploads the file.",
+    promptSnippet: "Inspect local CSV columns, numeric ranges, timestamps, and cadence before comparison",
+    promptGuidelines: [
+      "Use qdash_inspect_timeseries_csv before qdash_compare_timeseries when a local CSV schema, timestamp format, timezone, or numeric columns are not already known.",
+      "Do not infer the timezone of naive timestamps from qdash_inspect_timeseries_csv samples; ask for or supply an explicit timezone offset.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({ description: "Local CSV path, absolute or relative to the current working directory." }),
+      delimiter: Type.Optional(Type.String({ description: "Single-character delimiter. Defaults to comma." })),
+      skipRows: Type.Optional(Type.Number({ description: "Rows before the header. Defaults to 0." })),
+      timeColumn: Type.Optional(Type.String({ description: "Optional timestamp column to validate." })),
+      timeFormat: Type.Optional(Type.String({ description: "iso, yyyy/M/d H:mm, yyyy-MM-dd HH:mm:ss, unix-seconds, or unix-milliseconds." })),
+      timezoneOffsetMinutes: Type.Optional(Type.Number({ description: "Required to validate timestamps without an explicit zone; JST is 540." })),
+      scanRows: Type.Optional(Type.Number({ description: "Rows to profile, from 1 to 100000. Defaults to 10000." })),
+    }),
+    async execute(_toolCallId, params: {
+      path: string;
+      delimiter?: string;
+      skipRows?: number;
+      timeColumn?: string;
+      timeFormat?: CsvTimeFormat;
+      timezoneOffsetMinutes?: number;
+      scanRows?: number;
+    }, _signal, _onUpdate, ctx) {
+      const inspection = inspectExternalCsv(params, ctx.cwd);
+      return toTextToolResult(csvInspectionText(inspection), inspection, {
+        tool: "qdash_inspect_timeseries_csv",
+        path: inspection.path,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "qdash_compare_timeseries",
+    label: "QDash Compare Timeseries",
+    description: "Compare two or more QDash and/or local CSV numeric timeseries on a common time grid. Read-only; reports alignment, correlations, optional shared-period fits, phases, and statistical caveats without inferring causality.",
+    promptSnippet: "Compare generic QDash metrics and external CSV sensor timeseries",
+    promptGuidelines: [
+      "Use qdash_compare_timeseries when comparing multiple QDash metrics, targets, or local CSV sensor logs over time.",
+      "For qdash_compare_timeseries local CSV inputs, explicitly specify timestamp format and timezone offset when timestamps have no zone.",
+      "Treat qdash_compare_timeseries correlations and shared periods as evidence of association, not proof of causality.",
+    ],
+    parameters: Type.Object({
+      profile: Type.Optional(Type.String({ description: "QDash profile name. Defaults to env when QDASH_BASE_URL is set, otherwise 'default'." })),
+      configPath: Type.Optional(Type.String({ description: "Optional path to qdash config.ini." })),
+      useEnv: Type.Optional(Type.Boolean({ description: "Force QDASH_* environment variables instead of a profile." })),
+      chipId: Type.Optional(Type.String({ description: "Chip ID. Defaults to the active/default chip when omitted." })),
+      startAt: Type.Optional(Type.String({ description: "Optional common start timestamp as an ISO timestamp with timezone." })),
+      endAt: Type.Optional(Type.String({ description: "Optional common end timestamp as an ISO timestamp with timezone." })),
+      withinHours: Type.Optional(Type.Number({ description: "QDash lookback when startAt is omitted. Defaults to 168 hours." })),
+      useInvestigationContext: Type.Optional(Type.Boolean({ description: "Use missing series/window/transform defaults from the active investigation context. Defaults to true." })),
+      qdashSeries: Type.Optional(Type.Array(Type.Object({
+        parameter: Type.String({ description: "QDash task-result parameter name." }),
+        qid: Type.Optional(Type.String()),
+        tag: Type.Optional(Type.String()),
+        label: Type.Optional(Type.String({ description: "Unique display label. Defaults to parameter plus qid/returned series." })),
+        unit: Type.Optional(Type.String({ description: "Optional output unit override." })),
+        scale: Type.Optional(Type.Number({ description: "Multiply QDash values by this factor. Defaults to 1." })),
+        offset: Type.Optional(Type.Number({ description: "Add this value after scaling. Defaults to 0." })),
+      }), { maxItems: 12 })),
+      csvSeries: Type.Optional(Type.Array(Type.Object({
+        path: Type.String({ description: "Local CSV path, absolute or relative to the current working directory." }),
+        timeColumn: Type.String(),
+        valueColumns: Type.Array(Type.Object({
+          column: Type.String(),
+          label: Type.Optional(Type.String()),
+          unit: Type.Optional(Type.String()),
+          scale: Type.Optional(Type.Number()),
+          offset: Type.Optional(Type.Number()),
+        }), { minItems: 1, maxItems: 12 }),
+        timeFormat: Type.Optional(Type.String({ description: "iso, yyyy/M/d H:mm, yyyy-MM-dd HH:mm:ss, unix-seconds, or unix-milliseconds. Defaults to iso." })),
+        timezoneOffsetMinutes: Type.Optional(Type.Number({ description: "Required for timestamps without an explicit zone; for JST use 540." })),
+        delimiter: Type.Optional(Type.String({ description: "Single-character delimiter. Defaults to comma." })),
+        skipRows: Type.Optional(Type.Number({ description: "Rows to skip before the header. Defaults to 0." })),
+        filters: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String()), { description: "Optional exact-match row filters keyed by column name." })),
+      }), { maxItems: 8 })),
+      resampleMinutes: Type.Optional(Type.Number({ description: "Common grid interval. Defaults to 1 minute." })),
+      smoothingWindowMinutes: Type.Optional(Type.Number({ description: "Centered moving-average window. Zero disables smoothing." })),
+      detrend: Type.Optional(Type.String({ description: "none or linear. Defaults to none." })),
+      normalize: Type.Optional(Type.String({ description: "none or zscore. Defaults to none." })),
+      maxInterpolationGapMinutes: Type.Optional(Type.Number({ description: "Do not interpolate across larger source gaps." })),
+      periodSearch: Type.Optional(Type.Object({
+        minMinutes: Type.Number(),
+        maxMinutes: Type.Number(),
+        stepMinutes: Type.Optional(Type.Number()),
+      })),
+      includeAlignedData: Type.Optional(Type.Boolean({ description: "Include transformed aligned rows in structured details. Defaults to false." })),
+    }),
+    async execute(_toolCallId, params: ComparisonToolParams, _signal, _onUpdate, ctx) {
+      const investigation = params.useInvestigationContext === false ? undefined : dependencies.investigationContext?.();
+      const analysis = investigation?.analysis;
+      const detrend = params.detrend ?? analysis?.detrend ?? "none";
+      const normalize = params.normalize ?? analysis?.normalize ?? "none";
+      if (detrend !== "none" && detrend !== "linear") throw new Error("detrend must be 'none' or 'linear'");
+      if (normalize !== "none" && normalize !== "zscore") throw new Error("normalize must be 'none' or 'zscore'");
+      const csvSpecs = (params.csvSeries ?? investigation?.csvSeries ?? []).map((spec) => ({
+        ...spec,
+        timezoneOffsetMinutes: spec.timezoneOffsetMinutes ?? investigation?.timezoneOffsetMinutes,
+      }));
+      const qdashSpecs = (params.qdashSeries ?? investigation?.qdashSeries ?? []).map((spec) => ({
+        ...spec,
+        tag: spec.tag ?? investigation?.tag,
+      }));
+      const csv = csvSpecs.flatMap((spec) => loadExternalCsvSeries(spec, ctx.cwd));
+      const qdash: NumericTimeseries[] = [];
+      let resolvedStartAt = params.startAt ?? investigation?.startAt;
+      let resolvedEndAt = params.endAt ?? investigation?.endAt;
+      if (qdashSpecs.length > 0) {
+        resolvedEndAt = resolvedEndAt ?? new Date().toISOString();
+        resolvedStartAt = resolvedStartAt ?? new Date(Date.parse(resolvedEndAt) - (params.withinHours ?? 168) * 3_600_000).toISOString();
+        const client = await dependencies.makeClient(params);
+        const chipId = await dependencies.defaultChipId(client, params.chipId);
+        const fetched = await Promise.all(qdashSpecs.map(async (spec) => {
+          const data = await client.getTaskResultsTimeseries({
+            chipId,
+            parameter: spec.parameter,
+            qid: spec.qid,
+            tag: spec.tag,
+            startAt: resolvedStartAt!,
+            endAt: resolvedEndAt!,
+          });
+          return { spec, points: timeseriesPoints(data) };
+        }));
+        for (const { spec, points } of fetched) {
+          const groups = new Map<string, typeof points>();
+          for (const point of points) {
+            if (!point.at) continue;
+            const group = spec.qid ?? point.series;
+            groups.set(group, [...(groups.get(group) ?? []), point]);
+          }
+          for (const [group, values] of groups) {
+            const suffix = spec.qid ? ` q${spec.qid}` : groups.size > 1 ? ` ${group}` : "";
+            qdash.push({
+              label: spec.label ? groups.size > 1 ? `${spec.label} ${group}` : spec.label : `${spec.parameter}${suffix}`,
+              unit: spec.unit ?? values.find((point) => point.unit)?.unit,
+              source: "qdash",
+              points: values.map((point) => ({
+                at: point.at!,
+                value: point.value * (spec.scale ?? 1) + (spec.offset ?? 0),
+              })),
+            });
+          }
+        }
+      }
+      const comparison = compareTimeseries([...qdash, ...csv], {
+        startAt: resolvedStartAt,
+        endAt: resolvedEndAt,
+        resampleMinutes: params.resampleMinutes ?? analysis?.resampleMinutes,
+        smoothingWindowMinutes: params.smoothingWindowMinutes ?? analysis?.smoothingWindowMinutes,
+        detrend,
+        normalize,
+        maxInterpolationGapMinutes: params.maxInterpolationGapMinutes ?? analysis?.maxInterpolationGapMinutes,
+        periodSearch: params.periodSearch ?? analysis?.periodSearch,
+        includeAlignedData: params.includeAlignedData,
+      });
+      return toTextToolResult(timeseriesComparisonText(comparison), comparison, {
+        tool: "qdash_compare_timeseries",
+        seriesCount: comparison.series.length,
+        investigation: investigation?.name,
+      });
+    },
+  });
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",
   "author": "OQTOPUS Team <oqtopus-team@googlegroups.com>",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oqtopus-team/pi-qdash.git"
@@ -24,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@oqtopus-team/qdash-client": "^0.1.3"
+    "@oqtopus-team/qdash-client": "^1.9.11"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -39,7 +42,8 @@
     ]
   },
   "scripts": {
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "rm -rf .test-dist && tsc --noEmit false --outDir .test-dist && node --test tests/*.test.mjs; status=$?; rm -rf .test-dist; exit $status"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",

package/skills/qdash/SKILL.md

@@ -15,7 +15,7 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `qdash_get_chip_metrics`, `qdash_list_chip_qubits`, `qdash_list_chip_couplings`
    - `qdash_list_cryostats`, `qdash_list_cooldowns`
    - `qdash_get_cooldown_wiring`, `qdash_wiring_insights`, `qdash_list_cooldown_wiring_events`
-   - `qdash_get_timeseries`, `qdash_plot_timeseries`
+   - `qdash_get_timeseries`, `qdash_plot_timeseries`, `qdash_inspect_timeseries_csv`, `qdash_compare_timeseries`
    - `qdash_list_task_results`, `qdash_get_task_result`
    - `qdash_list_issues`
    - `qdash_list_flows`, `qdash_get_flow`
@@ -24,6 +24,7 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies`
    - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`, `qdash_build_qcal_evidence`
    - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
+   - `qdash_preview_forum_image_reply`, then `qdash_create_forum_image_reply` for confirmed uploads of locally generated analysis images
 3. Use harness overview tools for status and triage:
    - `qdash_investigate` for natural-language requests to investigate or compare recent calibration, target history, figures, failures, issues, and Forum context
    - `qdash_compare_calibration` for read-only before/after comparison of repeated target calibration results
@@ -64,6 +65,8 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 /qdash-use-chip [chip_id]
 /qdash-use-target qid <qid> | coupling <coupling_id>
 /qdash-use-agent-session <session_id>
+/qdash-investigation-setup [json]
+/qdash-clear-investigation
 /qdash-context
 /qdash-dashboard [limit]
 /qdash-wiring-insights
@@ -73,6 +76,43 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 
 Prefer the current context when the user has already selected a profile/chip/session. Tools use that context when parameters are omitted.
 
+## Cooldown-aware investigations
+
+Treat cooldown identity as mandatory investigation context whenever comparing calibration results, coherence metrics, drift, failures, or Forum evidence across time:
+
+1. Call `qdash_list_cooldowns` for the chip early in the investigation and record the relevant `cooldown_id`, `started_at`, and `ended_at` boundaries.
+2. Assign every result or Forum observation used in a comparison to a cooldown. Prefer an explicit `cooldown_id`; when it is absent, infer membership only from the chip association and timestamp boundaries, and label it as inferred.
+3. Do not describe values from different cooldowns as one continuous degradation, recovery, or before/after trend. Partition the evidence by cooldown first. Cross-cooldown comparison is allowed only when it is explicitly identified as such.
+4. State plainly whether the compared evidence comes from the same cooldown, different cooldowns, or an unresolved cooldown context. Include the cooldown IDs in the report and in Forum evidence replies when relevant.
+5. Same cooldown does not guarantee identical measurement conditions. If cabling, attenuation, instruments, or wiring may have changed, inspect `qdash_get_cooldown_wiring` with history or `qdash_list_cooldown_wiring_events`, then distinguish a cooldown boundary from an in-cooldown wiring change.
+6. Do not treat a temporary disconnect/reconnect as a new cooldown unless QDash records a new cooldown. Describe it as an in-cooldown wiring event and report whether the wiring was nominally restored.
+7. Prefer same-cooldown, temporally adjacent measurements for physical interpretation. Older-cooldown evidence may provide context but must not be used to explain a current-cooldown anomaly without an explicit caveat.
+
+Before publishing investigated evidence, verify that every date-based claim respects these rules.
+
+## Generic timeseries comparison
+
+Use `qdash_compare_timeseries` when the investigation needs to align multiple
+QDash metrics/targets, local CSV sensor logs, or both. For repeated calls, use
+`/qdash-investigation-setup` to store the arbitrary series mappings, window,
+timezone, and transform defaults; explicit tool arguments override the preset.
+Do not assume a specific
+CSV layout, metric name, target, unit, timestamp format, or timezone:
+
+1. Inspect unknown CSV headers, numeric coverage, and optional time cadence with
+   `qdash_inspect_timeseries_csv` first.
+2. Supply `timeColumn`, one or more `valueColumns`, and optional exact-match
+   `filters`; use `scale`/`offset` only for explicit unit conversion.
+3. For timestamps without a zone, require an explicit
+   `timezoneOffsetMinutes` (JST is `540`) rather than relying on the host clock.
+4. Start with raw/no-transform comparison, then state any smoothing,
+   interpolation, detrending, normalization, and period-search settings.
+5. Report overlap duration, source point counts, aligned point count, number of
+   observed cycles, correlations, phases, and explained fractions together.
+6. Treat correlation and shared periodicity as evidence of association. Do not
+   claim direct causality without intervention, longer observation, or evidence
+   that excludes a common driver.
+
 For cryostat wiring requests, start with `qdash_get_cooldown_wiring`. Pass `cooldownId` when the user names one; otherwise pass `cryoId`, or omit both to resolve the active/newest cooldown from the current/default chip. Prefer the compact `wiring.markdown`; request raw blocks only when structural or embedded BlockNote data is necessary, and request history when investigating wiring changes. Set `includeInsights` or call `qdash_wiring_insights` when the user asks what is characteristic, unusual, or worth checking in attenuation; summarize control/readout totals and affected qubits/MUXes instead of dumping the raw table.
 
 ## Configuration
@@ -90,14 +130,15 @@ If `QDASH_BASE_URL` is set and no profile is specified, the tools default to env
 
 When the user wants to preserve an investigated observation in QDash forum/notes:
 
-1. Inspect the task result, task figure, timeseries/history, and related forum context first.
-2. Summarize the observation as evidence, not as an automatic calibration decision.
+1. Inspect the task result, task figure, timeseries/history, related Forum context, and cooldown membership first.
+2. Summarize the observation as evidence, not as an automatic calibration decision. State whether compared observations are from the same cooldown, and separate in-cooldown wiring changes from cooldown boundaries.
 3. Prefer replying to an existing target/coupling forum thread when one exists.
 4. Use `qdash_create_forum_evidence_reply` for task-result evidence so figures are embedded as QDash UI image blocks (`/api/executions/figure?path=...`) and visible in the forum.
-5. Include task and execution QDash Web URLs in the reply.
-6. When mentioning history or trends, include links to representative historical task results.
-7. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
-8. Ask for confirmation before creating/updating the forum post.
+5. For locally generated analysis images, call `qdash_preview_forum_image_reply` first, show the exact paths and reply text, then use `qdash_create_forum_image_reply` only after explicit confirmation. Supported images are PNG, JPEG, GIF, and WebP up to 5 MB each.
+6. Include task and execution QDash Web URLs in the reply when applicable.
+7. When mentioning history or trends, include links to representative historical task results.
+8. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
+9. Ask for confirmation before uploading images or creating/updating the forum post.
 
 ## Safety
 

package/skills/qdash-calibration-agent/SKILL.md

@@ -32,7 +32,8 @@ This skill defines how pi should behave as a conservative, confirmation-gated ca
 
 - Work one target at a time: one qubit or one coupling per action/session when possible.
 - Diagnose before changing parameters.
-- Prefer read-only inspection first: dashboard, failed task results, history, figures, forum posts, and task knowledge when available.
+- Establish cooldown identity before interpreting history: partition evidence by `cooldown_id`, never present different cooldowns as one continuous trend, and distinguish cooldown boundaries from in-cooldown wiring changes.
+- Prefer read-only inspection first: dashboard, cooldowns and wiring events, failed task results, history, figures, forum posts, and task knowledge when available.
 - Use narrow agent session policies with the smallest allowed task/action/parameter scope.
 - Do not commit or apply parameter candidates until a validation task succeeds and the user explicitly confirms.
 - Avoid blind parameter sweeps. If two conservative probes fail, step back to a diagnostic task.
@@ -42,6 +43,8 @@ This skill defines how pi should behave as a conservative, confirmation-gated ca
 
 1. Establish context:
    - profile and chip
+   - active/relevant `cooldown_id` and its time boundaries via `qdash_list_cooldowns`
+   - any in-cooldown wiring changes relevant to the target
    - failed task(s)
    - qid/coupling_id
    - recent executions and open forum/issue context

package/skills/qdash-timeseries-diagnosis/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: qdash-timeseries-diagnosis
+description: Diagnose common-mode drift, shared periodicity, phase relationships, and possible environmental coupling across arbitrary QDash metrics and external sensor CSV logs. Use when calibration metrics oscillate, drift together, appear delayed or anti-correlated, or may be influenced by cryostat/environmental cycles.
+---
+
+# QDash Timeseries Diagnosis
+
+Use this skill for evidence-based multi-timeseries investigation. Keep the
+measurement schema and physical interpretation separate: the comparison tool
+extracts mechanical evidence, while this skill guides conclusions and next
+checks.
+
+## Principles
+
+- Do not hard-code metric names, targets, sensors, units, CSV columns, periods,
+  or timezone assumptions.
+- Preserve both raw and transformed results. A visually clean transformed plot
+  must not replace the raw evidence.
+- Correlation, shared periodicity, and phase alignment establish association,
+  not causal direction.
+- Consider a shared driver when multiple targets and an environmental sensor
+  move together. The sensor itself may be a proxy for an unmeasured actuator,
+  vibration, electrical noise, magnetic noise, or control cycle.
+- Count observed cycles, not raw sample points, when judging periodic evidence.
+- Resolve cooldown boundaries before interpreting drift or shared periodicity. Analyze each cooldown separately by default; never smooth, interpolate, correlate, or fit a period across a cooldown boundary unless an explicit cross-cooldown comparison is intended and clearly reported.
+
+## Workflow
+
+### 1. Fix the investigation scope
+
+Record the reusable scope with `/qdash-investigation-setup` when multiple
+comparison passes are expected. The JSON context accepts arbitrary QDash
+series, CSV mappings, window/timezone, and transform defaults. Record:
+
+- QDash profile and chip
+- cooldown IDs and start/end boundaries from `qdash_list_cooldowns`
+- any in-cooldown wiring events that overlap the window
+- metrics and target IDs
+- tags
+- start/end timestamps
+- timezone for every source
+- expected cadence and units
+- local CSV path, time column, value columns, and any row filters
+
+For timestamps without an explicit zone, require a declared offset. Never infer
+a timezone from the host machine.
+
+### 2. Inspect source integrity
+
+Before comparing, use `qdash_inspect_timeseries_csv` for local files whose
+schema or time encoding is not already established. Use `qdash_list_cooldowns`
+to split the requested window at cooldown boundaries, and inspect cooldown
+wiring events when hardware conditions may have changed. Then:
+
+- verify first/last timestamps and overlap
+- check source point counts and cadence
+- identify duplicate timestamps, missing intervals, and long gaps
+- verify scale and offset conversions
+- ensure labels are unique
+
+Do not bridge long outages. Set `maxInterpolationGapMinutes` explicitly when the
+default is unsuitable for the slowest source.
+
+### 3. Establish a raw baseline
+
+Call `qdash_compare_timeseries` first with:
+
+- no smoothing
+- no detrending
+- no normalization
+- no period search unless a period was specified independently
+
+Report ranges, units, overlap, and raw correlation. Different units are fine for
+correlation, but do not visually overlay incomparable scales without separate
+axes or normalization.
+
+### 4. Compare oscillatory components
+
+When looking for common cycles, rerun with explicit settings such as:
+
+- a smoothing window justified by source cadence
+- `detrend: linear` when slow drift would dominate
+- `normalize: zscore` for shape/phase comparison
+- a period-search range chosen from prior evidence or a broad physically
+  plausible interval
+
+Report all transform settings with the result. Compare:
+
+- full transformed correlation
+- selected shared period
+- per-series periodic explained fraction
+- pairwise phase differences
+- observed cycle count
+
+A near-0° phase difference indicates in-phase periodic components. A near-180°
+difference indicates anti-phase components. Intermediate phase may represent a
+delay, but phase alone does not identify response direction.
+
+### 5. Grade the evidence conservatively
+
+Use qualitative language:
+
+- **weak**: unstable period/phase, low explained fraction, or fewer than about
+  three observed cycles
+- **suggestive**: similar periods with plausible phase but short observation or
+  substantial residual variation
+- **strong association**: repeated common period and stable phase across
+  multiple targets/sensors, with substantial explained fractions
+- **causal evidence**: requires intervention, independently controlled input,
+  repeated response, or evidence excluding plausible shared drivers
+
+These are reasoning categories, not fixed acceptance thresholds. Explain which
+facts support the chosen category.
+
+### 6. Test alternatives
+
+For apparent environmental or cryostat coupling, distinguish:
+
+1. the measured sensor variable directly affecting the metric
+2. a controller/refrigerator cycle affecting both
+3. periodic measurement or scheduling artifacts
+4. timestamp offset or resampling artifacts
+5. target-local behavior coincidentally near the same frequency
+
+Check additional targets in different control/readout groups and, when
+available, actuator state, compressor/pulse-tube, vibration, rack temperature,
+magnetic field, pressure, and control-system logs.
+
+### 7. Recommend discriminating measurements
+
+Prefer measurements that separate hypotheses:
+
+- extend observation to cover at least 8–10 candidate cycles
+- preserve the same cadence and synchronized clocks
+- record actuator/controller state in addition to sensor output
+- test multiple targets and control/readout groups
+- perform a safe controlled setpoint or operating-state change when authorized
+- compare lag/phase stability across independent runs
+
+Do not initiate operational changes without an explicit plan and user
+confirmation.
+
+## Reporting template
+
+Include:
+
+1. sources and exact time window
+2. timezone and unit conversions
+3. raw-data integrity and overlap
+4. transformation settings
+5. raw/transformed correlations
+6. shared period, phase, explained fraction, and observed cycles
+7. strongest association statement
+8. causal alternatives still open
+9. next measurement that best discriminates those alternatives

package/skills/qdash-two-qubit-calibration-diagnosis/SKILL.md

@@ -17,7 +17,8 @@ Use this skill when investigating coupling-level calibration quality, especially
 
 - Treat `completed` as execution status, not proof of calibration quality.
 - Diagnose from evidence before suggesting operational actions.
-- Prefer read-only tools first: `qdash_target_report`, `qdash_list_task_results`, `qdash_get_task_result`, `qdash_analyze_figure_json`, and `qdash_get_task_figures`.
+- Resolve cooldown membership before comparing calibrations or coherence limits. Keep different cooldowns separate, and distinguish a cooldown boundary from an in-cooldown wiring change.
+- Prefer read-only tools first: `qdash_list_cooldowns`, `qdash_target_report`, `qdash_list_task_results`, `qdash_get_task_result`, `qdash_analyze_figure_json`, and `qdash_get_task_figures`.
 - Do not rerun RB first when validation quality is suspicious. Walk back through prerequisites.
 - Do not commit or apply candidates without explicit user confirmation, and only after downstream validation.
 
@@ -25,8 +26,8 @@ Use this skill when investigating coupling-level calibration quality, especially
 
 For a coupling `cA-B`:
 
-1. Build context with `qdash_target_report` and recent task results for the coupling.
-2. Inspect the latest tasks in this chain:
+1. Build context with `qdash_list_cooldowns`, `qdash_target_report`, and recent task results for the coupling. Record the cooldown ID for each result and inspect wiring events when measurement conditions may have changed.
+2. Inspect the latest same-cooldown tasks in this chain by default:
    - `CheckCrossResonance`
    - `CreateZX90`
    - `CheckZX90`