docs: add the missing time-series classification section to how-training-works

[LukasWodka]

Summary

how-training-works.mdx had per-use-case accordions for 9 use cases but none for time-series classification, even though the TSC epic shipped to production on 2026-07-11 and the model zoo ships TSC templates. This adds the tenth accordion, following the existing structure (Frameworks / Input / Preprocessing / Train-validation split / Training step / Cycle metrics / Inference output).

Every fact is sourced from the engine code on tracebloc-enginedevelop:

• core/datasets/loaders/time_series_classification_loader.py — input contract (sequence_id/timestamp/label, label constant per sequence)
• core/datasets/preprocessors/time_series_classification_preprocessor.py — per-sequence forward-fill imputation + leading-gap fallbacks, sequence_id/timestamp detach, SequenceFeatureScalingStep
• core/domains/time_series_classification/{base,pytorch_strategy}.py — sequence-level stratified split, WeightedRandomSampler class-imbalance mechanism, loss dispatch, threshold gradient clipping
• core/datasets/time_series_classification_dataset_pytorch.py — scale-first-then-pad, zero post-pad / tail-keep truncate, no auto-shrink
• core/metrics/registry.py — verbatim reuse of TabularClassificationMetrics

Two supporting touches on the same page: the forecasting accordion title is hyphenated to match the TERMINOLOGY.md task display names ("Time-series forecasting"), and the local-reproduction split-strategy step now distinguishes the two time-series splits.

Related

• Ref tracebloc/backend#1054 (TSC epic)
• Ref docs: PreprocessingConfig knobs — fix stale claims + document the six levers #65 — flags this gap; see sequencing note below

Content-rule notes (for review)

• missingness_indicators is deliberately NOT documented. tracebloc/tracebloc-engine#508 (opt-in missingness-indicator channels) is still open, so per the shipped-to-prod content rule it must not appear here yet. Add it in a follow-up once #508 ships. ⚠️ Note: PR docs: PreprocessingConfig knobs — fix stale claims + document the six levers #65 currently documents that knob in hyperparameters.mdx — its merge should be sequenced with engine#508.
• Scaler default: the accordion says an untouched experiment runs with Min-Max scaling. That is the as-shipped SDK behavior (the SDK always sends scaler=MinMaxScaler on the time-series key; the engine's internal StandardScaler fallback only fires when the field is empty, which SDK-driven runs never hit).
• No numeric sequence_length default is claimed — SDK, backend model, and engine fallbacks disagree (24 / 25 / 60), so the text points readers at the experiment view instead. The forecasting accordion's existing "default 60" claim has the same fragility; left untouched here.
• strict_label_set exists engine-side but is not SDK-exposed, so the strict behavior is documented as fixed rather than as a knob.

Type of change

• Docs

Test plan

• Accordion/tag balance verified (10 <Accordion> / 10 </Accordion>); structure and component usage mirror the existing nine sections
• Content cross-checked line-by-line against the engine sources listed above, plus the SDK (tracebloc/training/shape.py, preprocessing.py, submitter.py) and backend Experiment model for the effective knob defaults
• No new links added (nothing for mint broken-links to break)

Checklist

• Docs updated if behavior or config changed
• No secrets / credentials in the diff

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes with no runtime, config, or API impact.

Overview
Adds the missing Time-series classification accordion to how-training-works.mdx, matching the structure of the other nine use cases and documenting input contract (sequence_id / timestamp / per-sequence label), preprocessing (per-sequence imputation, scale-then-pad/truncate, frozen cycle-1 state), sequence-level stratified splits, WeightedRandomSampler (not loss reweighting), training/validation behavior, tabular-classification-aligned cycle metrics, and inference.

Also renames the forecasting accordion to Time-series forecasting for terminology consistency, and updates the local-reproduction step to separate temporal splits for forecasting from sequence-level stratified splits for time-series classification.

^{Reviewed by Cursor Bugbot for commit d0fbde0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tracebloc	🟢 Ready	View Preview	Jul 23, 2026, 9:09 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[divyasinghds]

Pushed d0fbde0: added the platform-canonical sequence-length default (25) + template-override rule to the TSC sequence-assembly step, for parity with the forecasting section (docs#67). Now that backend#1196 ratified Option A, both TS sections name the same default.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tracebloc	🟡 Building	–	Jul 23, 2026, 9:09 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[shujaatTracebloc]

Review — TSC section in how-training-works

Excellent, carefully-sourced addition. I've been deep in the TSC engine path recently (imputation, scaler, and cross-repo consistency work), so I checked the load-bearing claims against the actual code rather than just the prose — and they hold up, including the subtle ones:

Verified accurate

• Categorical leading-gap fallback = "most frequent observed value." ✅ This matches the current behavior — the leading-gap categorical fill is the column mode, not a "Unknown" sentinel (engine #476). A doc written against the older code would have said "Unknown"; this is right.
• Numeric leading-gap = median, honoring a configured strategy, knn/iterative → median. ✅ Matches _leading_fill_value.
• "Min-Max unless you change it." ✅ Correct as the SDK-driven default — the SDK sends MinMaxScaler on the time-series key; the engine's internal StandardScaler fallback only fires on an empty field, which SDK runs never leave empty. Good call documenting the effective behavior, not the engine fallback. (And QuantileTransformer is correctly not listed — it's refused platform-wide on privacy grounds.)
• Scale-first-then-pad, zero post-pad, tail-keep truncate, never auto-shrunk (FL shape contract). ✅ Matches the dataset (backend#1054 Decision-1).
• Sequence-level stratified split + fallback to random/clamped. ✅
• Weighted random sampler for imbalance, loss not reweighted, no synthetic samples. ✅ — and the explicit contrast with image/tabular is a genuinely useful clarification.
• Grad-clip only when global norm > 10; non-finite loss skips the update; single-sequence batch skipped (batchnorm). ✅
• Metrics reuse TabularClassificationMetrics; argmax / sigmoid>0.5; frozen preprocessing replayed at inference. ✅
• Accordion balance + the two supporting touches (hyphenated "Time-series forecasting", split-strategy step) are consistent.

One thing to reconcile (minor):
The sequence_length paragraph says "when neither your model template nor the notebook sets it, the platform default of 25 applies … read the value your experiment ran with from the experiment view." But the PR description says "No numeric sequence_length default is claimed … points readers at the experiment view instead" — so the text and the stated intent disagree. And it genuinely is ambiguous: the SDK's sequence_length defaults to None and the submitter sends that None when unset (training/submitter.py), so an untouched run falls through to an engine-side fallback — not a value the SDK pins (unlike the scaler, which the SDK always sends). So "25" isn't the SDK-sent default the way "Min-Max" is.

Suggest either (a) drop the specific "25" and keep only the "read it from the experiment view" pointer (matching the description's stated approach), or (b) if you've confirmed the engine's TSC fallback is exactly 25, say "the engine falls back to 25" rather than "the platform default of 25" — to mirror how you (correctly) handled the scaler default. Not blocking; the experiment-view pointer already protects the reader.

Otherwise LGTM — approve once the sequence_length wording is squared away. 🚀

🤖 Reviewed with Claude Code