ma-agents 3.4.7 → 3.4.8

package/.opencode/skills/mil498-std/template.md

@@ -0,0 +1,188 @@
+# 1. Scope.
+
+This section shall be divided into the following paragraphs.
+
+## 1.1 Identification.
+
+This paragraph shall contain a full identification of the system and the software to which this document applies, including, as applicable, identification number(s), title(s), abbreviation(s), version number(s), and release number(s).
+
+## 1.2 System overview.
+
+This paragraph shall briefly state the purpose of the system and the software to which this document applies. It shall describe the general nature of the system and software; summarize the history of system development, operation, and maintenance; identify the project sponsor, acquirer, user, developer, and support agencies; identify current and planned operating sites; and list other relevant documents.
+
+## 1.3 Document overview.
+
+This paragraph shall summarize the purpose and contents of this document and shall describe any security or privacy considerations associated with its use.
+
+# 2. Referenced documents.
+
+This section shall list the number, title, revision, and date of all documents referenced in this document. This section shall also identify the source for all documents not available through normal Government stocking activities.
+
+# 3. Test preparations.
+
+This section shall be divided into the following paragraphs. Safety precautions, marked by WARNING or CAUTION, and security and privacy considerations shall be included as applicable.
+
+## 3.x (Project-unique identifier of a test).
+
+This paragraph shall identify a test by project-unique identifier, shall provide a brief description, and shall be divided into the following subparagraphs. When the information required duplicates information previously specified for another test, that information may be referenced rather than repeated.
+
+### 3.x.1 Hardware preparation.
+
+This paragraph shall describe the procedures necessary to prepare the hardware for the test. Reference may be made to published operating manuals for these procedures. The following shall be provided, as applicable:
+
+a. The specific hardware to be used, identified by name and, if applicable, number
+
+b. Any switch settings and cabling necessary to connect the hardware
+
+c. One or more diagrams to show hardware, interconnecting control, and data paths
+
+d. Step-by-step instructions for placing the hardware in a state of readiness
+
+### 3.x.2 Software preparation.
+
+This paragraph shall describe the procedures necessary to prepare the item(s) under test and any related software, including data, for the test. Reference may be made to published software manuals for these procedures. The following information shall be provided, as applicable:
+
+a. The specific software to be used in the test
+
+b. The storage medium of the item(s) under test (e.g., magnetic tape, diskette)
+
+c. The storage medium of any related software (e.g., simulators, test drivers, databases)
+
+d. Instructions for loading the software, including required sequence
+
+e. Instructions for software initialization common to more than one test case
+
+### 3.x.3 Other pre-test preparations.
+
+This paragraph shall describe any other pre-test personnel actions, preparations, or procedures necessary to perform the test.
+
+# 4. Test descriptions.
+
+This section shall be divided into the following paragraphs. Safety precautions, marked by WARNING or CAUTION, and security and privacy considerations shall be included as applicable.
+
+## 4.x (Project-unique identifier of a test).
+
+This paragraph shall identify a test by project-unique identifier and shall be divided into the following subparagraphs. When the required information duplicates information previously provided, that information may be referenced rather than repeated.
+
+### 4.x.y (Project-unique identifier of a test case).
+
+This paragraph shall identify a test case by project-unique identifier, state its purpose, and provide a brief description. The following subparagraphs shall provide a detailed description of the test case.
+
+#### 4.x.y.1 Requirements addressed.
+
+This paragraph shall identify the CSCI or system requirements addressed by the test case. (Alternatively, this information may be provided in 5.a.)
+
+#### 4.x.y.2 Prerequisite conditions.
+
+This paragraph shall identify any prerequisite conditions that must be established prior to performing the test case. The following considerations shall be discussed, as applicable:
+
+a. Hardware and software configuration
+
+b. Flags, initial breakpoints, pointers, control parameters, or initial data to be set/reset prior to test commencement
+
+c. Preset hardware conditions or electrical states necessary to run the test case
+
+d. Initial conditions to be used in making timing measurements
+
+e. Conditioning of the simulated environment
+
+f. Other special conditions peculiar to the test case
+
+#### 4.x.y.3 Test inputs.
+
+This paragraph shall describe the test inputs necessary for the test case. The following shall be provided, as applicable:
+
+a. Name, purpose, and description (e.g., range of values, accuracy) of each test input
+
+b. Source of the test input and the method to be used for selecting the test input
+
+c. Whether the test input is real or simulated
+
+d. Time or event sequence of test input
+
+e. The manner in which the input data will be controlled to:
+
+   1. Test the item(s) with a minimum/reasonable number of data types and values
+   2. Exercise the item(s) with a range of valid data types and values that test for overload, saturation, and other "worst case" effects
+   3. Exercise the item(s) with invalid data types and values to test for appropriate handling of irregular inputs
+   4. Permit retesting, if necessary
+
+#### 4.x.y.4 Expected test results.
+
+This paragraph shall identify all expected test results for the test case. Both intermediate and final test results shall be provided, as applicable.
+
+#### 4.x.y.5 Criteria for evaluating results.
+
+This paragraph shall identify the criteria to be used for evaluating the intermediate and final results of the test case. For each test result, the following information shall be provided, as applicable:
+
+a. The range or accuracy over which an output can vary and still be acceptable
+
+b. Minimum number of combinations or alternatives of input and output conditions that constitute an acceptable test result
+
+c. Maximum/minimum allowable test duration, in terms of time or number of events
+
+d. Maximum number of interrupts, halts, or other system breaks that may occur
+
+e. Allowable severity of processing errors
+
+f. Conditions under which the result is inconclusive and re-testing is to be performed
+
+g. Conditions under which the outputs are to be interpreted as indicating irregularities in input test data, in the test database/data files, or in test procedures
+
+h. Allowable indications of the control, status, and results of the test and the readiness for the next test case (may be output of auxiliary test software)
+
+i. Additional criteria not mentioned above.
+
+#### 4.x.y.6 Test procedure.
+
+This paragraph shall define the test procedure for the test case. The test procedure shall be defined as a series of individually numbered steps listed sequentially in the order in which the steps are to be performed. For convenience in document maintenance, the test procedures may be included as an appendix and referenced in this paragraph. The appropriate level of detail in each test procedure depends on the type of software being tested. For some software, each keystroke may be a separate test procedure step; for most software, each step may include a logically related series of keystrokes or other actions. The appropriate level of detail is the level at which it is useful to specify expected results and compare them to actual results. The following shall be provided for each test procedure, as applicable:
+
+a. Test operator actions and equipment operation required for each step, including commands, as applicable, to:
+
+   1. Initiate the test case and apply test inputs
+   2. Inspect test conditions
+   3. Perform interim evaluations of test results
+   4. Record data
+   5. Halt or interrupt the test case
+   6. Request data dumps or other aids, if needed
+   7. Modify the database/data files
+   8. Repeat the test case if unsuccessful
+   9. Apply alternate modes as required by the test case
+   10. Terminate the test case
+
+b. Expected result and evaluation criteria for each step
+
+c. If the test case addresses multiple requirements, identification of which test procedure step(s) address which requirements. (Alternatively, this information may be provided in 5.)
+
+d. Actions to follow in the event of a program stop or indicated error, such as:
+
+   1. Recording of critical data from indicators for reference purposes
+   2. Halting or pausing time-sensitive test-support software and test apparatus
+   3. Collection of system and operator records of test results
+
+e. Procedures to be used to reduce and analyze test results to accomplish the following, as applicable:
+
+   1. Detect whether an output has been produced
+   2. Identify media and location of data produced by the test case
+   3. Evaluate output as a basis for continuation of test sequence
+   4. Evaluate test output against required output
+
+#### 4.x.y.7 Assumptions and constraints.
+
+This paragraph shall identify any assumptions made and constraints or limitations imposed in the description of the test case due to system or test conditions, such as limitations on timing, interfaces, equipment, personnel, and database/data files. If waivers or exceptions to specified limits and parameters are approved, they shall be identified and this paragraph shall address their effects and impacts upon the test case.
+
+# 5. Requirements traceability.
+
+This paragraph shall contain:
+
+a. Traceability from each test case in this STD to the system or CSCI requirements it addresses. If a test case addresses multiple requirements, traceability from each set of test procedure steps to the requirement(s) addressed. (Alternatively, this traceability may be provided in 4.x.y.1.)
+
+b. Traceability from each system or CSCI requirement covered by this STD to the test case(s) that address it. For CSCI testing, traceability from each CSCI requirement in the CSCI's Software Requirements Specification (SRS) and associated Interface Requirements Specifications (IRSs). For system testing, traceability from each system requirement in the system's System/Subsystem Specification (SSS) and associated IRSs. If a test case addresses multiple requirements, the traceability shall indicate the particular test procedure steps that address each requirement.
+
+# 6. Notes.
+
+This section shall contain any general information that aids in understanding this document (e.g., background information, glossary, rationale). This section shall include an alphabetical listing of all acronyms, abbreviations, and their meanings as used in this document and a list of any terms and definitions needed to understand this document.
+
+# A. Appendixes.
+
+Appendixes may be used to provide information published separately for convenience in document maintenance (e.g., charts, classified data). As applicable, each appendix shall be referenced in the main body of the document where the data would normally have been provided. Appendixes may be bound as separate documents for ease in handling. Appendixes shall be lettered alphabetically (A, B, etc.).

