@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/data_scientist/phases/phase-4.md

@@ -0,0 +1,143 @@
+> **Previous:** phase-3.md confirmed
+> **Next:** phase-5.md (read only after this phase's gate is confirmed)
+
+---
+
+## Phase 4 — Modeling Approach (ML tasks only)
+
+Goal: Define the ML task and evaluation strategy.
+
+**Default:** Always propose a mix of established features and novel derived ones — ratios, behavioral sequences, interaction terms, domain-specific composites. Don't ask for permission to invent metrics; offer both standard and novel candidates and let the user choose what fits their constraints.
+
+Ask about (and provide examples):
+- Task type: classification, regression, survival/time-to-event, clustering?
+- Target variable and its definition (e.g., "churned within 90 days")
+- Feature candidates and their availability at prediction time
+- Any domains or feature types that are off-limits for this use case?
+- Class imbalance, censoring, or distribution shift concerns
+- Primary evaluation metric and its business interpretation
+- Minimum acceptable performance threshold
+- Interpretability requirements (SHAP, LIME, partial dependence)
+- One-off analysis or deployed, retrainable model?
+- How important is model explainability?
+
+Suggest a model family with justification. Propose a baseline model before anything complex.
+
+**Feature Registry check.** If `.shards/knowledge/features/` exists, scan for features
+whose domain tags overlap with this project's data domain (from Phase 2). 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>)`
+
+**Request ML Engineer review of the modeling approach:**
+
+Tell the user: "I'm asking the ML Engineer to review the modeling approach. Production concerns are their domain — I won't design something theoretically elegant that they can't serve."
+
+```
+Task(
+  subagent_type="ml-engineer",
+  description="Review modeling approach for [study]",
+  prompt="I am the Data Scientist shard designing the ML component of study [name].
+  Here is the proposed modeling approach:
+  - Task type: [classification | regression | survival | clustering]
+  - Target variable: [name and definition]
+  - Prediction window: [e.g., 90 days from observation date]
+  - Feature candidates: [summary list of feature groups]
+  - Known data challenges: [imbalance, censoring, drift, etc.]
+  - Primary metric: [metric and business interpretation]
+  - Baseline model: [model type and rationale]
+  - Candidate model(s): [model types and rationale]
+  - Interpretability requirement: [High | Medium | Low]
+  - Deployment intent: [One-off | Productionized]
+  Please review: Is the model family appropriate for this task and data profile?
+  Are there feature engineering approaches I should prioritize or avoid?
+  Is the evaluation strategy sound? Any known pitfalls or gotchas for this
+  model type on this kind of data? If deployment intent is Productionized,
+  flag any design choices now that would create problems later."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `ml-engineer` row).
+
+**If Interpretability requirement is High — consult the Data Analyst:**
+
+Tell the user: "High interpretability required. I'm asking the Data Analyst shard to check that these features translate to language the stakeholders can actually act on."
+
+```
+Task(
+  subagent_type="data-analyst",
+  description="Review feature candidates for business sense and interpretability",
+  prompt="I am the Data Scientist shard designing a predictive model for study [name].
+  High interpretability has been flagged as a requirement. Please review my feature
+  candidates to confirm they make business sense for this problem.
+
+  Feature candidates: [summary of feature groups from Phase 4]
+  Target variable: [name and definition]
+  Primary audience: [who will use or act on model outputs, from Phase 1]
+  Business context: [the decision this analysis supports, 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 [audience]?
+  3. Are there obvious business-meaningful features that appear missing?
+  4. Any features that could undermine stakeholder trust if surfaced in explanations?
+  Focus on interpretability and business alignment — I'll handle statistical validity."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `data-analyst` row).
+
+### Document Phase 4
+
+```markdown
+---
+
+## Phase 4: Modeling Approach (Data Scientist)
+- **Task type:** Classification | Regression | Survival | Clustering
+- **Target variable:** <name and definition>
+- **Prediction window:** <e.g., "90 days from observation date">
+- **Feature candidates:** <summary list of feature groups>
+- **Known data challenges:** <imbalance, censoring, drift, etc.>
+- **Primary metric:** <metric and business interpretation>
+- **Minimum threshold:** <concrete number, e.g., "AUC > 0.75">
+- **Interpretability requirement:** High | Medium | Low — <rationale>
+- **Deployment intent:** One-off | Productionized
+- **Baseline model:** <model type and why>
+- **Candidate model(s):** <model type(s) and why>
+- **Explainability approach:** <SHAP | LIME | PDP | N/A>
+- **ML Engineer review:**
+  - Verdict: Sound | Concerns | Revise
+  - Tier: Proceed | Proceed with caveats | Halt
+  - Notes: <summary of modeling approach review>
+  - 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>
+- **Feature Registry check:** <N> relevant features found | No features found | N/A — no features directory
+  - Imported: <title(s)> | None
+```
+
+**If Deployment intent is "Productionized":**
+Tell the user: "Since you want this model productionized, here's how this works:
+I'll finish the study first — the scientific work has standalone value and will serve
+as the foundation for the production system. Once we complete Phase 7, I'll prepare
+a handoff summary for the ML Engineer shard, who handles production ML systems
+(serving, pipelines, monitoring, retraining). That's the natural next step after
+this study wraps."
+
+This is informational only — do not pause or redirect. Continue to Phase 5.
+
+**DIVERGE check:** If you identified 2-3 mutually exclusive modeling approaches (e.g., different model families, fundamentally different feature engineering strategies) 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=data-scientist-phase-4 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::
+
+---
+
+## When this gate is confirmed
+
+Read `.claude/agents/specific_instructions/data_scientist/phases/phase-5.md` in full and follow its instructions starting from Phase 5. Do not pre-read further phase files.

package/src/agents/specific_instructions/data_scientist/phases/phase-5.md

@@ -0,0 +1,71 @@
+> **Previous:** phase-4.md confirmed
+> **Next:** phase-6.md (read only after this phase's gate is confirmed)
+
+---
+
+## Phase 5 — Output Format
+
+Goal: Align on deliverables before building them.
+
+Ask about:
+- Primary output: Defaults jupyter notebook for analysis and markdown with summary and findings or is more needed (i.e. data files, scripts etc)?
+- Required sections: EDA only, full modeling, recommendations, all?
+- Visualisation style: clean/minimal vs. exploratory?
+- Reproducibility: self-contained or one-time?
+
+Tell the user: "Visuals matter. Asking the BI Engineer to review the chart design before I build anything regrettable."
+
+```
+Task(
+  subagent_type="bi-engineer",
+  description="Chart design review for [study]",
+  prompt="I am the Data Scientist shard. I am about to build visualizations for study [name].
+  Please review the planned chart types and suggest improvements before I build them.
+  This is a design review only — I will implement.
+
+  Study context:
+  - Business question: [from Phase 1]
+  - Primary audience: [from Phase 1]
+  - Visualisation style preference: [Clean/minimal | Exploratory, from Phase 5]
+  - Planned visualizations: [list chart types, what each shows, data basis — e.g.,
+    'line chart of monthly churn rate by cohort', 'bar chart of feature importances']
+
+  Please review:
+  1. Are the chart types appropriate for the data and this audience?
+  2. Are there better alternatives I should use?
+  3. Any design or layout recommendations given the intended audience?
+  4. Any visualizations I should add that would strengthen the findings?
+  Return your review as: Approved (proceed as planned) | Concerns raised (flag issues)."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `bi-engineer` row).
+
+Skip this consultation only if the primary deliverable is "data file only" with no charts or if no visualizations are planned.
+
+### Document Phase 5
+
+```markdown
+---
+
+## Phase 5: Output Format (Data Scientist)
+- **Primary deliverable:** Notebook | Slide summary | Data file | Other
+- **Sections included:** <list: EDA, modeling, recommendations, etc.>
+- **Visualisation style:** Clean/minimal | Exploratory
+- **Reproducibility requirement:** Self-contained | One-time
+- **Additional deliverables:** <requirements.txt, summary doc, or "none">
+- **BI Engineer chart design review:** N/A — no visual deliverables | <summary>
+  - Verdict: Approved | Concerns raised
+  - Tier: Proceed | Proceed with caveats
+  - Reviewer resolution: Approved | User override — <rationale>
+```
+
+::GATE:: id=data-scientist-phase-5 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::
+
+---
+
+## When this gate is confirmed
+
+Read `.claude/agents/specific_instructions/data_scientist/phases/phase-6.md` in full and follow its instructions starting from Phase 6. Do not pre-read further phase files.

package/src/agents/specific_instructions/data_scientist/phases/phase-6.md

@@ -0,0 +1,239 @@
+> **Previous:** phase-5.md confirmed
+> **Next:** phase-7.md (read only after this phase's gate is confirmed)
+
+---
+
+## Phase 6 — Build (queries and notebook)
+
+**Context checkpoint:** Before building, prompt the user:
+
+"Planning's locked — good moment to run `/compact` or `/clear` before we start
+building. 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 Phase 6. "Beginning Phase 6" includes the reviewer Task calls below — do not fire them until the user signals readiness.
+
+**Knowledge re-check:** Follow `.claude/agents/specific_instructions/shared/knowledge_checkpoint.md` before building.
+
+Goal: Write the SQL queries and the notebook. **No execution.** SQL is reviewed and validated under `LIMIT 100` by the Analytics Engineer in Phase 7. The notebook is run by the user (or via the `/notebook-walkthrough` mode) outside the build flow. Phase 6 is a write-only phase.
+
+**Join path self-check:** Before requesting the Data Modeller review, trace the
+join path for each query following `.claude/agents/specific_instructions/shared/join_path_protocol.md`.
+Present the trace to the user. Include the trace in the Data Modeller review
+prompt below so the DM validates your reasoning, not just your SQL.
+
+**Then request Data Modeller review with validation:**
+
+Tell the user: "Asking the Data Modeller to verify sql queries (i.e. joins and grain before writing them out)."
+
+```
+Task(
+  subagent_type="data-modeller",
+  description="Review queries for [study]",
+  prompt="I am the Data Scientist shard. I've drafted queries for study [name].
+  The project specs are at: studies/[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?
+
+  Run validation queries to check:
+  1. PK uniqueness on all tables I'm joining
+  2. Null rates on my join keys and critical filter columns
+  3. Join fan-out: row counts before/after my key joins
+  4. Data freshness on the tables I'm querying
+
+  Cross-reference the validation results against the study requirements in
+  project-specs.md (especially the grain and data sources from Phase 2).
+  Return your full review with query validation results."
+)
+```
+
+The Data Modeller will run a bulk read-only validation sweep — that's an
+auto-verify fit on the consultation side. No marker is needed on your side
+for the Task call itself.
+
+**Also request Researcher review of the analysis approach:**
+
+Tell the user: "I'm also asking the Researcher shard to review the analytical
+approach for statistical validity..."
+
+```
+Task(
+  subagent_type="researcher",
+  description="Review analysis approach for [study]",
+  prompt="I am the Data Scientist shard preparing study [name]. Here is the
+  analytical approach I'm about to encode in queries and notebook cells:
+  - Methodology: [from Phase 3]
+  - Queries: [include query outlines or key SQL]
+  - Feature engineering: [if applicable, key transformations]
+  - Evaluation approach: [metrics, validation strategy]
+  Please review: Any concerns about how the methodology is being implemented?
+  Outlier handling appropriate? Transformations sound? Statistical tests valid
+  for the data characteristics? Keep review focused on what gets written into
+  the queries and notebook."
+)
+```
+
+Apply the Reviewer Verdict Protocol independently for each reviewer (see shared protocol — `data-modeller`, `researcher` rows). Address all Halt-tier verdicts before proceeding to build.
+
+### Reviewer-verdict checkpoint
+
+After both reviewers return and you have applied the Reviewer Verdict Protocol to each, emit the gate below. **Do not begin writing SQL or notebook cells until the user confirms this gate.** This applies regardless of verdict tier — even when both reviewers return clean "Proceed", the user must explicitly confirm before build begins.
+
+```
+::GATE:: id=data-scientist-phase-6-checkpoint-reviewers phase=6 kind=checkpoint
+Component: Reviewer verdicts (Data Modeller + Researcher)
+Data Modeller verdict: <Proceed | Proceed with caveats | Halt> — <one-line summary>
+Researcher verdict: <Proceed | Proceed with caveats | Halt> — <one-line summary>
+Resolution: <action taken for each — e.g., "Both Proceed; no fixes needed" or "DM raised grain concern → switched to teacher-week grain; Researcher Proceed">
+Status: PASS — ready to build
+Next: SQL queries (build step 1)
+Stop here — await explicit confirmation before writing the next component.
+::ENDGATE::
+```
+
+### Build scope
+
+The deliverables are SQL files under `studies/<name>/queries/` and a notebook under `studies/<name>/notebooks/`. **Write only — do not execute the SQL or run notebook cells in this phase.** Do not introduce standalone Python loader, helper, or "data prep" scripts — data loading and transformation live in notebook cells per the SQL-loading rule below. If something genuinely belongs in a `.py` module (a long shared utility used across notebooks), surface it to the user and confirm before writing it. A freestanding `load_data.py` is almost always a sign you're building outside the plan.
+
+### Incremental testing — checkpoint gates between components
+
+Follow `.claude/agents/specific_instructions/shared/incremental_testing.md` during this build. Each numbered build step below ends with a `kind=checkpoint` gate emission — after you write the component, emit the gate fence and wait for user confirmation before starting the next component. The "test" in this build-only phase is structural — you read back what you wrote and confirm it matches the Phase 3 plan; you do not execute it.
+
+**Worked example — emit checkpoint gates in exactly this shape.** Both `::GATE::` and `::ENDGATE::` fences are required. All readback lives *inside* the fence body. No prose above `::GATE::` and no prose after `::ENDGATE::` — the fence is the entire emission.
+
+```
+::GATE:: id=data-scientist-phase-6-checkpoint-notebook phase=6 kind=checkpoint
+Component: Jupyter notebook (full)
+Verification: structural read-back against Phase 3 cell-list plan (no execution)
+Evidence:
+  - Path: studies/teacher_churn/notebooks/teacher_churn.ipynb
+  - Cells written: 22 (4 markdown headers, 18 code) across Overview / Setup / Data load / EDA / Analysis / Results / Caveats
+  - SQL files referenced: queries/01_feature_extraction.sql, queries/02_cohort_definition.sql (loaded via Path.read_text())
+  - SQL-loading-rule compliance: PASS — no embedded SQL strings
+  - Phase 3 plan match: 22/22 sections present; one deviation noted (split EDA section into 2 sub-blocks for readability)
+Status: PASS — notebook structure matches Phase 3 plan, ready for Phase 7 review
+Next: Phase 7 documentation and code review fan-out
+Stop here — await explicit confirmation before writing the next component.
+::ENDGATE::
+```
+
+The values above are illustrative — substitute real measurements from your actual run. The *shape* (id / Component / Verification / Evidence / Status / Next / Stop here / ENDGATE) is fixed.
+
+For reference the abstract schema is:
+
+```
+::GATE:: id=<agent-name>-phase-<N>-checkpoint-<component> phase=<N> kind=checkpoint
+Component: <human-readable name>
+Verification: <the verification action you took — for build-only phases this is "structural read-back against [plan]"; for build-and-run phases this is the exact command you ran>
+Evidence:
+  - <measured fact 1>
+  - <measured fact 2>
+  - <measured fact 3>
+Status: PASS | FAIL — <one-line summary>
+Next: <what you'll build after this is confirmed>
+Stop here — await explicit confirmation before writing the next component.
+::ENDGATE::
+```
+
+**Common deviations to avoid.** The gate hook requires both `::GATE::` and `::ENDGATE::` to match — a bare `::GATE::` line with no closing fence emits zero enforcement. Do not:
+
+- Put decision summaries, context bullets, or component descriptions *outside* the fence (above `::GATE::` or below `::ENDGATE::`). All readback content lives inside the fence body.
+- Replace the `Component / Verification / Evidence / Status / Next` body with free prose or an open question. The user confirms by reading the fence body itself.
+- Append "Good to proceed?" after `::ENDGATE::`. The "Stop here — await explicit confirmation" line built into the fence body is sufficient. Post-fence prose either trips the hook's post-fence violation check (>40 words or phase-advance phrasing) or muddles the readback the user is supposed to confirm — neither is wanted.
+- Invent a gate ID outside the per-step IDs called out in the build steps below (e.g., `...checkpoint-sql` instead of `...checkpoint-queries`). The IDs are part of the contract.
+- Run the SQL or execute the notebook to gather evidence. Phase 6 is write-only. SQL is run under `LIMIT 100` by the Analytics Engineer in Phase 7; the notebook is run by the user or via `/notebook-walkthrough` outside this flow.
+- Emit a checkpoint for a script that isn't part of the build plan. If you find yourself wanting to checkpoint a `load_data.py`, stop — that script shouldn't exist (see Build scope above).
+
+The hook blocks all non-read tools while a checkpoint is open. If a checkpoint fails (e.g., structural review reveals a missing section vs. the Phase 3 plan), fix the artifact and re-emit with updated evidence before advancing.
+
+### Then build (each step ends with its own checkpoint gate)
+
+**1. SQL queries — write, then checkpoint.**
+   - Write to `studies/<name>/queries/`
+   - Name files descriptively: `01_feature_extraction.sql`, `02_cohort_definition.sql`
+   - Include header comments:
+     ```sql
+     -- Study: <study_name>
+     -- Query: <description>
+     -- Date: <date>
+     -- Dependencies: <upstream tables>
+     -- Output grain: one row per <entity>
+     ```
+   - Verify structurally: every query has the header block; the join path in each query matches the trace you presented under the join-path self-check; every required table from the Phase 2 data sources is referenced.
+   - Emit the gate `::GATE:: id=data-scientist-phase-6-checkpoint-queries phase=6 kind=checkpoint` with structural evidence: file paths and counts, header-comment compliance, one-line join-path summary per query, any deviations from Phase 3 plan.
+   - Wait for user confirmation before step 2.
+
+**2. Notebook — write, then checkpoint.** Create the notebook at `studies/<name>/notebooks/<study>.ipynb` using NotebookEdit. Write all sections in this single step:
+
+   - **Overview** (markdown): business question, hypothesis, data sources, date, author
+   - **Setup**: imports, config, reproducibility notes
+   - **Data load**: cells that read each `.sql` file and produce the analysis dataframe(s) — see SQL loading rule below
+   - **EDA**: target distribution, feature distributions, missingness, correlations
+   - **Analysis / Modelling**: implement chosen method
+   - **Results**: key numbers, visualizations, model performance with business interpretation
+   - **Recommendations**: top 2–3 actionable findings with confidence levels
+   - **Caveats and Limitations**: what this can't answer, assumptions, data quality
+
+   **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/01_feature_extraction.sql").read_text()
+   df = pd.read_sql(sql, conn)
+   ```
+
+   Verify structurally: every section listed above is present; the section list matches the Phase 3 plan; every `.sql` file under `queries/` is loaded by at least one cell via `Path.read_text()`; no SQL is embedded as Python strings; no stray `.py` loaders were created.
+
+   Emit the gate `::GATE:: id=data-scientist-phase-6-checkpoint-notebook phase=6 kind=checkpoint` with structural evidence: notebook path, total cell count and per-section breakdown, SQL files referenced, SQL-loading-rule compliance status, deviations from the Phase 3 plan if any.
+
+   Wait for user confirmation before step 3.
+
+**3. Requirements file — no checkpoint.** If analysis needs non-standard packages, create `requirements.txt`. Optional.
+
+### Document Phase 6
+
+```markdown
+---
+
+## Phase 6: Build Log (Data Scientist)
+- **Data Modeller query review:**
+  - Verdict: Approved | Concerns raised
+  - Tier: Proceed | Proceed with caveats
+  - Notes: <summary>
+  - Reviewer resolution: Approved | User override — <rationale>
+- **Researcher build review:**
+  - Verdict: Sound | Concerns | Revise
+  - Tier: Proceed | Proceed with caveats | Halt
+  - Notes: <summary of statistical build review>
+  - Reviewer resolution: Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Query files:**
+  - <file path>: <description>
+- **Notebook location:** <file path>
+- **Notebook cell count:** <total> (<markdown>/<code>)
+- **Requirements file:** <file path or "N/A — base Python only">
+- **Deviations from plan:** <changes from Phases 3–5 and why, or "none">
+- **Phase 6 produced no execution evidence by design** — SQL validation runs in Phase 7 (Analytics Engineer); notebook execution is user-managed or via `/notebook-walkthrough`.
+
+### Validation
+
+Roll up the structural evidence from the three in-phase checkpoint gates. Copy the Status + key Evidence facts directly from each gate body so this section is auditable on its own without rereading every checkpoint.
+
+| Checkpoint | Status | Key evidence |
+|---|---|---|
+| reviewers | PASS | DM: <verdict>; Researcher: <verdict>; Resolution: <action> |
+| queries | PASS \| FAIL | <file count and paths>; <header-comment compliance>; <join-path summary>; <deviations from Phase 3 plan> |
+| notebook | PASS \| FAIL | <notebook path>; <cell count and per-section breakdown>; <SQL files referenced>; <SQL-loading-rule compliance>; <Phase 3 plan match> |
+```
+
+::GATE:: id=data-scientist-phase-6 phase=6 kind=phase validates=data_scientist
+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/data_scientist/phases/phase-7.md` in full and follow its instructions starting from Phase 7. Do not pre-read further phase files.

package/src/agents/specific_instructions/data_scientist/phases/phase-7.md

@@ -0,0 +1,207 @@
+> **Previous:** phase-6.md confirmed
+> **Next:** This is the final phase — follow the Syn sign-off instructions in this phase to close the project.
+
+---
+
+## Phase 7 — Review and Handoff
+
+**Code review (Python scripts, notebooks, and SQL):**
+
+Tell the user: "Before Syn reviews this, we're running code review. Python
+scripts → Backend Engineer; notebooks → ML Engineer; SQL queries → Analytics
+Engineer (review + LIMIT 100 validation). Peer review is good science."
+
+Glob the project directory (`studies/<study_name>/`) for `.py` files,
+`.ipynb` files, and `.sql` files — three separate buckets.
+
+**Python scripts → Backend Engineer** (only if any `.py` files were found):
+
+```
+Task(
+  subagent_type="backend-engineer",
+  description="Python code review for [study_name]",
+  prompt="You are in SERVICE MODE. Review the Python scripts in the project at
+  studies/[study_name]/. Read project-specs.md first for context.
+  Files to review: [list of .py files found]"
+)
+```
+
+**Notebooks → ML Engineer** (only if any `.ipynb` files were found). Cross-
+shard review — the ML Engineer catches code quality, modelling, and
+production-alignment issues that the author of the notebook is likely blind
+to:
+
+```
+Task(
+  subagent_type="ml-engineer",
+  description="Notebook code review for [study_name]",
+  prompt="SERVICE MODE — NOTEBOOK CODE REVIEW. Review the Jupyter notebooks in
+  the project at studies/[study_name]/. Read project-specs.md first for
+  context.
+  Files to review: [list of .ipynb files found]
+  Your job here is review only — do not apply any fixes."
+)
+```
+
+**SQL queries → Analytics Engineer** (only if any `.sql` files were found).
+Cross-shard review — the AE catches grain, fan-out, and source-layer issues
+that the Data Scientist may have missed, and validates each query under
+LIMIT 100:
+
+```
+Task(
+  subagent_type="analytics-engineer",
+  description="SQL code review + LIMIT 100 validation for [study_name]",
+  prompt="SERVICE MODE — CODE REVIEW. Review the following SQL files in
+  studies/[study_name]/. Read project-specs.md first for context.
+  Files to review: [list of .sql files found]
+
+  Beyond the standard code review pass (correctness, quality, security,
+  performance, domain fit), please ALSO execute each query under LIMIT 100
+  and report:
+  - Row count under LIMIT, column list, and dtypes
+  - Join fan-out (multi-table queries only): left row count vs. joined row count
+  - Any unexpected NULLs on join keys or critical filter columns
+  - Match against the Phase 3 grain and join path documented in project-specs.md
+
+  The LIMIT 100 sweep is a read-only validation — feel free to open an
+  ::AUTO-VERIFY:: marker if it speeds up your run.
+
+  Your job here is review + validation only — do not apply any fixes."
+)
+```
+
+If two or more buckets are non-empty, fire all Task calls in parallel. If all
+buckets are empty, report "No code artifacts — skipping code review."
+
+Append all reviews to project-specs.md under a combined `Code Review` heading.
+
+**After appending the reviews, branch on the worst verdict across all reviewers:**
+
+- **Clean or Minor Issues** → proceed directly to Syn review.
+- **Refactor Required** → tell the user: "Reviewer(s) flagged structural
+  issues. Fixing before Syn review." Address every listed issue in the
+  project files. Update project-specs.md. Re-gate: "Reviewer issues resolved:
+  [summary]. Confirm to proceed to Syn?" Then proceed to Syn.
+- **Blocked** → tell the user: "Reviewer has blocked this. Fixing critical
+  issues before continuing." Address every critical issue. Update
+  project-specs.md. Resubmit to the same reviewer(s) once. If the second
+  verdict is Clean/Minor Issues/Refactor Required, proceed to Syn. If still
+  Blocked, surface to user: "Reviewer 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."
+
+---
+
+**Before finalizing**, invoke Syn for final review:
+
+Tell the user: "I'm asking Syn to review the full project specs before we wrap this up..."
+
+```
+Task(
+  subagent_type="syn",
+  description="Final review of data science study",
+  prompt="I am the Data Scientist shard. I've completed all phases for study
+  [study_name]. Please review the project-specs.md at [file_path] and provide
+  your final review verdict. Check methodology, data sufficiency, results
+  interpretation, and completeness."
+)
+```
+
+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 data science study",
+  prompt="CODE REVIEW MODE. I am the Data Scientist shard. Project: [study_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. **Write the report** to `studies/<name>/report.md` using the report template.
+   Include: executive summary, background, methodology, key findings,
+   recommendations with confidence levels, caveats, and next steps.
+
+2. Summarize top findings in 3-5 plain-language bullet points
+3. State top 2-3 recommended actions with confidence levels
+4. Flag open questions or follow-up analyses
+5. Ask if the result answered the original decision question
+
+6. **If Deployment intent was "Productionized"** see `.claude/agents/specific_instructions/data_scientist/ml_engineer_handoff.md` for the full handoff instructions (Phase 7, Step 6 section).
+
+7. **BI dashboard handoff (recurring visualizations):** See `.claude/agents/specific_instructions/data_scientist/bi_engineer_handoff.md` for the full handoff instructions (Phase 7, Step 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: Findings and Handoff (Data Scientist)
+- **Backend Engineer Review (.py scripts):** <summary or N/A — list files reviewed, overall verdict>
+- **ML Engineer Review (.ipynb notebooks):** <summary or N/A — list notebooks reviewed, overall verdict>
+- **Analytics Engineer Review (.sql queries):** <summary or N/A — list files reviewed, overall verdict, LIMIT 100 validation findings (row counts / fan-out / null anomalies)>
+- **Syn Review:** <included above>
+- **Syn review resolution:** Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Report location:** <file path>
+- **Top findings:**
+  1. <finding — plain language>
+  2. <finding — plain language>
+  3. <finding — plain language>
+- **Recommended actions:**
+  1. <action> — Confidence: High | Medium | Low
+  2. <action> — Confidence: High | Medium | Low
+  3. <action> — Confidence: High | Medium | Low
+- **Open questions / follow-ups:**
+  - <question or follow-up>
+- **Original question answered:** Yes | Partially | No — <explanation>
+- **Productionization handoff:** Yes — ML Engineer | No — one-off study
+- **If handoff — ML Engineer handoff file:** studies/<project_name>/ml_engineer_handoff.md | N/A
+- **BI dashboard handoff:** Yes — studies/<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=data-scientist-phase-7 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::
+
+---
+
+## When this gate is confirmed
+
+This is the final phase. Once Syn returns APPROVED sign-off, the project is complete. Do not read further files.