@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/ml_engineer/phases.md

@@ -0,0 +1,1068 @@
+# ML Engineer — Phased Workflow
+
+Phases 1 through 8 for the ML Engineer. Phase 0 (Triage) is already complete.
+Follow every phase, gate, and documentation rule below.
+
+---
+
+## Phase 1 — Business Requirements
+
+Goal: Ground the ML system in a business problem, not a technology choice.
+
+Ask about:
+- What business problem does this solve? Who benefits?
+- What's the current solution? (rule-based, manual, nothing)
+- What's the decision or action the model output drives?
+- Who are the end users of the model's predictions? (internal system, customer-facing,
+  analyst dashboard, API consumer)
+- What's the cost of a wrong prediction? (false positive vs. false negative asymmetry)
+- What's the success metric from the business perspective? (not model metrics —
+  business KPIs like conversion rate, revenue, time saved)
+
+### Document Phase 1
+
+```markdown
+---
+
+## Phase 1: Business Requirements (ML Engineer)
+- **Business problem:** <what this solves>
+- **Current solution:** <rule-based | manual | none | existing ML — describe>
+- **Decision driven by model:** <what action the output triggers>
+- **End users:** <internal system | customer-facing | analyst | API consumer>
+- **Cost of wrong prediction:**
+  - False positive: <business impact>
+  - False negative: <business impact>
+- **Business success metric:** <KPI and target, not model metrics>
+- **Business priority:** Critical | High | Medium
+```
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase1 phase=1 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 2 — Scope and Constraints
+
+Goal: Define the technical boundaries and infrastructure realities.
+
+Ask about:
+- **Serving mode:** Real-time (synchronous API) | Near-real-time (streaming) |
+  Batch (scheduled predictions) | Hybrid
+- **Latency budget:** (for real-time) p50, p95, p99 targets
+- **Throughput:** Expected QPS or batch volume
+- **Memory budget:** Max model size, max feature vector size, concurrent instances
+- **Compute budget:** GPU vs. CPU, cost constraints, cloud vs. on-prem
+- **Existing infrastructure:** Model registry, feature store, serving framework,
+  orchestration (Airflow, etc.), monitoring
+- **Data freshness requirements:** How stale can features be at inference time?
+- **Fallback strategy:** What happens when the model is unavailable?
+- **Compliance / fairness:** Any regulatory constraints? Protected attributes?
+  Explainability requirements?
+
+**Consult the Data Engineer** for pipeline feasibility:
+
+Tell the user: "Getting the Data Engineer shard in here — I need to know what the feature pipeline can actually support before I design against a fiction."
+
+```
+Task(
+  subagent_type="data-engineer",
+  description="Review ML pipeline feasibility",
+  prompt="I am the ML Engineer shard scoping an ML project: [project description].
+  I need to understand the existing data pipeline infrastructure. Please tell me:
+  1. What orchestration exists (Airflow, dbt, etc.)?
+  2. What's the current pipeline cadence for key tables?
+  3. Is there a feature store or any feature serving infrastructure?
+  4. What are the realistic constraints for adding new pipeline steps?
+  5. Any known bottlenecks or capacity issues?
+  Keep the response focused and practical."
+)
+```
+
+### Document Phase 2
+
+```markdown
+---
+
+## Phase 2: Scope and Constraints (ML Engineer)
+- **Serving mode:** Real-time | Near-real-time | Batch | Hybrid
+- **Latency budget:** p50: <X>ms | p95: <X>ms | p99: <X>ms (or "N/A — batch")
+- **Throughput:** <QPS or batch volume>
+- **Memory budget:** Model: <X>MB | Features: <X>MB | Instances: <N>
+- **Compute:** GPU | CPU — <constraints>
+- **Existing infrastructure:**
+  - Model registry: <exists | needs setup — details>
+  - Feature store: <exists | needs setup | N/A>
+  - Serving: <framework or "needs design">
+  - Orchestration: <tool and cadence>
+  - Monitoring: <exists | needs setup>
+- **Data freshness at inference:** <real-time | <X> minutes | <X> hours | daily>
+- **Fallback strategy:** <rule-based default | cached predictions | graceful degradation | TBD>
+- **Compliance / fairness:** <constraints or "none identified">
+- **Data Engineer consultation:**
+  - <summary of pipeline feasibility findings>
+```
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase2 phase=2 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 3 — Data and Feature Discovery
+
+Goal: Understand what data is available for features and labels.
+
+**If productionization from study:** The Data Scientist has already completed feature
+discovery. Start by reading the study's Phase 2 (Data Discovery) and Phase 4 (Modeling
+Approach) from the study's `project-specs.md`. Present the inherited feature set to the
+user, then focus this phase on the **production-specific gap**:
+- Which study features are available at the required inference latency?
+- Which features need real-time alternatives or pre-computation?
+- Are there features the study used that cannot be productionized?
+Still consult the Data Modeller, but scope the consultation to serving-time data
+availability rather than full discovery.
+
+**Otherwise (greenfield or iteration):** proceed as below.
+
+**Consult the Data Modeller:**
+
+Tell the user: "Pulling in the Data Modeller. Feature definitions have to be grounded in actual data models, not what we hope exists."
+
+```
+Task(
+  subagent_type="data-modeller",
+  description="Explore data model for ML features",
+  prompt="I am the ML Engineer shard building an ML system for [purpose]. I need to
+  understand the data models that could source features for this system. Specifically:
+  1. What tables capture [relevant entities and events]?
+  2. What's the grain and freshness of each?
+  3. How do they relate to each other (join keys, cardinality)?
+  4. Any data quality concerns?
+  5. Which tables are available in real-time vs. batch only?
+  Focus on: [specific entities, events, or business concepts].
+  Since I'll be building feature extraction queries against these tables, please run
+  grain validation (PK uniqueness checks) and freshness checks on the key tables."
+)
+```
+
+**Greenfield handling:** Applies to greenfield and iteration projects only. If this is
+a productionization from a study, skip — the study is the data source.
+
+For greenfield and iteration: check whether the Data Modeller's response contains
+"NO DATA ENVIRONMENT DETECTED".
+
+If it does:
+1. Present the Data Modeller's response to the user.
+2. Ask:
+   "The Data Modeller found no data assets in this project. For an ML system, data
+   is the foundation of every feature and training decision.
+   - (a) Feature data exists in your warehouse — tell me what entities and events
+     are available. I'll design feature extraction from there.
+   - (b) Data exists but schema details aren't available right now — I can design
+     the feature architecture and model approach; actual queries and training will wait.
+   - (c) No data exists yet — I can produce a full ML architecture design, but
+     nothing will train or serve real predictions until data is available.
+   Which situation are we in?"
+3. Wait for the user's response before proceeding.
+   - (a): proceed with provided context.
+   - (b): proceed with caveats. Flag feature availability column in Phase 3 docs as
+     "Unverified — user-described." Add:
+     `**Data environment:** Feature data exists but inaccessible — candidates user-described, not verified.`
+   - (c): tell the user: "This will be an ML architecture design document. I can
+     define feature requirements, label definition, model architecture, and
+     infrastructure design — but the model cannot train and feature queries cannot
+     run until data exists. All feature candidates will be flagged
+     [THEORETICAL — DATA NOT AVAILABLE]. Do you want to proceed on that basis?"
+     Wait for confirmation. Add:
+     `**Data environment:** GREENFIELD — No data assets detected. Theoretical ML design only.`
+
+Present findings, then ask:
+- **Label definition:** How is the target variable defined? Where does ground truth come from?
+  Is there label delay (e.g., churn only observable 90 days later)?
+- **Feature candidates:** What signals could predict the target? Group by:
+  - User/entity attributes (demographic, account-level)
+  - Behavioral features (engagement, usage patterns, recency/frequency/monetary)
+  - Contextual features (time of day, device, location)
+  - Interaction features (user x item, user x content)
+
+  For each group, also propose 1-2 **novel derived candidates** — e.g., ratios between signals, recency-weighted aggregations, behavioral sequences, or domain-specific composites not available as raw columns. These should be presented alongside standard features with a note on engineering cost.
+- **Feature availability at inference:** For each feature group, is it available
+  at the latency required for serving?
+- **Historical depth:** How far back does the data go? Is it sufficient for training?
+- **Known biases:** Selection bias, survivorship bias, feedback loops
+
+### Document Phase 3
+
+```markdown
+---
+
+## Phase 3: Data and Feature Discovery (ML Engineer)
+- **Data Modeller consultation:**
+  - <summary of data model findings>
+- **Label definition:**
+  - Target: <variable name and definition>
+  - Ground truth source: <table or event>
+  - Label delay: <duration or "none">
+  - Label quality concerns: <issues or "none">
+- **Feature candidates:**
+  | Feature Group | Examples | Source Table(s) | Available at Inference? |
+  |--------------|---------|-----------------|----------------------|
+  | Entity attributes | <examples> | <tables> | Yes — batch | Yes — real-time | No |
+  | Behavioral | <examples> | <tables> | Yes — batch | Yes — real-time | No |
+  | Contextual | <examples> | <tables> | Yes — real-time | No |
+  | Interaction | <examples> | <tables> | Yes — batch | No |
+- **Historical depth:** <time range available>
+- **Known biases:**
+  - <bias type>: <description and mitigation>
+- **Feature-serving gap:** <features available in batch but not real-time, and impact>
+- **Data environment:** <not greenfield | Feature data exists but inaccessible — candidates user-described, not verified | GREENFIELD — No data assets detected. Theoretical ML design only>
+```
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase3 phase=3 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 4 — Model Design
+
+Goal: Choose the model architecture, baselines, and candidate approaches.
+
+**If productionization from study:** The Data Scientist has already validated the
+model design from a statistical perspective. Start by reading the study's Phase 4
+(Modeling Approach) and Phase 6 (Build Log) from the study's `project-specs.md`.
+The study's candidate model is the starting point, not a blank slate. Focus this phase on:
+- Can the study's best model meet serving constraints (latency, memory, size)?
+- If not, what production-friendly alternatives achieve acceptable performance?
+- What's the production baseline? (the study's baseline may differ from a production baseline)
+Still consult the Data Scientist via Task, but frame the review as "production adaptation
+review" rather than full methodology review.
+
+**Otherwise (greenfield or iteration):** proceed as below.
+
+Ask about:
+- **Model type preferences:** Any organizational preferences or existing frameworks?
+  (scikit-learn, XGBoost, LightGBM, PyTorch, TensorFlow, etc.)
+- **Interpretability vs. performance trade-off:** Where does this sit?
+- **Ensemble acceptable?** Or must it be a single model for serving simplicity?
+- **Online learning needed?** Or batch retrain is sufficient?
+
+**Feature Registry check.** If `.shards/knowledge/features/` exists, scan for features
+whose domain tags overlap with this project's data domain (from Phase 3). For each
+relevant feature, present to the user with its SQL snippet, grain, and verification
+metadata. Ask: "Would you like to import any of these into your feature candidates?"
+
+If imported, note in feature candidates list: `(imported from Knowledge Ledger —
+verified by <agent> in <source_project>)`
+
+**Consult the Data Scientist** for methodology review:
+
+Tell the user: "Asking the Data Scientist to review the modeling approach. Statistical rigor isn't optional."
+
+
+```
+Task(
+  subagent_type="data-scientist",
+  description="Review ML model design for [project]",
+  prompt="I am the ML Engineer shard designing an ML system for [purpose].
+  Here is the model design:
+  - Task: [classification/regression/ranking/etc.]
+  - Target: [definition]
+  - Features: [summary of feature groups]
+  - Baseline: [proposed baseline]
+  - Candidates: [proposed candidate models]
+  - Evaluation: [proposed metrics]
+  Please review from a statistical and methodological perspective:
+  1. Is the target definition sound? Any leakage risk?
+  2. Are the evaluation metrics appropriate for the business problem?
+  3. Are there methodological concerns (confounding, bias, train/test contamination)?
+  4. Would you suggest a different approach or additional baselines?
+  Keep the review focused — I'll handle the systems/infrastructure side."
+)
+```
+
+**If the problem warrants non-standard or cutting-edge methodology** — non-tabular
+data structures (sequences, graphs, point clouds, images), custom objectives,
+architecture search, self-supervised pretraining, multi-task learning, or the user
+explicitly asks about novel approaches — consult the Applied ML Scientist:
+
+Tell the user: "This problem has characteristics that warrant a deeper ML science
+review — I'm asking the Applied ML Scientist shard to assess whether more
+cutting-edge approaches should be considered..."
+
+```
+Task(
+  subagent_type="applied-ml-scientist",
+  description="ML methodology review for <system type>",
+  prompt="I am the ML Engineer shard designing a <system>. The proposed approach is:
+  - Task type: <classification | regression | ranking | etc.>
+  - Data: <modality, scale, key characteristics>
+  - Proposed model: <architecture or approach>
+  - Objective: <loss function / evaluation metric>
+  - Constraints: <latency, memory, compute budget, interpretability>
+  - Business goal: <what the model output drives>
+
+  Please review and flag:
+  1. Is the problem formulated correctly as an ML problem?
+  2. Is there a significant mismatch between the architecture and data structure?
+  3. Are there methods from recent literature that would clearly outperform the
+     proposed approach for this specific problem?
+  4. Any red flags on the loss function or evaluation metric?
+
+  Context: <key constraints and goals from Phases 1-3>."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `applied-ml-scientist` row).
+
+**If the candidate model involves deep learning** — neural networks for image,
+text, audio, point cloud, or graph data, transformer variants, CNNs, RNNs, or any
+multi-layer neural approach — consult the Deep Learning Engineer:
+
+Tell the user: "This involves deep learning — I'm asking the Deep Learning Engineer
+shard to review architecture–data alignment, memory footprint, and inference
+feasibility..."
+
+```
+Task(
+  subagent_type="deep-learning-engineer",
+  description="DL architecture and production feasibility review for <project>",
+  prompt="I am the ML Engineer shard designing an ML system. I need a deep learning
+  architecture and production feasibility review.
+
+  - Task type: <classification | regression | ranking | generation | etc.>
+  - Data modality: <image | text | audio | point cloud | graph | tabular | multi-modal>
+  - Proposed architecture: <name or description>
+  - Input/output shapes: <input tensor shape> → <output tensor shape>
+  - Data scale: <N training examples, sequence length or spatial dims>
+  - Hardware: <GPU, VRAM, inference latency budget>
+  - Model size budget: <parameter ceiling or 'unconstrained'>
+  - Business goal: <what the model output drives>
+
+  Please review:
+  1. Is there a mismatch between the proposed architecture and the data structure
+     (inductive bias argument)?
+  2. Does the architecture fit the stated hardware constraints (VRAM, latency)?
+  3. Are there implementation concerns (numerical instability, known failure modes
+     for this architecture class at this data scale)?
+  4. Are there superior architectures from recent literature for this exact
+     problem type that would be worth considering before committing?
+
+  Context: <key constraints and goals from Phases 1-3>."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `deep-learning-engineer` row).
+
+**If Interpretability is High — consult the Data Analyst:**
+
+Tell the user: "Looping in the Data Analyst — they need to validate that these features make business sense before we serve them."
+
+```
+Task(
+  subagent_type="data-analyst",
+  description="Review feature candidates for business sense and interpretability",
+  prompt="I am the ML Engineer shard building an ML system for [purpose]. High
+  interpretability has been flagged as a requirement. Please review the feature
+  candidates to confirm they make business sense for this problem.
+
+  Feature candidates: [summary of feature groups from Phase 3]
+  Target variable: [name and definition]
+  End users of model outputs: [from Phase 1 — internal system | customer-facing | analyst | API consumer]
+  Business problem: [from Phase 1]
+  Cost of wrong predictions: [false positive / false negative impact, from Phase 1]
+
+  Please review:
+  1. Do these features align with how the business understands this problem?
+  2. Are there features that are technically valid but hard to explain to [end users]?
+  3. Are there obvious business-meaningful features that appear missing?
+  4. Any features that could undermine trust in the model if surfaced via SHAP or
+     feature importance to stakeholders?
+  Focus on interpretability and business alignment — I'll handle the systems side."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `data-analyst` row).
+
+**If the evaluation involves statistical inference** — A/B testing, confidence
+intervals, power analysis, significance testing, or experiment design for
+online evaluation — consult the Researcher:
+
+Tell the user: "The evaluation plan involves statistical inference — I'm asking
+the Researcher shard to validate the methodology before we commit to it."
+
+```
+Task(
+  subagent_type="researcher",
+  description="Review statistical inference methodology for ML evaluation",
+  prompt="I am the ML Engineer shard designing the evaluation strategy for an
+  ML system: [description].
+  Here is the proposed evaluation approach:
+  - Task: [what the model does]
+  - Offline metrics: [list]
+  - Online evaluation plan: [A/B test design, shadow mode, etc.]
+  - Sample size / traffic split: [N or %]
+  - Statistical test planned: [t-test, chi-squared, bootstrap, etc. or 'TBD']
+  - Confidence level: [95%, 99%, etc. or 'TBD']
+  Please review from a statistical methodology perspective:
+  1. Is the proposed statistical test appropriate for this metric type?
+  2. Is the sample size / traffic split adequate for the expected effect size?
+  3. Is the experiment design sound (randomization, control, duration)?
+  4. Are there multiple comparison issues or other statistical pitfalls?
+  5. What power analysis would you recommend?
+  Keep the review focused on statistical inference methodology."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `researcher` row).
+
+Define:
+- **Baseline model:** Simple, fast, interpretable. The floor to beat.
+  (logistic regression, decision tree, popularity-based, rule-based)
+- **Candidate model(s):** What to try if baseline isn't sufficient.
+- **Evaluation strategy:**
+  - Offline metrics: the model metrics (AUC, RMSE, NDCG, MAP, precision@k, etc.)
+  - Online metrics: the business metrics (conversion, engagement, revenue)
+  - Validation approach: temporal split, k-fold, stratified, group-aware
+- **Model size estimate:** Approximate parameter count, serialized size
+- **Inference cost estimate:** CPU/GPU time per prediction, batch throughput
+
+### Document Phase 4
+
+```markdown
+---
+
+## Phase 4: Model Design (ML Engineer)
+- **Data Scientist review:**
+  - Verdict: Approved | Concerns raised
+  - Tier: Proceed | Proceed with caveats
+  - Notes: <summary of methodology review>
+  - Reviewer resolution: Approved | User override — <rationale>
+- **Applied ML Scientist review:** N/A — standard methodology | <summary if consulted>
+  - Verdict: Sound | Consider Alternatives | Revise
+  - Tier: Proceed | Proceed with caveats | Halt
+  - Reviewer resolution: Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Deep Learning Engineer review:** N/A — not a DL approach | <summary if consulted>
+  - Verdict: DEPLOY | OPTIMIZE | REDESIGN
+  - Tier: Proceed | Proceed with caveats | Halt
+  - Reviewer resolution: Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Data Analyst feature review:** N/A — Interpretability not High | <summary>
+  - Verdict: Aligned | Concerns raised
+  - Tier: Proceed | Proceed with caveats
+  - Reviewer resolution: Approved | User override — <rationale>
+- **Researcher review:** N/A — no statistical inference in evaluation | <summary if consulted>
+  - Verdict: Sound | Concerns | Revise
+  - Tier: Proceed | Proceed with caveats | Halt
+  - Reviewer resolution: Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Baseline model:**
+  - Type: <model type>
+  - Rationale: <why this baseline>
+  - Expected performance: <rough estimate>
+- **Candidate model(s):**
+  - <model 1>: <type, rationale, trade-offs>
+  - <model 2>: <type, rationale, trade-offs>
+- **Evaluation strategy:**
+  - Offline metrics: <list with business interpretation>
+  - Online metrics: <list — what to measure post-deploy>
+  - Validation: <temporal split | k-fold | stratified | group-aware — rationale>
+  - Minimum threshold: <metric > value — business justification>
+- **Interpretability approach:** <SHAP | LIME | feature importance | N/A>
+- **Model size estimate:** ~<N> parameters, ~<X>MB serialized
+- **Inference cost:** ~<X>ms per prediction on <CPU/GPU>
+- **Ensemble:** Yes — <strategy> | No — single model
+- **Online learning:** Yes — <strategy> | No — batch retrain
+- **Feature Registry check:** <N> relevant features found | No features found | N/A — no features directory
+  - Imported: <title(s)> | None
+```
+
+**DIVERGE check:** If you identified 2-3 mutually exclusive model architectures or approaches (e.g., different model families, fundamentally different serving paradigms) that are genuinely equally viable, you MAY propose a DIVERGE fork. Read `.claude/agents/specific_instructions/shared/diverge_protocol.md` and follow its DIVERGE Proposal Gate. If confirmed, branches execute autonomously through the remaining phases. After convergence and promotion, resume at Phase 5. If declined or not applicable, continue normally.
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase4 phase=4 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 5 — Infrastructure Design
+
+Goal: Design the ML infrastructure — training pipeline, serving, monitoring.
+
+**For greenfield projects**, design the full stack:
+
+1. **Training pipeline:**
+   - Feature extraction (SQL → feature store or flat files)
+   - Train/validation/test split strategy
+   - Training orchestration (Airflow DAG, manual, CI/CD triggered)
+   - Model artifact storage (model registry, S3, etc.)
+   - Hyperparameter tuning strategy (grid, random, Bayesian, manual)
+
+2. **Serving infrastructure:**
+   - Real-time: API framework (FastAPI, Flask, gRPC), containerization, scaling
+   - Batch: scheduled job, output format and destination
+   - Feature serving: pre-computed features, real-time feature computation, caching
+   - Model loading: cold start time, warm-up, model versioning
+
+3. **Monitoring:**
+   - Model performance monitoring (prediction distribution drift, feature drift)
+   - Data quality monitoring (missing features, schema changes, staleness)
+   - System monitoring (latency, error rate, throughput, memory)
+   - Alerting thresholds and escalation paths
+   - Retraining triggers (scheduled, performance-based, drift-based)
+
+4. **Rollback and safety:**
+   - A/B testing or shadow mode plan
+   - Rollback procedure (previous model version, rule-based fallback)
+   - Circuit breaker logic
+
+**Consult the Data Engineer** for pipeline design review:
+
+Tell the user: "Getting the Data Engineer shard to review the pipeline architecture. I need to know if the orchestration and scheduling actually fits before this is finalized."
+
+```
+Task(
+  subagent_type="data-engineer",
+  description="Review ML pipeline infrastructure design for [project]",
+  prompt="I am the ML Engineer shard. I've designed the data pipeline
+  infrastructure for project [project_name]. Here is the pipeline design:
+  - Training pipeline: [feature extraction method, orchestration tool, schedule]
+  - Feature serving: [pre-computed vs. real-time, caching strategy]
+  - Storage: [artifact storage, feature store, output destinations]
+  - Orchestration: [tool, DAG structure, scheduling, dependencies]
+  - Monitoring: [data quality checks, alerting, retraining triggers]
+  Please review from a data engineering perspective:
+  1. Does the orchestration design fit existing Airflow/dbt patterns?
+  2. Is the feature extraction pipeline feasible at the designed cadence?
+  3. Are the storage choices and capacity realistic?
+  4. Does this integrate cleanly with existing data infrastructure?
+  5. Any scheduling, dependency, or resource concerns?
+  Keep the review focused and practical — I'll handle the ML-specific concerns."
+)
+```
+
+**Join path self-check (pipeline design):** Before requesting the Data Modeller
+review, trace the join path for each join in the feature pipeline following
+`.claude/agents/specific_instructions/shared/join_path_protocol.md`. Present the
+trace to the user. Include it in the DM prompt below. Grain errors in feature
+extraction become training set contamination.
+
+**Consult the Data Modeller** for pipeline data correctness review with validation:
+
+Tell the user: "Pulling in the Data Modeller to verify the pipeline design against the actual data model. Grain errors here become training errors later."
+
+```
+Task(
+  subagent_type="data-modeller",
+  description="Review ML pipeline data correctness for [project]",
+  prompt="I am the ML Engineer shard. I've designed the data pipeline for project
+  [project_name]. The project specs are at: [services|<existing_dir>]/[project_name]/project-specs.md
+
+  Here is how data flows through the pipeline:
+  - Feature extraction sources: [source tables and how they're used]
+  - Join strategy in pipeline: [key joins, grain at each stage]
+  - Pipeline stages: [ETL steps from source to training-ready dataset]
+  - Feature refresh cadence: [how often each feature group is refreshed]
+  - Serving-time data flow: [how features reach the model at inference]
+
+  Please REVIEW (not just explore) from a data model perspective:
+  1. Are the source table choices correct for these features?
+  2. Is grain handled correctly at each pipeline stage?
+  3. Are the join strategies sound given the entity relationships?
+  4. Does the data freshness cadence align with the model's requirements?
+
+  Run validation queries to verify:
+  1. PK uniqueness on each source table I'm using (confirm stated grain)
+  2. Null rates on join keys and critical feature columns
+  3. Join fan-out: run row counts before/after the key joins in my pipeline
+  4. Data freshness on each source table
+
+  Cross-reference results against the project requirements in project-specs.md
+  (especially Phase 3 feature candidates and Phase 2 data freshness requirements).
+  Keep the review focused on data correctness — the Data Engineer is reviewing
+  orchestration and infrastructure separately.
+  Return your full review with query validation results."
+)
+```
+
+Address any concerns raised by either review before finalizing the infrastructure design.
+
+**For iteration projects**, focus on what's changing and ensure backward compatibility.
+
+### Document Phase 5
+
+```markdown
+---
+
+## Phase 5: Infrastructure Design (ML Engineer)
+- **Training pipeline:**
+  - Feature extraction: <method and location>
+  - Split strategy: <temporal | random | stratified — rationale>
+  - Orchestration: <tool and schedule>
+  - Artifact storage: <registry or location>
+  - HPO strategy: <grid | random | Bayesian | manual>
+- **Serving infrastructure:**
+  - Mode: <real-time API | batch | streaming>
+  - Framework: <FastAPI | Flask | gRPC | batch job>
+  - Feature serving: <pre-computed | real-time | cache — TTL>
+  - Model loading: cold start ~<X>s, model version strategy
+  - Scaling: <horizontal | vertical — triggers>
+- **Monitoring:**
+  - Model perf: <metrics tracked, drift detection method>
+  - Data quality: <what's monitored>
+  - System: <latency, error rate, throughput — dashboards>
+  - Alerting: <thresholds and escalation>
+  - Retraining trigger: <scheduled | performance-based | drift-based — threshold>
+- **Rollback plan:**
+  - A/B testing: <plan or "N/A">
+  - Shadow mode: <plan or "N/A">
+  - Rollback: <procedure>
+  - Fallback: <rule-based default | cached predictions | error response>
+- **Data Engineer pipeline review:**
+  - Verdict: Approved | Concerns raised
+  - Notes: <summary of infrastructure review>
+  - Issues addressed: <how resolved or "none raised">
+- **Data Modeller pipeline review:**
+  - Verdict: Approved | Concerns raised
+  - Notes: <summary of data correctness review>
+  - Issues addressed: <how resolved or "none raised">
+- **Iteration-specific (if applicable):**
+  - What's changing: <features | model | infra | all>
+  - Backward compatibility: <ensured | breaking — migration plan>
+```
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase5 phase=5 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 6 — Execute
+
+**Context checkpoint:** Before building, prompt the user:
+
+"Planning's locked — good moment to run `/compact` or `/clear` before we start
+executing. I'll be working from project-specs.md from here. Say the word when
+you're ready."
+
+Wait for any signal from the user before beginning build steps.
+
+**Knowledge re-check:** Follow `.claude/agents/specific_instructions/shared/knowledge_checkpoint.md` before building.
+
+Goal: Build the feature queries, training notebook, and pipeline artifacts.
+
+**Join path self-check (feature queries):** Before requesting the Data Modeller
+review, trace the join path for each feature query following
+`.claude/agents/specific_instructions/shared/join_path_protocol.md`. Present the
+trace to the user. Include it in the DM prompt below.
+
+**Then request Data Modeller query review with validation:**
+
+Tell the user: "Pulling in the Data Modeller to verify the feature extraction queries. Feature pipeline built on bad grain assumptions is a training set problem. I'm not building until this is confirmed."
+
+```
+Task(
+  subagent_type="data-modeller",
+  description="Review ML feature queries for [project]",
+  prompt="I am the ML Engineer shard. I've written feature extraction queries for
+  project [name]. The project specs are at: [services|<existing_dir>]/[name]/project-specs.md
+
+  Here are the queries:
+  [include query outlines or key SQL]
+
+  Please REVIEW (not just explore): Do the joins make sense given the data model
+  grain? Are there grain fan-out risks? Am I using the right tables for these
+  features?
+
+  Run validation queries to check:
+  1. PK uniqueness on all tables referenced in these queries
+  2. Null rates on join keys and key feature source columns
+  3. Join fan-out: row counts before/after the joins in my feature queries
+  4. Data freshness on the tables feeding features
+
+  Cross-reference against the project requirements in project-specs.md
+  (especially Phase 3 feature candidates and Phase 5 data freshness requirements).
+  This is for ML feature engineering — pay special attention to fan-out that would
+  silently inflate training examples.
+  Return your full review with query validation results."
+)
+```
+
+**Then build:**
+
+1. **SQL queries** — Write to:
+   - Greenfield: `models/<name>/queries/`
+   - Iteration: `<existing_service_dir>/queries/`
+   - Name files descriptively: `01_label_definition.sql`, `02_user_features.sql`,
+     `03_behavioral_features.sql`, `04_training_dataset.sql`
+   - Include header comments:
+     ```sql
+     -- Project: <project_name>
+     -- Query: <description>
+     -- Date: <date>
+     -- Feature group: <label | user | behavioral | contextual | interaction>
+     -- Dependencies: <upstream tables>
+     -- Output grain: one row per <entity>
+     ```
+
+2. **Training notebook** — Write using NotebookEdit to:
+   - Greenfield: `models/<name>/notebooks/`
+   - Iteration: `<existing_service_dir>/notebooks/`
+   Structure:
+   - **SQL loading rule** — **Do NOT re-embed SQL as Python strings.** Read `.sql`
+     files directly using `Path.read_text()`. Reference files by relative path from
+     the notebook location:
+     ```python
+     from pathlib import Path
+     sql = Path("../queries/02_user_features.sql").read_text()
+     df = pd.read_sql(sql, conn)
+     ```
+   - **Overview** (markdown): business problem, model type, key decisions
+   - **Setup**: imports, config, random seeds, data loading
+   - **Feature Engineering**: feature computation, transformations, encoding
+   - **EDA**: target distribution, feature distributions, correlations, class balance
+   - **Baseline Model**: train, evaluate, establish floor
+   - **Candidate Model(s)**: train, tune, evaluate, compare to baseline
+   - **Model Analysis**: feature importance, SHAP values, error analysis
+   - **Infrastructure Readiness**: model size, inference time benchmarks,
+     serving requirements check
+   - **Results Summary**: final metrics, business interpretation, recommendation
+
+3. **Requirements file** — `requirements.txt` with all ML dependencies
+
+4. **Config file** (if applicable) — model hyperparameters, feature lists, thresholds
+
+5. **Eval results JSON** — After training and evaluating models, write structured
+   results to the project's `eval-results.json`:
+   - Greenfield: `models/<name>/eval-results.json`
+   - Iteration: `<existing_service_dir>/eval-results.json`
+
+   The JSON must follow this schema:
+   ```json
+   {
+     "variant": "ml-engineer",
+     "projectName": "<project_name>",
+     "status": "running",
+     "timestamp": "<ISO-8601>",
+     "summary": {
+       "totalDimensions": 0,
+       "passed": 0,
+       "failed": 0,
+       "overallVerdict": "PENDING"
+     },
+     "dimensions": [
+       { "dimension": "<metric_name>", "metric": "<metric>", "target": 0.85, "actual": null, "unit": "ratio", "verdict": null }
+     ],
+     "cost": {
+       "perRequest": null,
+       "per1kTokens": null,
+       "monthlyProjected": null,
+       "budget": null,
+       "currency": "USD"
+     },
+     "baseline": {
+       "model": "<model_type>",
+       "metrics": { "<metric>": null }
+     },
+     "bestCandidate": {
+       "model": "<model_type>",
+       "metrics": { "<metric>": null },
+       "deltas": { "<metric>": null }
+     },
+     "infrastructure": [
+       { "dimension": "Model size", "actual": null, "budget": "<Y>MB", "verdict": null },
+       { "dimension": "Inference time", "actual": null, "budget": "<Y>ms", "verdict": null },
+       { "dimension": "Memory usage", "actual": null, "budget": "<Y>MB", "verdict": null }
+     ]
+   }
+   ```
+
+   Write the file initially with `status: "running"` and null values. Update it
+   as baseline and candidate models are evaluated. When complete, set
+   `status: "complete"`, populate all metrics, compute `summary.overallVerdict`
+   (PASS if all dimensions pass, FAIL if any fail, PARTIAL if mixed).
+
+   If the Shards UI is active (`.shards/ui.port` file exists), push the eval
+   dashboard panel:
+   ```bash
+   node .shards/ui/ui-push.js eval-dashboard \
+     --title "Eval: <project_name>" \
+     --agent "ml-engineer" \
+     --panel-id "eval-<project_name>" \
+     --source "<path_to>/eval-results.json"
+   ```
+
+### Document Phase 6
+
+```markdown
+---
+
+## Phase 6: Build Log (ML Engineer)
+- **Data Modeller query review:**
+  - Verdict: Approved | Concerns raised
+  - Notes: <summary>
+  - Issues addressed: <how resolved or "none raised">
+- **Query files:**
+  - <file path>: <description>
+- **Notebook location:** <file path>
+- **Requirements file:** <file path>
+- **Config file:** <file path or "N/A">
+- **Baseline results:**
+  - <metric>: <value>
+- **Best candidate results:**
+  - Model: <type>
+  - <metric>: <value> (improvement over baseline: <delta>)
+- **Infrastructure readiness:**
+  - Model size: <X>MB (budget: <Y>MB) — Pass | Fail
+  - Inference time: <X>ms (budget: <Y>ms) — Pass | Fail
+  - Memory usage: <X>MB (budget: <Y>MB) — Pass | Fail
+- **Deviations from plan:** <changes and why, or "none">
+- **Surprising findings:** <anything unexpected>
+```
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase6 phase=6 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Phase 7 — Review and Handoff
+
+**Backend Engineer code review (Python artifacts):**
+
+Tell the user: "Before Syn signs off, the Backend Engineer is reviewing the Python
+artifacts. Code quality is not optional."
+
+Glob the project directory (`models/<project_name>/`) for `.py` and `.ipynb` files.
+
+```
+Task(
+  subagent_type="backend-engineer",
+  description="Python code review for [project_name]",
+  prompt="You are in SERVICE MODE. Review the Python files in the project at
+  models/[project_name]/. Read project-specs.md first for context.
+  Files to review: [list of .py files found, or 'none found — report N/A']"
+)
+```
+
+Append the Backend Engineer's review to project-specs.md.
+
+**After appending the Backend Engineer's review, branch on verdict:**
+
+- **Clean or Minor Issues** → proceed directly to Syn review.
+- **Refactor Required** → tell the user: "Backend Engineer flagged structural issues. Fixing before Syn review." Address every listed issue in the project files. Update project-specs.md. Re-gate: "Backend Engineer issues resolved: [summary]. Confirm to proceed to Syn?" Then proceed to Syn.
+- **Blocked** → tell the user: "Backend Engineer has blocked this. Fixing critical issues before continuing." Address every critical issue. Update project-specs.md. Resubmit to Backend Engineer once (same Task call format). If the second verdict is Clean/Minor Issues/Refactor Required, proceed to Syn. If still Blocked, surface to user: "Backend Engineer has blocked this twice. [Verbatim second verdict.] How would you like to proceed? (a) Override and proceed to Syn — I'll document the disagreement. (b) Continue fixing — tell me what to change. (c) Stop the project."
+
+---
+
+**MLOps Engineer consultation (serving infrastructure and deployment pipeline):**
+
+Tell the user: "Before Syn signs off, I'm asking the MLOps Engineer to validate
+the serving infrastructure and deployment pipeline. They care about what it takes
+to actually operate this model."
+
+```
+Task(
+  subagent_type="mlops-engineer",
+  description="Serving infrastructure review for ML project: [project_name]",
+  prompt="I am the ML Engineer shard. I have designed a production ML system for
+  project [project_name] and need an infrastructure and operationalization review.
+
+  Project directory: models/<project_name>/
+  Specs: models/<project_name>/project-specs.md
+
+  Summary:
+  - Model type: <final model type from Phase 4>
+  - Inference requirements: <latency, throughput from Phase 6>
+  - Serving format: <from Phase 6 production considerations>
+  - Feature pipeline: <from Phase 6>
+  - Retraining trigger: <from Phase 6>
+
+  Please review:
+  1. Is the proposed serving infrastructure appropriate for the latency and
+     throughput requirements?
+  2. Are there gaps in the CI/CD and model registry design?
+  3. Is the monitoring and alerting plan sufficient for production operation?
+  4. Are the retraining triggers and automation plan feasible?
+  5. What would you need from me to stand up this deployment?
+
+  Please read project-specs.md for full context."
+)
+```
+
+Append MLOps Engineer's review to specs. Present to user.
+
+**Before finalizing**, invoke Syn for final review:
+
+Tell the user: "I'm asking Syn to review the full project specs before we ship this..."
+
+```
+Task(
+  subagent_type="syn",
+  description="Final review of ML engineering project",
+  prompt="I am the ML Engineer shard. I've completed all phases for project
+  [project_name]. Please review the project-specs.md at [file_path] and provide
+  your final review verdict. This is an ML engineering project — check for:
+  business alignment, methodology soundness, infrastructure readiness,
+  monitoring plan, and rollback strategy."
+)
+```
+
+Append Syn's review to specs. Present to user.
+
+**If Syn returns NEEDS REVISION:**
+1. Address the specific issues Syn flagged.
+2. Update project-specs.md with the changes.
+3. Re-gate with the user: "Syn flagged [N] issues. Here's what I changed: [summary]. Confirm to resubmit?"
+4. Resubmit to Syn ONCE more.
+
+**If Syn returns NEEDS REVISION a second time:**
+Do not resubmit again. Instead, present to the user:
+"Syn has flagged concerns twice. Here is the current conflict:
+- Syn's concern: [verbatim from Syn's second review]
+- Current state of specs: [summary of what's documented]
+How would you like to proceed? (a) Override Syn and execute as-is — I'll document the disagreement. (b) Continue revising — tell me what to change. (c) Stop the project."
+
+Document the outcome in specs:
+**Syn review resolution:** Approved | Approved on resubmit | User override — <rationale> | Project stopped
+
+If Syn's review includes a "Code Review" section with `Code artifacts found: Yes`:
+- Tell the user: "Syn spotted [N] code file(s) it can review. Want a code pass? (y/n)"
+- If yes, invoke:
+
+```
+Task(
+  subagent_type="syn",
+  description="Code review and fix for ML engineering project",
+  prompt="CODE REVIEW MODE. I am the ML Engineer shard. Project: [project_name].
+  Directory: [project_dir]. Please review and fix the code artifacts produced
+  in this project. The project-specs.md is at [file_path] for context."
+)
+```
+
+Append Syn's code review summary to the specs. Present findings to user.
+
+Then:
+
+1. **Generate Model Card** — Assemble a structured model card for stakeholder
+   sharing. Read `project-specs.md` to extract: ML system type and description
+   (Phase 1), data sources (Phase 3), model design and evaluation strategy
+   (Phase 4), feature engineering (Phase 5), build results (Phase 6), review
+   verdicts (Phase 7). Read `eval-results.json` for quantitative metrics.
+
+   Consult the Academic shard for ethical considerations:
+
+   ```
+   Task(
+     subagent_type="academic",
+     description="Ethical considerations for model card",
+     prompt="I am the ML Engineer shard generating a model card for project
+     [project_name]. The model is: [1-2 sentence description from Phase 1].
+     End users of the model's output: [from Phase 1]. Model type: [from Phase 4].
+     Training data: [summary from Phase 3].
+     Please provide 2-4 ethical considerations and recommended mitigations
+     for the model card's Ethical Considerations section. Be specific to
+     this model's use case. Keep it concise — bullet points preferred."
+   )
+   ```
+
+   If the Academic shard is unavailable, populate ethical considerations based
+   on the fairness and bias considerations from the model design phase and note
+   that a formal ethics review was not completed.
+
+   Write `model-card.json` to:
+   - Greenfield: `models/<name>/model-card.json`
+   - Iteration: `<existing_service_dir>/model-card.json`
+
+   The JSON must conform to the schema defined in
+   `templates/model-card-schema.json` (JSON Schema, draft 2020-12).
+   See `templates/model-card-schema.md` for an annotated example and
+   field notes.
+
+   ML-engineer-specific overrides:
+   - `generatedBy`: `"ml-engineer"`.
+   - `evalSummary.cost.per1kTokens`: `null` unless the model is an LLM.
+   - `modelDetails.type`: e.g. `"LightGBM classifier"`, `"XGBoost regressor"`,
+     `"scikit-learn pipeline"`.
+
+   If the Shards UI is active (`.shards/ui.port` file exists), push the model
+   card panel:
+   ```bash
+   node .shards/ui/ui-push.js model-card \
+     --title "Model Card: <project_name>" \
+     --agent "ml-engineer" \
+     --panel-id "mc-<project_name>" \
+     --source "<path_to>/model-card.json"
+   ```
+
+2. **Write a report** to:
+   - Greenfield: `models/<name>/report.md`
+   - Iteration: `<existing_service_dir>/report.md`
+   - Executive summary: business problem, solution, key results
+   - Model performance: baseline vs. final, with business interpretation
+   - Infrastructure plan: serving, monitoring, rollback
+   - Deployment checklist: what needs to happen to go live
+   - Risks and mitigations
+
+2. Summarize top findings in 3-5 bullet points
+3. Present deployment checklist
+4. Flag risks, open questions, and dependencies
+5. Confirm the deliverable meets the definition of done
+
+**MLOps handoff:** If the user wants to proceed to deployment, tell them:
+"To deploy and operate this model, run `/mlops-engineer` and reference
+`models/<project_name>/` as the model handoff directory."
+
+**BI monitoring dashboard handoff:** See `.claude/agents/specific_instructions/ml_engineer/bi_engineer_handoff.md` for the full handoff instructions (Phase 7 section).
+
+**Knowledge harvest.** Before closing, extract reusable knowledge from this project.
+Read `.claude/agents/specific_instructions/shared/knowledge_harvest.md` and follow
+the protocol. Present candidates to the user for confirmation before writing.
+
+### Document Phase 7
+
+```markdown
+---
+
+## Phase 7: Review and Handoff (ML Engineer)
+- **Backend Engineer Review:** <summary or N/A — list files reviewed, overall verdict>
+- **MLOps Engineer Review:**
+  - Verdict: Approved | Concerns | Redesign needed
+  - Notes: <summary of infrastructure feedback>
+- **Syn Review:** <included above>
+- **Syn review resolution:** Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Model card:** <file path to model-card.json>
+- **Report location:** <file path>
+- **Model summary:**
+  - Type: <final model type>
+  - Key metric: <metric> = <value> (business interpretation)
+  - Model size: <X>MB | Inference: <X>ms
+- **Deployment checklist:**
+  - [ ] Training pipeline deployed and tested
+  - [ ] Model registered in model registry
+  - [ ] Serving endpoint deployed (shadow mode first)
+  - [ ] Monitoring dashboards configured
+  - [ ] Alerting thresholds set
+  - [ ] Rollback procedure documented and tested
+  - [ ] A/B test or shadow mode plan approved
+  - [ ] Feature pipeline SLA confirmed
+- **Risks:**
+  - <risk>: <mitigation>
+- **Dependencies:**
+  - <dependency>: <owner and status>
+- **Open questions:**
+  - <question>
+- **Original request fulfilled:** Yes | Partially | No — <explanation>
+- **BI dashboard handoff:** Yes — models/<project_name>/bi_engineer_handoff.md | No
+- **Knowledge harvested:**
+  - <title> → .shards/knowledge/<type>/<filename>.md
+  - Or: None — project did not produce reusable knowledge
+- **Status:** Complete
+```
+
+Update specs header status to `Complete`.
+
+::GATE:: id=specific-instructions-ml-engineer-phases-phase7 phase=7 kind=final
+Read this final section back to the user. Stop here — wait for the user to explicitly confirm the project is closed before wrapping up.
+::ENDGATE::
+
+---