package/.opencode/skills/ml-advise/SKILL.md

@@ -0,0 +1,76 @@
+---
+
+name: ml-advise
+
+description: Acts as Demerzel (Machine Learning Scientist) to search past experiments, retrospectives, and TechSpecs to surface relevant findings, validated parameters, and failure warnings before starting new work.
+
+---
+
+# Machine Learning Workflow: Experiment Advisor — Demerzel
+
+## 1. Operating Instructions
+
+You are **Demerzel**, an expert Machine Learning Scientist with access to the team's accumulated knowledge. Your job is to **prevent redundant experiments** by surfacing everything relevant the team has already learned. You only present findings in the chat — you do not write files.
+
+1. **Read the Research Thesis:** `_bmad-output/planning-artifacts/research-thesis.md`
+   - Active hypothesis (Section II).
+   - Past hypothesis history (Section V).
+   - Domain constraints (Section III).
+
+2. **Scan experiment knowledge sources:**
+   ```bash
+   # Ranked experiment history
+   python3 scripts/summarize_experiment_history.py _bmad-output/implementation-artifacts/ --metric val/f1
+   ```
+
+   Also scanned patterns:
+   - `_bmad-output/implementation-artifacts/ml-analysis-exp-*.md`
+   - `_bmad-output/planning-artifacts/techspecs/ml-techspec-exp-*.md`
+   - `_bmad-output/implementation-artifacts/ml-revision-log.md`
+
+3. **Match findings to the user's current goal.** Identify what worked, what failed, and what parameters were validated in similar contexts.
+
+4. **Present the advisory report directly in chat.** Structure it as follows (see template below). Do not write any files.
+
+5. **Flag gaps:** If no relevant past experiments exist for the user's goal, say so explicitly. Do not fabricate findings.
+
+## 2. Advisory Report Format
+
+Present this report in the chat:
+
+```markdown
+## Experiment Advisory Report
+
+**Goal:** [What the user is about to attempt]
+**Knowledge sources scanned:** [N experiments, M revisions, K TechSpecs]
+
+### What We Already Know
+#### Validated Parameters (copy-paste ready)
+**From EXP-[ID] ([date]):**
+```yaml
+learning_rate: 1e-4
+batch_size: 1024
+warmup_steps: 500
+```
+#### What Worked
+| Finding | Source | Metric |
+| :--- | :--- | :--- |
+| [e.g., Focal Loss alpha=0.25] | EXP-001 | val/f1 = 0.91 |
+
+#### Failure Warnings ⚠️
+| What was tried | Why it failed | Source |
+| :--- | :--- | :--- |
+| [Specific approach] | [Root cause] | EXP-002, REV-003 |
+
+### Recommended Starting Configuration
+[Exact parameter block — copy-paste ready.]
+
+### Open Risks Not Yet Explored
+* [Something the team hasn't tried.]
+* [Data characteristic from EDA not yet addressed.]
+
+### Suggested Experiment Design
+* [Concrete suggestion for parameter sweep.]
+
+**Bottom line:** [One sentence: what the researcher should do first.]
+```

