Ds Eda

Evidence-Driven EDA

Turn requirements into the smallest set of investigations that can change a decision. Do not produce a generic profile, chart gallery, or modeling plan.

Read references/plot-selection.md when an investigation needs a visual.

Input Gate

Start from a ready user_requirements.md or an equivalent authoritative requirements artifact. If the decision, target, grain, time boundary, or population needed for the requested EDA is unresolved, reject execution and return the blocking requirement questions. Do not invent semantics from column names.

This skill may help $ds-timeseries satisfy its EDA gate, but it does not own the research or experiment-decision gates.

Design The Investigation Ledger

Trace each objective to one or more REQ-* IDs. Keep only objectives whose answers can confirm or challenge a requirement, target, population, feature availability rule, validation boundary, or later experiment decision.

For each objective record:

objective ID:
requirement IDs:
question and decision affected:
grain and entity key:
population, filters, and denominator:
fields and time boundary:
metric or test:
table or plot and why it fits:
possible outcomes and next action:

Choose The Investigation Family

Use one or more families only when linked requirements need them:

• Semantic and target EDA: lock the prediction contract; test event or row keys; construct the target; preserve exclusions and coverage; distinguish lifecycle and time semantics; prove cutoff availability and leakage policy.
• Panel and readiness EDA: inspect representative series, demand shape, missing versus structural zero, sparsity, cold start, lifecycle, drift, events, and whether the volume-supported population justifies modeling.
• Completed-experiment EDA: verify input readiness and comparison fairness; report overall, horizon, split or event, and material segment behavior; decompose errors at meaningful pipeline boundaries; test diagnostic alternatives without silently promoting another experiment.

Rank semantic and boundary risks before descriptive detail. Include only checks connected to the actual requirements.

Completed-Experiment Comparisons

Before ranking methods, verify a common target, grain, cutoffs, forecast dates, horizons, entity population, and split roles. Keep pipeline and model identities distinct when names can collide.

• Use untouched held-out results for headline findings. Label selection splits, all-fold summaries, threshold searches, and quantile searches diagnostic.
• Rank on the intersection shared by every compared method. Report each method's native coverage separately so omission is not rewarded.
• Pair aggregate error with horizon, split, event, bias, and material segment evidence when those views can change the conclusion.
• Show segment support beside segment error. A dramatic small segment is an investigation candidate, not automatically the next priority.
• Decompose error at the earliest meaningful boundary, such as occurrence versus positive magnitude, total versus allocation, or model output versus rounding. Diagnose before proposing more complexity.
• Label actual-total, oracle, replay, optimistic, full-history, and post-hoc analyses as diagnostic or falsification evidence, never deployable results.

This skill may state which completed method wins the declared comparison and where it fails. Hand those findings to $ds-timeseries; do not choose the next experiment here.

Notebook Protocol

Reuse the repository's existing notebook format, source file, loading boundary, and execution method. Deciding libraries or replacing notebook infrastructure is outside this skill.

Every substantive notebook section must contain:

1. A markdown question, EDA-OBJ-* ID, linked REQ-* IDs, and why the answer matters.
2. A preparation step that establishes the grain, population, denominator, and time boundary and asserts critical invariants.
3. The smallest evidence table needed to verify exact values.
4. At most one primary plot unless another view answers a distinct question.
5. A finding with evidence, caveat, affected requirement, and next action.

Each code cell must serve the stated objective. Reject cells that exist only to display another summary, repeat a table as a chart, or explore without a decision-relevant question.

In Plan mode, inspect the data contract and notebook workflow, then return a decision-complete implementation and execution plan. Do not write or execute. Outside Plan mode, implement the agreed investigations, execute the notebook, and fix failures before accepting findings.

Produce eda_findings.md

After a clean execution, extract only supported findings. For each EDA-F-* record:

• its EDA-OBJ-* and REQ-* IDs;
• its investigation family and evidence role;
• observed result at the verified grain and population;
• notebook section, cell, figure, table, or derived-artifact reference;
• date coverage and denominator where relevant;
• common-grid population and native coverage for method comparisons;
• interpretation, caveat, and implication;
• whether it supports readiness, identifies a failure mechanism, falsifies an approach, or leaves the requirement unresolved.

Maintain REQ-* -> EDA-OBJ-* -> EDA-F-* traceability. Label associations as predictive or descriptive unless a causal design exists.

The result is not ready when the notebook is unexecuted, errors remain, a finding lacks evidence provenance, important coverage is hidden, or a relevant semantic/time/leakage risk is merely assumed away. A code-only notebook or a partially executed analysis can inform a future investigation plan but cannot produce a ready findings artifact.

Scope Boundary

Reject a request whose primary job is experiment selection, literature research, package selection, model implementation, repository refactoring, TDD, or code review. For a mixed request, perform only the EDA portion and state the handoff for the rest.