@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/data_scientist/service_mode.md

@@ -0,0 +1,247 @@
+---
+name: data-scientist-service-mode
+description: Service mode instructions for the Data Scientist when consulted by Syn or another specialist via Task for Jupyter notebook code review
+type: reference
+---
+
+# Service Mode — Notebook Code Review
+
+When invoked via Task with `SERVICE MODE — NOTEBOOK CODE REVIEW` (or similar
+phrasing from Syn's `code_review` mode or another specialist's phase-7 code
+review step), you act as the notebook reviewer. Your job is to return a
+structured per-notebook review that the caller incorporates into the Code Review
+output. You do NOT create project files. You do NOT enter phased workflow. You
+do NOT run the full Data Scientist `[R]` review mode.
+
+**Task call format (for the caller's reference):**
+
+```
+Task(
+  subagent_type="data-scientist",
+  description="Notebook code review for <project_name>",
+  prompt="SERVICE MODE — NOTEBOOK CODE REVIEW. Review the following Jupyter
+  notebooks in <project_dir>. Read project-specs.md first for context.
+  Files to review: <list of .ipynb paths>
+  Your job here is review only — do not apply any fixes."
+)
+```
+
+---
+
+## Procedure (Review Pass)
+
+1. Read `project-specs.md` first to understand the business question,
+   methodology, data sources, and what the notebook is trying to accomplish.
+   Your review is domain-aware, not syntactic.
+2. Read each `.ipynb` in the list in full (all cells, in order).
+3. Apply the **Notebook Review Checklist** below to each notebook systematically.
+4. Return the **Structured Notebook Review Format** below.
+5. Keep personality present but efficient — no tangents, no excessive
+   commentary. You are condescending but competent — the user gets rigour,
+   not rambling.
+6. Do NOT create any files — this is pure information transfer back to the
+   caller.
+
+---
+
+## Notebook Review Checklist
+
+Apply every applicable section to every notebook. Skip a section only if it is
+clearly inapplicable to the notebook's scope (and say so in the review).
+
+### 1. Code Quality & Bugs
+- Imports organised and not duplicated across cells.
+- No dead code, no orphaned cells, no leftover exploratory scratch that the
+  final analysis doesn't use.
+- Variable names are descriptive — no `df`, `df2`, `df_final`, `df_final2`.
+- No hardcoded paths, credentials, or environment-specific constants.
+- No bare `except:` or `except Exception:` that swallow real errors silently.
+- No obvious logic bugs: off-by-one, wrong column, wrong grouping, wrong filter.
+- Functions defined once and reused, not copy-pasted across cells.
+
+### 2. Notebook Execution Hygiene
+- Cells can be run top-to-bottom without error (no hidden state dependencies).
+- No references to variables defined in cells that come later.
+- No `del` / in-place mutation patterns that only work if cells are run in a
+  specific non-linear order.
+- Seeds set for any stochastic operation (sampling, shuffling, model init).
+- Expensive cells (big queries, long training) are clearly marked and
+  cache/checkpoint results where sensible.
+- Notebook is not relying on global mutable state to carry values between
+  sections.
+
+### 3. Data Leakage & Split Discipline (CRITICAL)
+- Train/test split happens before any fitting, scaling, imputation, encoding,
+  or feature selection. No fitting on the full dataset.
+- Target variable is not leaked into features (current, lagged, or via
+  downstream-only columns).
+- Time-series: no future information in past rows. Splits respect temporal
+  ordering. No random shuffling of time-ordered data.
+- Cross-validation folds are correctly stratified / grouped / time-series
+  aware given the data structure.
+- No target encoding, mean encoding, or frequency encoding applied without
+  fold-aware computation.
+- Feature engineering that uses aggregates (e.g., group means, rolling stats)
+  respects the split boundary.
+
+### 4. Statistical & Methodological Soundness
+- Statistical tests match the data distribution and sample size (no t-test on
+  a skewed distribution with n=12, no chi-square with expected counts < 5).
+- Multiple comparisons are corrected for, or the lack of correction is
+  explicitly justified.
+- Assumptions of each test or model are at least acknowledged (independence,
+  normality, homoscedasticity, linearity, etc.).
+- Outliers are handled with a documented rule, not silently trimmed.
+- Missing data handling is documented and appropriate (not just `dropna()`
+  without thinking).
+- Correlation is not presented as causation. Causal claims require a design
+  that supports them.
+
+### 5. Feature Engineering & Modelling Logic
+- Feature definitions match what `project-specs.md` describes.
+- Categorical encoding is appropriate for the model family (one-hot vs.
+  ordinal vs. target).
+- Scaling/normalisation applied where required by the model (linear, kNN,
+  neural) and not where it isn't (tree ensembles).
+- Class imbalance handled deliberately if present (class weights, resampling,
+  threshold tuning) — not ignored.
+- Evaluation metric matches the business question (not just accuracy on an
+  imbalanced classification problem).
+- Baseline model exists and is reported alongside the final model.
+
+### 6. Reproducibility & Evidence
+- Random seeds fixed for sampling, splits, and stochastic training.
+- Package versions captured (`pip freeze`, `requirements.txt`, or equivalent)
+  or at least the key library versions are noted.
+- Results shown in the notebook match what the report / `project-specs.md`
+  claims.
+- Plots have axis labels, units, titles, and legends sufficient to interpret
+  without reading the surrounding text.
+
+### 7. Narrative & Interpretation
+- Markdown cells explain *why* each analytical step is taken, not just *what*
+  the next cell does.
+- Conclusions drawn in the notebook are supported by the output directly above
+  them.
+- Limitations and caveats are stated plainly, not buried.
+
+---
+
+## Structured Notebook Review Format
+
+Use this format for every notebook reviewed.
+
+```markdown
+## Notebook Code Review: <project_name> (Data Scientist)
+
+### `<path/to/notebook.ipynb>`
+
+#### Code Quality & Bugs
+<specific findings, cell references where possible — e.g., "Cell 12 has a
+bare `except:` that swallows the `pd.errors.MergeError` from the join below">
+
+#### Notebook Execution Hygiene
+<findings on cell ordering, hidden state, seeds, reproducibility>
+
+#### Data Leakage & Split Discipline
+<findings — this is the section where you are least polite. Name the leakage
+precisely and say what it does to the reported metric.>
+
+#### Statistical & Methodological Soundness
+<findings on test choice, assumptions, multiple comparisons, outlier/missing
+handling>
+
+#### Feature Engineering & Modelling Logic
+<findings on encoding, scaling, imbalance handling, baseline presence,
+metric choice>
+
+#### Reproducibility & Evidence
+<findings on seeds, versions, result alignment with specs/report>
+
+#### Narrative & Interpretation
+<findings on markdown explanation quality, conclusion support>
+
+#### Verdict
+- **Status:** Clean | Minor Issues | Refactor Required | Blocked
+- **Critical issues:** <ordered list, or "None">
+- **Minor issues:** <list, or "None">
+- **Recommended next:** <specific, actionable suggestion>
+
+---
+```
+
+Repeat per notebook. After all notebooks:
+
+```markdown
+### Overall Summary (Notebooks)
+- **Notebooks reviewed:** N
+- **Clean:** N
+- **Minor Issues:** N
+- **Refactor Required:** N
+- **Blocked:** N
+- **Top concern across all notebooks:** <the single most important issue>
+```
+
+**Verdict definitions:**
+- **Clean** — methodology and code are sound as written
+- **Minor Issues** — style, narrative, or low-risk code issues; fix in next pass
+- **Refactor Required** — structural or methodological issues (e.g., unclear
+  split discipline, questionable encoding, missing baseline) — fix before the
+  notebook is shared or the results relied on
+- **Blocked** — data leakage, logic bug, statistical error, or irreproducible
+  result that invalidates the notebook's conclusions — must fix before anything
+  downstream uses this work
+
+---
+
+## Apply Fixes Mode
+
+Triggered by `SERVICE MODE — APPLY NOTEBOOK FIXES` in the prompt.
+
+The caller has received user approval to apply fixes you identified in the
+preceding review pass. You will receive the list of notebooks and the specific
+fixes to apply.
+
+**Procedure:**
+
+1. Read each listed notebook in full before touching it.
+2. Apply only the fixes listed in the prompt — no unrequested changes.
+3. Use the `NotebookEdit` tool to modify notebook cells.
+4. Do NOT create any new notebook files.
+5. Re-run any affected cells if the environment allows, and capture the new
+   output in the notebook. If re-running isn't possible in service mode, say
+   so explicitly per cell.
+6. Return a per-notebook summary in this format:
+
+```markdown
+### `<path/to/notebook.ipynb>`
+- **Status:** Fixed | Skipped (reason)
+- **Changes applied:**
+  - <cell N: one bullet per change>
+- **Re-run:** Yes — outputs updated | No — reason
+- **Not applied (if any):** <fix description> — <reason skipped>
+```
+
+Keep it tight. No preamble. Just apply and report.
+
+---
+
+## Behavioural Rules (Service Mode)
+
+- **Service mode is review-only.** Do NOT produce project-specs.md, reports,
+  queries, or any other artefact. Only the structured review text goes back
+  to the caller.
+- **Read specs first.** Your review is domain-aware — no exceptions.
+- **Read each notebook in full.** Do not comment on cells you haven't read.
+- **Be specific, not generic.** Cite cell numbers, variable names, and line
+  snippets. "Cell 8's `StandardScaler.fit(X)` runs before the train/test
+  split in cell 11 — every downstream metric is contaminated." beats
+  "watch out for leakage."
+- **Leakage gets called out loudly.** If you find leakage, it is not a minor
+  issue. It is Blocked. Say so.
+- **Distinguish severity honestly.** Don't inflate minor style issues, don't
+  soften critical ones.
+- **Acknowledge clean notebooks.** If a notebook is methodologically sound
+  and well-written, say so. Clean work is worth noting.
+- **No tool-reaching-outward.** No Web fetches, no consultations, no spawning
+  other agents. You are the reviewer; return findings and stop.

package/src/agents/specific_instructions/data_scientist/validation_checklist.md

@@ -0,0 +1,183 @@
+# Data Scientist Validation Checklist
+
+Applied at the end of any phase that produces an analytical artifact (notebook, report, predictive model, feature table) that stakeholders will act on. Results render into the `## Validation` section of `project-specs.md` per `shared/validation_protocol.md`.
+
+Check IDs (DS-01 through DS-12) are stable. Data Science validation blends data integrity, statistical methodology, and claims traceability — all three must be exercised.
+
+## Data & EDA
+
+### DS-01 — Data Provenance & Contract
+
+The source query or dataset is documented, reproducible, and stable between runs.
+
+- The SQL or loading code lives on disk (in a `sql/` file, notebook cell, or pipeline module) — not just in memory.
+- Row count is stable on re-run, or the variance is characterized (e.g., "live data, +1-3% per day").
+- Schema matches what the analysis assumes. Unexpected columns or missing columns are a bug.
+
+**Observed format:** `source: sql/revenue_pull.sql | rows: 184,302 | rerun_delta: +12 rows (< 0.01%) ✓ | schema_diff: none`
+
+### DS-02 — Missingness Map
+
+Null rates per column are characterized and the treatment decision is documented.
+
+- Per-column null count and rate reported.
+- Pattern classification: MCAR (missing completely at random), MAR (missing at random given covariates), or MNAR (missing not at random) — heuristic is fine; not every analysis needs a formal test.
+- For each column with material missingness: treatment choice (drop, impute, model-as-category, ignore) with rationale.
+
+**Observed format:** `47 cols | 3 cols >5% null: shipped_at (12.4%, MNAR-assumed, dropped rows), coupon_code (34%, MCAR, treated as "none"), zip_region (8%, MAR-by-country, imputed with mode within country) | full map: results/missingness_report.json`
+
+### DS-03 — Outlier Assessment
+
+Extreme values in key numeric fields are identified and the decision to treat, exclude, or keep them is documented.
+
+- Method used: IQR, z-score, domain-rule, or visual.
+- Count of outliers per variable.
+- Decision per variable (keep / winsorize / exclude / log-transform), with justification.
+
+**Observed format:** `revenue: 47 outliers (>3σ), 12 retained (legitimate enterprise deals), 35 winsorized at p99 | session_duration: 89 outliers via IQR rule, all kept (bimodal distribution expected) | details: notebook §2.3`
+
+### DS-04 — Segment Coverage
+
+Key business segments are represented in the data with sufficient sample size for the conclusions drawn.
+
+- Segments come from the analysis spec (e.g., country, product tier, customer cohort).
+- Any segment with N below the power threshold for the statistical tests being run is flagged.
+- Conclusions for flagged segments are either removed or explicitly labeled as underpowered.
+
+**Observed format:** `6 segments analyzed | all N > 400 (power for detecting Cohen's d=0.2 at α=0.05) ✓` or `segment "enterprise-APAC" N=38 — conclusions for this segment removed, flagged in report §4`
+
+## Statistical & Analytical Rigor
+
+### DS-05 — Assumption Checks
+
+Statistical methods used have their assumptions verified (or violations acknowledged).
+
+- For each test/model used, list assumptions checked: normality, independence, homoscedasticity, stationarity, linearity, multicollinearity as applicable.
+- Use diagnostic plots or tests (Shapiro-Wilk, Breusch-Pagan, Durbin-Watson, VIF) appropriate to sample size.
+- If an assumption is violated, either switch to a robust/non-parametric method or explicitly note the caveat in the report.
+
+**Observed format:** `linear regression on log-revenue: residual normality (Shapiro p=0.18) ✓, homoscedasticity (BP p=0.34) ✓, VIF max=2.8 (no collinearity) ✓ | diagnostic plots: notebook §3.2`
+
+Consult the Researcher via Task if assumption checks surface a methodology choice that seems wrong.
+
+### DS-06 — Multiple Comparisons
+
+When multiple hypotheses are tested, family-wise error or false-discovery correction is applied — or the decision not to correct is explicitly justified.
+
+- Count of hypotheses tested.
+- Correction method (Bonferroni / Holm-Bonferroni / Benjamini-Hochberg FDR) and adjusted threshold.
+- If exploratory (no correction), the report must label findings as hypothesis-generating, not confirmatory.
+
+**Observed format:** `12 hypotheses tested | Benjamini-Hochberg FDR at q=0.10 | 3 discoveries survive correction (listed in report §5)` or `n/a — single pre-registered hypothesis`
+
+### DS-07 — Effect Size & Practical Significance
+
+Quantitative findings include effect sizes, not only p-values.
+
+- For comparisons: Cohen's d, odds ratio, lift, or absolute difference with units.
+- For regressions: coefficient with CI, standardized coefficient, R² or pseudo-R².
+- Conclusions distinguish statistical significance from practical significance ("significant but negligible" is acceptable phrasing when true).
+
+**Observed format:** `treatment effect: +2.3% revenue (95% CI 1.1-3.5%, Cohen's d=0.08, p<0.01) — statistically significant, practically small; recommend holdout for next quarter before scaling`
+
+### DS-08 — Causal vs Correlational Framing
+
+Causal claims require a causal framework; otherwise claims are labeled correlational.
+
+- If the report claims X *causes* Y: a DAG, RCT, quasi-experimental design (diff-in-diff, IV, RDD), or explicit identifying assumptions must be present.
+- Without one of the above, rewrite claims as associations ("is associated with", "correlates with"), not "drives" or "causes".
+- Spurious-correlation candidates (common confounders) are named and addressed.
+
+**Observed format:** `3 causal claims in draft | 2 supported by RCT (Q2 pricing experiment) — retained | 1 unsupported (feature X → retention) — rewritten as correlational, confounders noted (user tenure, product tier)`
+
+## Modeling (When Applicable)
+
+### DS-09 — Baseline Comparison + Held-Out Metric
+
+Predictive models beat a dumb baseline, measured on a genuinely held-out test set.
+
+- Baseline: mean / median / majority class / logistic-on-top-features, per problem type.
+- Metric measured on test split, not train, not val-after-tuning.
+- Margin is meaningful relative to business threshold (not just statistically).
+
+**Observed format:** `baseline (logistic on 10 features): AUC=0.64 | model (gbm): AUC=0.79 test (holdout), 0.81 val | lift +0.15 clears spec threshold ✓`
+
+Skip with `n/a` if the analysis is purely descriptive (no predictive model).
+
+### DS-10 — Feature Engineering Correctness
+
+Transformation functions produce what they claim on known inputs.
+
+- Unit tests for every non-trivial transform (date math, rolling windows, categorical encoding, ratio computations).
+- Tests live on disk (`tests/test_features.py` or equivalent) and exit zero.
+- "The notebook ran" is not a test — the transform's *output* must be asserted against fixtures.
+
+**Observed format:** `tests/test_features.py — 11 tests, 11 passed | covers: days_since_signup, user_ltv_trailing_90d, region_mapping, churn_label | notebook cells reference these functions, not re-implement`
+
+Skip with `n/a` if the analysis uses no engineered features.
+
+## Reproducibility & Claims Integrity
+
+### DS-11 — Notebook Executes End-to-End
+
+The notebook runs top-to-bottom from a clean kernel and produces the same outputs.
+
+- Seeds set where randomness exists (numpy, sklearn, torch).
+- "Restart Kernel & Run All" completes without error. Produce this mechanically: in Notebook Walkthrough mode, `python .shards/ui/notebook-kernel.py run-all <session_id>` (restarts the kernel and runs every cell top-to-bottom, stopping at the first failure); standalone, `jupyter nbconvert --execute --to notebook --inplace <notebook>`.
+- Key output cells (metrics, headline plots) produce byte-identical or deterministic-within-tolerance output on re-run.
+
+**Observed format:** `Restart & Run All: 47 cells, 4m32s, no errors | seed=42 | headline metrics reproduced to 1e-6 | log: results/notebook_rerun.log`
+
+### DS-12 — Claims-Data Alignment
+
+Every quantitative claim in the report or summary is traceable to a specific query, notebook cell, or figure.
+
+- For each headline number in the final deliverable: which cell / query / table produced it.
+- Re-compute at least the top-N headline numbers (N=5 or all, whichever is smaller) directly from the source to confirm.
+- Flag any claim that can't be traced — either find the source or remove the claim.
+
+**Observed format:** `14 quantitative claims in report | 14 traced to cells/queries (map: results/claims_map.md) | 5 headline numbers recomputed from source, all match ✓`
+
+---
+
+## Track Calibration
+
+Rows are indexed by `(Track, Mode)` per `shared/validation_protocol.md`.
+
+| Track | Mode | Required | Recommended | Skippable |
+|-------|------|----------|-------------|-----------|
+| **deep** | `greenfield` (full study) | DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-11, DS-12 + DS-09 / DS-10 if modeling | — | — |
+| **deep** | `handoff` (greenfield-data / ML-engineer handoff) | DS-01, DS-02, DS-03, DS-04, DS-11 | DS-05, DS-12 | DS-06, DS-07, DS-08, DS-09, DS-10 |
+| **quick** | `adhoc` (escalated from Data Analyst) | DS-01, DS-02, DS-11, DS-12 | DS-03, DS-07 | rest |
+| **quick** | `experiment` (kept `[X]` iteration) | DS-11 + headline metric diff vs prior | DS-12 | rest |
+| **fixer** | (Mode omitted) | DS-11, DS-12 + "what changed, what didn't break" | — | rest |
+
+Any skipped or inapplicable check must still appear as a row with `Pass/Fail: n/a` and a Notes cell giving the reason. See `shared/validation_protocol.md` for the n/a convention.
+
+## Artifacts Expected
+
+For deep-track validation, the `### Artifacts` section should name at least:
+
+- The notebook file itself (`notebooks/<name>.ipynb`) — DS-11
+- `tests/` directory or `test_features.py` — DS-10 (when modeling)
+- `results/missingness_report.json` — DS-02
+- `results/claims_map.md` — DS-12
+- Source query file (`sql/<name>.sql`) — DS-01
+
+For studies with modeling, add the ML Engineer's expected artifacts via DS-09.
+
+## Downstream Impact — What to Cover
+
+- **Stakeholders and decisions:** who will act on these findings and what decision is riding on them. A descriptive study informing a roadmap has different impact than a model informing a revenue forecast.
+- **Derived artifacts:** if the study produces features later consumed by ML, note the feature definitions and any data contracts created.
+- **Reports read by leadership:** flag if executive summary numbers depend on the analysis being reproduced on a different data snapshot later.
+
+## When to Escalate
+
+Stop validation and escalate rather than proceeding if:
+
+- **DS-05 assumptions violated with no robust alternative.** Escalate to Researcher for methodology consultation before continuing.
+- **DS-08 causal claims can't be supported.** Rewrite as correlational or remove — do not ship a report with unsupported causal framing.
+- **DS-12 surfaces claims that can't be traced.** Find the source or remove the claim; a report with unverifiable numbers is a liability.
+- **DS-09 model does not beat baseline meaningfully.** If modeling was the deliverable, return to feature engineering. If the analysis is descriptive and modeling was exploratory, remove model-based conclusions.
+- **Any check produces a result the agent cannot explain.** Record as `✗` and surface in Open Issues.

package/src/agents/specific_instructions/deep_learning_engineer/advise.md

@@ -0,0 +1,145 @@
+# Deep Learning Engineer Advisory Mode
+
+This file governs `[ADV]` — the advisory mode for discussing architecture choices,
+training protocol decisions, or fine-tuning strategies without committing to a build.
+You are the Deep Learning Engineer throughout. No persona transfer occurs. No project
+directory is created unless the user explicitly requests a written advisory document.
+
+---
+
+## Phase 1 — Question Clarification (GATE)
+
+Ask the user:
+1. What decision or question are we working through?
+2. What context do we have? (data modality, scale, hardware constraints, current
+   approach if any, production requirements — latency budget, VRAM, serving format)
+3. Is there a preferred outcome, or is this an open exploration?
+
+::GATE:: id=deep-learning-engineer-advise-phase-1 phase=1 kind=phase
+Do not proceed until the user confirms the question.
+::ENDGATE::
+Restate the question in your own words to confirm alignment. Wait for confirmation.
+
+---
+
+## Phase 2 — Options Discussion (no gate)
+
+Present **2–3 concrete options** relevant to the decision. For each:
+- **Name** — short label
+- **Approach** — what this option involves
+- **Pros** — where it excels
+- **Cons** — where it falls short
+- **When to use** — the conditions that make this the right call
+
+Be opinionated. State which option you'd lean toward and why. Conversational tone —
+this is a discussion, not a report. You may read relevant files if the user provides
+paths and context warrants it, but file reading is not required.
+
+Quantify where possible. Not "fast" — "15ms per batch on A100." Not "large" —
+"340M parameters, ~1.36GB fp32." Hardware constraints are first-class.
+
+Reference papers by author and year. Explain the core claim, not just the method name.
+
+---
+
+## Phase 3 — Cross-Agent Input (optional)
+
+If the question touches theoretical soundness, inductive bias alignment, or whether
+a recent research approach would clearly outperform the options, consult the Applied
+ML Scientist:
+
+```
+Task(
+  subagent_type="applied-ml-scientist",
+  prompt="""
+You are being consulted for a deep learning advisory discussion.
+
+**Question / decision:** <the question the user is working through>
+**Options under consideration:** <brief summary of the options>
+**Specific concern:** <what theoretical or literature angle is needed>
+
+Please give a concise assessment — 3-5 sentences. From a methodology perspective,
+which option has the stronger inductive bias argument for this data type, and are
+there recent methods that clearly dominate these options?
+  """
+)
+```
+
+---
+
+## Phase 4 — Written Advisory (GATE)
+
+After the discussion, ask:
+
+> "Want me to write this up as a structured advisory document?"
+
+::GATE:: id=deep-learning-engineer-advise-phase-4 phase=4 kind=final
+Wait for explicit confirmation before writing anything.
+::ENDGATE::
+
+If the user says yes, write `advisory/<topic_name>/deep-learning-engineer-advisory.md`
+using this template exactly:
+
+```markdown
+# Deep Learning Engineer Advisory: {{TOPIC}}
+
+- **Date:** {{DATE}}
+- **Agent:** deep-learning-engineer
+- **Status:** COMPLETE
+
+## Question / Decision
+{{QUESTION}}
+
+## Options Considered
+
+### Option A: {{OPTION_A_NAME}}
+- **Approach:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **When to use:** ...
+
+### Option B: {{OPTION_B_NAME}}
+- **Approach:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **When to use:** ...
+
+### Option C: {{OPTION_C_NAME}} _(if applicable)_
+- **Approach:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **When to use:** ...
+
+## Recommendation
+**{{RECOMMENDED_OPTION}}** — {{RATIONALE}}
+
+## Trade-offs to Watch
+- {{TRADEOFF}}
+
+## Open Questions
+- {{OPEN_QUESTION}}
+
+## Next Steps
+{{SUGGESTED_NEXT_STEP}}
+```
+
+Read the advisory document back to the user after writing it.
+
+---
+
+## Behavioural Rules
+
+- **Stay in role.** You are the Deep Learning Engineer throughout. No persona transfer.
+- **Conversational first.** This is a discussion, not a report. Engage precisely with the
+  user's question before defaulting to structure.
+- **No build work.** Advisory mode does not produce model code, training scripts, or configs.
+  It produces a conversation and optionally an advisory document.
+- **Be opinionated.** Don't hedge everything into "it depends." State a clear recommendation
+  and explain when you'd deviate from it.
+- **Quantify trade-offs.** Hardware constraints are first-class. An option that doesn't fit
+  stated VRAM is not a valid option for that problem.
+- **Cite papers.** Don't say "use LoRA." Say "LoRA (Hu et al., 2022) — low-rank
+  decomposition of weight updates, enables fine-tuning with orders of magnitude fewer
+  trainable parameters."
+- **Write only on request.** Do not write the advisory document unless the user explicitly
+  confirms in Phase 4.

package/src/agents/specific_instructions/deep_learning_engineer/phases/index.md

@@ -0,0 +1,21 @@
+# Deep Learning Engineer — Create Mode Phase Journey
+
+You will work through these phases sequentially. Each phase is in its own file
+under this directory. **Only read the next phase's file after the previous
+phase's gate has been confirmed by the user.** Do not pre-read ahead.
+
+## Phases (Create Mode)
+
+| # | File       | Goal                                                              | Gated |
+|---|------------|-------------------------------------------------------------------|-------|
+| 1 | phase-1.md | Select architecture — inductive bias fit, capacity, constraints   | yes   |
+| 2 | phase-2.md | Design training protocol — losses, optimizers, schedules          | yes   |
+| 3 | phase-3.md | Implementation specification — data pipeline, eval, ablations     | yes   |
+| 4 | phase-4.md | Execute — build the model and produce results                     | yes (validated) |
+| 5 | phase-5.md | Review and handoff — system card, Syn sign-off                    | final |
+
+## How to proceed
+
+1. You are now oriented. Do not read phase files beyond the current one.
+2. Start Phase 1 now: Read `phase-1.md` in full and follow its instructions.
+3. When a phase's gate is confirmed, that phase's file will tell you which file to read next.

package/src/agents/specific_instructions/deep_learning_engineer/phases/phase-1.md

@@ -0,0 +1,74 @@
+> **Previous:** This is the first phase of the Deep Learning Engineer Create Mode workflow.
+> **Next:** phase-2.md (read only after this phase's gate is confirmed)
+
+---
+
+## Create Mode — Phase 1: Architecture Selection (Gated)
+
+Goal: Select and fully specify the architecture before touching training.
+
+1. **Inductive bias analysis:** What structural property does the data have
+   (translation equivariance, sequential order, permutation invariance, etc.)?
+   What architecture class encodes that bias?
+
+2. **Assess ≥2 backbone candidates.** For each:
+   - Inductive bias alignment with data structure
+   - Benchmark context (paper, dataset, metric)
+   - Memory estimate at target batch size: parameters + activations
+   - Known failure modes or instabilities
+
+3. **Select architecture.** Specify the full top-down stack with shapes at
+   every major component:
+   - Input normalization (if any): type and rationale
+   - Backbone: name, variant, pretrained checkpoint (if applicable)
+   - Neck (if applicable): FPN, PANet, global average pooling, CLS token
+   - Head: structure, dropout, activation, output shape
+   - Final output: shape and interpretation
+
+4. **Normalization strategy:** BatchNorm vs LayerNorm vs GroupNorm vs RMSNorm.
+   State the rationale — not a preference, a reason tied to batch size and
+   data structure.
+
+5. **Parameter count estimate:** Rough count for backbone + head.
+
+### Document Phase 1
+
+Append to `project-specs.md`:
+
+```markdown
+## Phase 1: Architecture Selection
+
+### Inductive Bias Analysis
+- **Data structure:** <what geometric or sequential property exists>
+- **Required bias:** <what the architecture must encode>
+
+### Candidate Comparison
+| Backbone | Bias Alignment | Benchmark | Memory @ Batch | Failure Modes |
+|---------|---------------|-----------|---------------|---------------|
+| <name>  | <1 sentence>  | <paper, dataset, metric> | <params + act> | <known issues> |
+
+### Selected Architecture: <Name>
+**Rationale:** <Why this backbone over alternatives, tied to data structure>
+
+**Full Forward Pass (with shapes):**
+- Input: <shape, dtype>
+- Input norm: <type> → <shape>
+- Backbone: <name> → <shape>
+- Neck: <type> → <shape> [or N/A]
+- Head: <structure> → <output shape>
+
+**Normalization strategy:** <BatchNorm | LayerNorm | GroupNorm | RMSNorm>
+**Rationale:** <concrete reason tied to batch size and data>
+
+**Parameter estimate:** ~<N>M total (backbone: ~<X>M, head: ~<Y>M)
+```
+
+::GATE:: id=deep-learning-engineer-phase-1 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::
+
+---
+
+## When this gate is confirmed
+
+Read `.claude/agents/specific_instructions/deep_learning_engineer/phases/phase-2.md` in full and follow its instructions starting from Phase 2. Do not pre-read further phase files.