package/.opencode/skills/ml-advise/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: ml-advise
+module: ma-skills

package/.opencode/skills/ml-advise/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "ML Experiment Advisor",
+  "description": "Searches past experiments, retrospectives, and TechSpecs to surface relevant findings and failure warnings.",
+  "version": "1.0.0",
+  "author": "Demerzel (ML Scientist)",
+  "tags": ["Machine Learning", "Advice", "Advisor", "Knowledge", "Demerzel"]
+}

package/.opencode/skills/ml-analysis/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ml-analysis
+description: ML Analysis - Evaluate experiment results against the locked TechSpec contract and produce a verdict
+---
+
+# ML Stage 7 - Analysis (vs TechSpec)
+
+Evaluate results objectively against the locked contract. Do not rationalize failures.
+
+## Instructions
+
+### 1. Load Context
+- Read `_bmad-output/planning-artifacts/ml-techspec.md`
+- Read `_bmad-output/implementation-artifacts/experiment-log.md`
+- Read `_bmad-output/planning-artifacts/ml-prd.md` (failure cost matrix)
+
+### 2. Acceptance Criteria Evaluation
+For each criterion in the TechSpec, produce a verdict table:
+
+| Criterion | Threshold | Achieved | Status |
+|-----------|-----------|----------|--------|
+| Recall    | >= 0.85   | 0.88     | PASS   |
+| AUC-ROC   | >= 0.80   | 0.79     | FAIL   |
+| Beat baseline | Yes   | Yes      | PASS   |
+
+Overall verdict: PASS only if ALL primary criteria pass and NO guardrails are violated.
+
+### 3. Deep Dive Analysis
+Perform and document:
+- **Confusion Matrix**: TP, FP, TN, FN counts and rates
+- **Failure Cost Analysis**: Using the PRD failure cost matrix, calculate actual expected cost per prediction
+- **Error Analysis**: Examine misclassified samples — are there patterns? (demographic, feature range, data quality)
+- **Threshold Sensitivity**: Show primary metric vs decision threshold curve; identify optimal threshold per cost matrix
+- **Feature Importance**: Top 10 features driving predictions (SHAP values or model-native importance)
+- **Overfitting Check**: Compare train vs validation metrics; flag if gap > 10%
+- **Distribution Shift Check**: Compare test feature distributions vs training distributions
+
+### 4. Write Analysis Report
+Write `_bmad-output/implementation-artifacts/analysis-report.md` with all findings and the overall PASS/FAIL verdict.
+
+### 5. Determine Next Step
+- **If PASS**: "All acceptance criteria met. The model is a candidate for deployment review. Proceed to **Stage 8 — /ml-retrospective**."
+- **If FAIL**:
+  - Diagnose root cause: data quality issue? wrong model family? HPO budget too small? Feature engineering gap?
+  - Propose specific actionable remediation
+  - Ask: "Would you like to loop back to Stage 3 (architecture), Stage 4 (adjust TechSpec thresholds with justification), or Stage 6 (rerun with adjusted HPO)?"
+  - Note: Adjusting TechSpec thresholds requires explicit user acknowledgement that the contract is being changed and why
+
+### 6. Surface Dilemmas & Commit Gate
+
+Before presenting and **before any git commit**:
+
+- Identify every analytical judgement call where two or more interpretations existed (threshold selection rationale, error pattern root cause, overfitting diagnosis, remediation path selection, etc.)
+- Format each as: **Dilemma [Letter] — Title** / **Context** / **Options (a/b)** / **Recommendation** / **Your decision:** [blank]
+- If all choices were unambiguous, state explicitly: "No open dilemmas."
+- **Do NOT commit the analysis report until the user has reviewed and approved.**
+
+### 7. Confirm and Advance
+- Present analysis report
+- STOP and WAIT for user decision on next step

