# ML Conventions (Override Skill Defaults)

> **MANDATORY:** These rules override ANY upstream skill default (including `writing-plans`, `generate-spec`, `train-model`, `evaluate-model`, and all superpowers skills).
> Read this file before writing any output file during the ML Gate Workflow.

---

## ML Plan Output Paths

ML tickets share the **same** `AK-Docs/04.Coding/` folders as the standard Dev workflow (see `project-conventions.md`) — no separate ML section:

| Output | Path | Note |
|--------|------|------|
| ML problem doc | `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` | Gate 1 output |
| Experiment plan | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` | Gate 2 output — **NOT** `docs/superpowers/plans/`, **NOT** `plan/` |
| Evaluation report + model card | `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` | Gate 4 output — include the model card draft in the same file, under its own section |

> `[functionId]` và `[ticketId]` được xác định theo đúng quy tắc "functionId & ticketId" trong `project-conventions.md` — **BẮT BUỘC xác định ở Gate 1 trước khi ghi file đầu tiên.**
> `plan/[ticket-id]/...` (đường dẫn cũ) đã **DEPRECATED** — không được ghi output mới vào `plan/`. Chỉ code/notebook/model artifact thật (Gate 3 training) mới nằm ngoài `AK-Docs`, theo mục "Data & Model Versioning" bên dưới.

---

## Reproducibility Rules

Every experiment must be fully reproducible from its logged artifacts alone:

- **Set all seeds** before any randomness: `random.seed(n)`, `numpy.random.seed(n)`, and the framework seed (`torch.manual_seed(n)`, `tf.random.set_seed(n)`).
- **Enable deterministic flags** where feasible (`torch.use_deterministic_algorithms(True)`; note and document any performance trade-off).
- **Pin the environment:** `requirements.txt` or a lockfile must be committed alongside every model artifact.
- **Log seed, config, and commit SHA** with every tracked run — a run is not reproducible unless these three are recorded.

---

## Experiment Naming Scheme

Pattern: `[ticket-id]_[approach]_[yyyymmdd-n]`

- `[ticket-id]` — Jira/linear ticket key (from `.aiflow/context/current.json`)
- `[approach]` — short slug describing the method (lowercase, hyphens, no spaces)
- `[yyyymmdd-n]` — date + 1-based daily sequence counter

**Concrete example:**

```
ML-42_lgbm-tfidf_20241115-1
ML-42_lgbm-tfidf_20241115-2
ML-42_bert-finetune_20241116-1
```

Use this name as the MLflow `run_name` / wandb `run` name and as the artifact folder name under `experiments/`.

---

## Data & Model Versioning

- **Datasets** must be versioned with DVC (or an equivalent registry). Never commit raw data or large processed files to git.
- **Model artifacts** must be registered in the artifact store (MLflow Model Registry, DVC, or equivalent). Record the data version used to produce each artifact.
- Each artifact's metadata must include: data version, code commit SHA, config file path, and eval metric.
- `models/` and `data/` directories are git-ignored; tracked via DVC or the registry instead.

---

## Anti-Leakage Rules (Hard Rules)

These rules are non-negotiable and override any convenience shortcut:

- **Split before fit** — perform the train/validation/test split BEFORE fitting any transformer, imputer, scaler, or encoder.
- **Fit transforms on train only** — all preprocessing must live inside a `Pipeline` that is fit exclusively on the training fold. Never fit on the full dataset and then split.
- **No target leakage** — features must not be derived from or computed after the prediction target. Explicitly check every feature's availability time relative to the target.
- **No temporal leakage** — for time-series data, use time-aware splits (no future data for past predictions). Validate that no feature uses information from future time steps.
- **Test set is held-out** — the test set is touched only at Gate 4 evaluation. No hyperparameter tuning, no feature selection, and no threshold selection on the test set.

---

## Checklist Before Writing Any Output File

Before saving any ML plan, experiment plan, or eval report, verify:

- [ ] Output path follows the table above — NOT the skill's default path, NOT the legacy `plan/` folder
- [ ] `functionId` đã được xác định/xác nhận ở Gate 1 (xem `project-conventions.md`)
- [ ] `[ticketId]` is read from `.aiflow/context/current.json`
- [ ] Directory `AK-Docs/04.Coding/<section>/[functionId]/` exists or will be created
- [ ] Announced path in the handoff message matches the actual saved path

---

## Other Conventions

- **Code style:** `custom/rules/code-style.md`
- **Naming:** `custom/rules/naming.md`