package/.opencode/skills/ml-analysis/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: ml-analysis
+module: ma-skills

package/.opencode/skills/ml-analysis/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "ML Experiment Analysis",
+  "description": "Analyzes experiment results against the TECHSPEC, evaluates the hypothesis, and identifies failure modes.",
+  "version": "1.0.0",
+  "author": "Demerzel (ML Scientist)",
+  "tags": ["Machine Learning", "Analysis", "Evaluation", "Hypothesis Testing", "Demerzel"]
+}

package/.opencode/skills/ml-architecture/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ml-architecture
+description: ML Architecture — Define the model stack, feature engineering strategy, and training pipeline design
+---
+
+# ML Stage 3 — Architecture Design
+
+Define the full technical stack before writing any training code.
+
+## Instructions
+
+### 1. Load Context
+- Read `_bmad-output/planning-artifacts/eda-report.md`
+- Read `_bmad-output/planning-artifacts/ml-prd.md` (success metrics, failure cost matrix)
+- Ask the user: "Do you have a preferred model family? (e.g. XGBoost, LightGBM, sklearn, PyTorch, Transformers, or let me recommend)"
+
+### 2. Recommend Architecture
+Based on data characteristics from EDA, recommend:
+- **Model family** with justification (tabular → gradient boosting; unstructured → deep learning; etc.)
+- **Baseline model** (logistic regression / dummy classifier) — always required as sanity check
+- **Candidate models** (1–3 options with trade-offs)
+- **Feature engineering strategy**: encoding, scaling, imputation, feature selection approach
+- **Class imbalance strategy**: class_weight, SMOTE, threshold tuning — choose based on failure cost matrix
+- **Validation strategy**: stratified k-fold, time-series split, or held-out — justify choice
+
+### 3. Define Dependencies
+Provide `uv add` commands for required packages:
+- Core ML library (e.g. `xgboost`, `lightgbm`, `scikit-learn`)
+- Tracking tool already configured (wandb / mlflow / clearml / none)
+- Supporting libraries (optuna for HPO, shap for explainability if needed)
+
+### 4. Write Architecture Document
+Write `_bmad-output/planning-artifacts/ml-architecture.md` with:
+- **Selected Stack**: Model family, libraries, versions
+- **Feature Engineering Pipeline**: steps in order with rationale
+- **Training Pipeline Design**: train/val/test split strategy, CV folds
+- **Hyperparameter Space**: list of HPO parameters and search ranges
+- **Explainability Plan**: how predictions will be explained (SHAP, feature importance, etc.)
+- **Experiment Tracking**: which metrics will be logged and to which tool
+- **Rejected Alternatives**: models considered but rejected, with reasons
+
+### 5. Surface Dilemmas & Commit Gate
+
+Before presenting and **before any git commit**:
+
+- Identify every architectural choice where two or more reasonable options existed (model family, HPO objective, imbalance strategy, CV folds, Stage 2 model, tracking tool, feature encoding, etc.)
+- Format each as: **Dilemma [Letter] — Title** / **Context** / **Options (a/b)** / **Recommendation** / **Your decision:** [blank]
+- If all choices were unambiguous, state explicitly: "No open dilemmas."
+- **Do NOT commit the architecture document or install dependencies until the user has responded and given explicit approval.**
+
+### 6. Confirm & Advance
+- Present architecture document for review
+- Ask: "Do you approve this stack, or would you like to adjust the model choice or validation strategy?"
+- On approval: commit artifacts, then say "Stage 3 complete. Proceed to **Stage 4 — /ml-techspec** to lock the experiment contract."
+- STOP and WAIT for user confirmation

package/.opencode/skills/ml-architecture/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: ml-architecture
+module: ma-skills

package/.opencode/skills/ml-architecture/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "ML Architecture Design",
+  "description": "Selects the model stack, experiment tracking tools, and defines the system-level ML architecture.",
+  "version": "1.0.0",
+  "author": "Aris (AI Scientist)",
+  "tags": ["Machine Learning", "Architecture", "System Design", "Models"]
+}

package/.opencode/skills/ml-detailed-design/SKILL.md

@@ -0,0 +1,67 @@
+---
+
+name: ml-detailed-design
+
+description: Acts as Demerzel (Machine Learning Scientist / Tech Lead) to break down the approved architecture into granular sub-agent tasks, separated into infrastructure tasks (INF-*) and experiment tasks (EXP-*).
+
+---
+
+# Machine Learning Workflow: Detailed Design & Task Breakdown — Demerzel
+
+## 1. Operating Instructions
+
+You are **Demerzel**, an expert Machine Learning Scientist and Tech Lead. Your goal is to break down the architecture into manageable tasks assigned to specific agent personas, using a clear task namespace that separates infrastructure work from experimental work.
+
+**Task namespaces:**
+- `INF-001`, `INF-002`, ... — Infrastructure tasks executed by `ml-infra`. built once. Examples: data pipeline, training loop scaffold, experiment tracking wiring, evaluation harness, inference API.
+- `EXP-001`, `EXP-002`, ... — Experiment tasks executed by `ml-experiment`. These are executed in each experiment cycle. Examples: training runs, ablation studies, model variants.
+- `REV-001`, `REV-002`, ... — Revision tasks generated by `ml-revision`.
+
+1. Locate and read `_bmad-output/planning-artifacts/research-thesis.md`, `ml-prd.md`, `eda-report.md`, and `ml-architecture.md`.
+
+2. Produce two task groups:
+   **Group A — Infrastructure (INF-*):** Everything built before any training run. Each INF task must specify its Definition of Done (smoke test). Include experiment tracking config as a mandatory INF task.
+   **Group B — Experiments (EXP-*):** Initial training runs defined by the first hypothesis. These reference the infrastructure built in Group A.
+
+   Assign tasks to roles: `Data-Agent`, `Model-Agent`, `MLOps-Agent`.
+
+3. **CRITICAL:** Do not generate the final file yet. Present the draft task list and ask the user to confirm granularity. Halt and wait.
+
+4. Once approved, write the final document to `_bmad-output/planning-artifacts/ml-detailed-design.md`.
+
+5. **Run design validation:**
+   ```bash
+   python3 scripts/validate_design.py _bmad-output/planning-artifacts/ml-detailed-design.md
+   ```
+
+6. **Commit the design artifacts:**
+   ```bash
+   git add _bmad-output/planning-artifacts/ml-detailed-design.md
+   git commit -m "docs(ml-detailed-design): task breakdown INF-* and EXP-* with definitions of done"
+   ```
+
+## 2. Expected Output Template
+
+### Template A: `_bmad-output/planning-artifacts/ml-detailed-design.md`
+
+```markdown
+### A. Infrastructure Tasks (INF-*)
+| Task ID | Assigned Agent | Task Description | Definition of Done | Linked Req | Dependencies | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| `INF-001` | `Data-Agent` | Implement Dataset + DataLoader with augmentation from EDA. | Smoke test: DataLoader yields correct shapes with dummy data. | `REQ-DATA-01` | None | Pending |
+| `INF-002` | `MLOps-Agent` | Wire experiment tracking (W&B/MLflow) into Trainer. | Tracking test: run creates a logged run in UI. | `REQ-ML-01` | `INF-001` | Pending |
+| `INF-003` | `Model-Agent` | Implement model scaffold from architecture design. | Smoke test: forward pass succeeds with dummy batch. | `REQ-ML-01` | `INF-001` | Pending |
+
+### B. Experiment Tasks (EXP-*)
+| Task ID | Assigned Agent | Task Description | Linked Req | Dependencies | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `EXP-001` | `Model-Agent` | Baseline training run: single config from TECHSPEC. | `REQ-ML-01` | All INF-* complete | Pending |
+| `EXP-002` | `Model-Agent` | [Variant defined after EXP-001] | [REQ-ID] | `EXP-001` + Analysis | Pending |
+
+### C. Merge & Validation Strategy
+* **Pre-Merge for INF:** Smoke test passes, unit tests written.
+* **Pre-Merge for EXP:** Run logged to tracking tool with run URL.
+
+### D. Clarification & Decision Log
+* **Q1:** [Question] -> **User Decision:** [Answer]
+```

package/.opencode/skills/ml-detailed-design/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: ml-detailed-design
+module: ma-skills

package/.opencode/skills/ml-detailed-design/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "ML Detailed Design & Task Breakdown",
+  "description": "Breaks down the architecture into infrastructure (INF-*) and experiment (EXP-*) tasks.",
+  "version": "1.0.0",
+  "author": "Demerzel (ML Scientist)",
+  "tags": ["Machine Learning", "Detailed Design", "Task Breakdown", "INF", "EXP"]
+}

package/.opencode/skills/ml-eda/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ml-eda
+description: ML EDA — Exploratory Data Analysis and Research Thesis validation
+---
+
+# ML Stage 2 — EDA & Research Thesis
+
+No modelling without high-quality EDA. This stage validates the data against the research thesis.
+
+## Instructions
+
+### 1. Load Context
+- Read `_bmad-output/planning-artifacts/research-thesis.md` — understand the hypothesis and target variable
+- Read `_bmad-output/planning-artifacts/ml-prd.md` — understand the success metrics and failure cost matrix
+- Confirm raw data path with the user (default: `data/raw/`)
+
+### 2. Run EDA Script
+- If `scripts/eda_analyzer.py` exists, execute it: `uv run python scripts/eda_analyzer.py`
+- If it does not exist, write a minimal `scripts/eda_analyzer.py` that:
+  - Loads the dataset
+  - Prints shape, dtypes, null counts
+  - Plots target distribution
+  - Computes correlation matrix for numeric features
+  - Saves outputs to `_bmad-output/planning-artifacts/eda-figures/`
+
+### 3. Analyze and Document
+Write `_bmad-output/planning-artifacts/eda-report.md` covering:
+- **Dataset Summary**: rows, columns, memory size, time range if applicable
+- **Target Variable Analysis**: class distribution, imbalance ratio, label quality
+- **Feature Analysis**:
+  - Numeric: distribution, outliers, missing rate
+  - Categorical: cardinality, dominant categories, missing rate
+- **Correlations**: Top features correlated with target; multicollinearity flags
+- **Data Quality Issues**: missing data patterns, duplicates, label leakage risks
+- **Class Imbalance**: If imbalance > 1:5, document recommended mitigation (oversampling, class weights, threshold tuning)
+- **Hypothesis Validation**: For each assumption in `research-thesis.md`, state CONFIRMED / CHALLENGED / UNKNOWN with evidence
+
+### 4. Update Research Thesis
+- If EDA challenges any assumption, update `research-thesis.md` with revised hypothesis and note the evidence
+- Document any features that should be excluded (leakage, zero-variance, etc.)
+
+### 5. Surface Dilemmas & Commit Gate
+
+Before presenting and **before any git commit**:
+
+- Identify every data or preprocessing decision where two or more reasonable options existed (missing value strategy, feature exclusion, class imbalance approach, hypothesis revisions, etc.)
+- Format each as: **Dilemma [Letter] — Title** / **Context** / **Options (a/b/c)** / **Recommendation** / **Your decision:** [blank]
+- If all choices were unambiguous, state explicitly: "No open dilemmas."
+- **Do NOT commit any artifact (report, figures, updated thesis) until the user has responded and given explicit approval.**
+
+### 6. Confirm & Advance
+- Present EDA findings summary to the user
+- Highlight any critical data quality issues that could block modelling
+- Ask: "Does this EDA align with your expectations? Any features to add or exclude?"
+- On approval: commit all artifacts, then say "Stage 2 complete. Proceed to **Stage 3 — /ml-architecture** to design the model stack."
+- STOP and WAIT for user confirmation

package/.opencode/skills/ml-eda/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: ml-eda
+module: ma-skills