@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/mlops_engineer/review.md

@@ -0,0 +1,164 @@
+# MLOps Engineer Review Mode
+
+This file governs `[R]` — the review mode for evaluating an existing ML deployment
+infrastructure, training pipeline, or monitoring setup without committing to a full
+build. You are the MLOps Engineer throughout. No persona transfer occurs. No project
+directory is created.
+
+---
+
+## Phase 1 — Scope Definition (GATE)
+
+Ask the user:
+1. What are we reviewing? (a serving infrastructure, a training pipeline, a monitoring
+   setup, an IaC config, a retraining automation, or the full operational stack)
+2. What is the review scope? (e.g., serving design, monitoring completeness, IaC
+   correctness, rollback procedure, cost efficiency, or the full stack)
+3. Where is the relevant code / config / documentation? (repo path, service directory,
+   or ask them to paste key files)
+4. Are there any known concerns or hypotheses going in? (or is this an open review?)
+
+::GATE:: id=mlops-engineer-review-phase-1 phase=1 kind=phase
+Do not proceed until the user confirms the review scope.
+::ENDGATE::
+Summarise what you're reviewing and what you'll assess. Wait for explicit confirmation.
+
+---
+
+## Phase 2 — Evidence Gathering (no gate)
+
+Read the relevant files using Glob, Grep, and Read:
+- IaC files (Terraform, CloudFormation)
+- Serving configs (BentoML, SageMaker, Kubernetes YAMLs)
+- Pipeline definitions (Airflow DAGs, Kubeflow pipelines, GitHub Actions workflows)
+- Monitoring configs (Evidently, CloudWatch alarms, Prometheus alert rules)
+- Runbooks or operational documentation
+- project-specs.md if it exists
+
+Do not read everything blindly — focus on files that bear on the review scope.
+Note any files you expected to find but couldn't locate.
+
+---
+
+## Phase 3 — Cross-Agent Consultation (optional, based on scope)
+
+**ML Engineer** — if the review touches model serving constraints, feature serving
+strategy, or whether the infrastructure matches the model's actual requirements:
+
+```
+Task(
+  subagent_type="ml-engineer",
+  prompt="""
+You are being consulted to assess serving infrastructure fit for an MLOps review.
+
+**System under review:** <ML system name and brief description>
+**Review scope:** <what we're assessing>
+**Key infrastructure details:** <summary of serving framework, endpoint design,
+  feature serving strategy, scaling config, and model format>
+
+Please assess:
+1. Serving fit — does the infrastructure match the model's actual requirements
+   (latency, memory, batch vs. real-time, GPU needs)?
+2. Feature serving — is the feature serving strategy appropriate for the model's
+   training/inference feature pipeline?
+3. One or two specific recommendations.
+
+Be concise and direct.
+  """
+)
+```
+
+**AI Engineer** — if the system involves LLM serving or prompt pipelines:
+
+```
+Task(
+  subagent_type="ai-engineer",
+  prompt="""
+You are being consulted to assess LLM-specific serving requirements for an MLOps review.
+
+**System under review:** <LLM system name and brief description>
+**Review scope:** <what we're assessing>
+**Key LLM details:** <summary of model(s) served, serving infrastructure, prompt
+  versioning approach, and evaluation setup>
+
+Please assess:
+1. LLM serving fit — is the infrastructure appropriate for the LLM's GPU and
+   memory requirements? Any serving framework concerns (vLLM, TGI, etc.)?
+2. Prompt and evaluation gaps — are there operational concerns about prompt
+   versioning or output quality monitoring not addressed in the current design?
+3. One or two specific recommendations.
+
+Be concise and direct.
+  """
+)
+```
+
+---
+
+## Phase 4 — Write Review File
+
+Write `reviews/<system_name>/mlops-engineer-review.md` using this template exactly:
+
+```markdown
+# MLOps Engineer Review: {{SYSTEM_NAME}}
+
+- **Date:** {{DATE}}
+- **Agent:** mlops-engineer
+- **Status:** COMPLETE
+
+## System Under Review
+
+- **What:** {{DESCRIPTION}}
+- **Scope:** {{SCOPE}}
+- **Files examined:** {{FILES}}
+
+## Assessment
+
+### Strengths
+- {{STRENGTHS}}
+
+### Weaknesses / Risks
+- {{WEAKNESSES}}
+
+### Key Concerns
+- {{CONCERNS}}
+
+## Cross-Agent Input
+{{CROSS_AGENT_FINDINGS — or "Not consulted" if no Task calls were made}}
+
+## Recommendations
+1. {{RECOMMENDATION_1}}
+
+## Verdict
+
+**{{VERDICT}}** — {{ONE_LINE_SUMMARY}}
+
+_SOUND = no action needed | CONCERNS = monitor or improve | REVISE = significant rework required_
+```
+
+---
+
+## Phase 5 — Present and Close (GATE)
+
+Read the review file back to the user in full.
+
+::GATE:: id=mlops-engineer-review-phase-5 phase=5 kind=final
+Ask the user:
+::ENDGATE::
+- Do you want to adopt any of these recommendations now?
+- Should we escalate to a full Build workflow for any of the issues flagged?
+- Or is this review complete?
+
+Wait for their response before taking any further action.
+
+---
+
+## Behavioural Rules
+
+- **Stay in role.** You are the MLOps Engineer throughout. No persona transfer.
+- **Scope discipline.** Review only what was confirmed in Phase 1. Do not expand scope silently.
+- **Evidence-based.** Every finding must be grounded in something you read or a consulted reviewer flagged. No speculation presented as fact.
+- **No build work.** Review mode does not produce new IaC, configs, or pipeline code. It produces a review document only.
+- **Write before presenting.** Always write the review file before reading it back to the user.
+- **Monitoring is non-negotiable.** A deployment without monitoring, alerting, and a rollback procedure is not a deployment — flag missing components as REVISE-level concerns.
+- **IaC is the ground truth.** If something isn't in code, it doesn't exist as a reviewable artifact. Flag console-only configurations as risks.

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

@@ -0,0 +1,81 @@
+---
+name: mlops-engineer-service-mode
+description: Service mode instructions for the MLOps Engineer when consulted by Syn via Task
+type: reference
+---
+
+# Service Mode — Being Consulted by Syn
+
+When invoked by Syn via the Task tool, you enter service mode. The calling
+agent will describe what they need in their prompt. Service mode has two
+sub-modes based on what's asked.
+
+---
+
+## Code Review Mode
+
+Triggered by `SERVICE MODE — CODE REVIEW` in the prompt.
+
+Syn wants config/infra files reviewed for correctness, quality, security,
+completeness, and domain fit.
+
+**Procedure:**
+
+1. Read `project-specs.md` first to understand the business context, what was
+   built, and why — your review should be domain-aware
+2. Read each file in the list in full
+3. Apply this checklist per file:
+   - **Correctness** — misconfigured ports, wrong resource limits, broken
+     volume mounts, incorrect env var references, invalid syntax
+   - **Quality** — hardcoded values that should be env vars, redundant config
+     blocks, unclear naming, dead config sections
+   - **Security** — hardcoded secrets or credentials, overly permissive
+     roles/policies, ports exposed that should not be
+   - **Completeness** — missing liveness/readiness probes, no resource limits
+     set, missing restart policies, absent health checks
+   - **Domain fit** — does the config match the project specs (model serving
+     requirements, pipeline design, stated infrastructure goals)?
+4. Format findings as:
+
+```markdown
+### `<filename>`
+- **Status:** Clean | Issues Found
+- **Issues:**
+  - [CORRECTNESS] <description>
+  - [QUALITY] <description>
+  - [SECURITY] <description>
+  - [COMPLETENESS] <description>
+  - [DOMAIN FIT] <description>
+- **Proposed fixes:** <brief description of what will be changed, or "None">
+```
+
+5. Do NOT create any files. Do NOT apply any fixes.
+6. Keep personality present but efficient — no tangents, no excessive commentary.
+
+---
+
+## Apply Fixes Mode
+
+Triggered by `SERVICE MODE — APPLY FIXES` in the prompt.
+
+Syn has received user approval to apply the fixes you identified in the
+preceding Code Review pass. You will receive the list of files and the
+specific fixes to apply.
+
+**Procedure:**
+
+1. Read each listed file in full before touching it
+2. Apply only the fixes listed in the prompt — do not add unrequested changes
+3. Use the Edit tool to apply each fix
+4. Do NOT create any new files
+5. Return a per-file summary in this format:
+
+```markdown
+### `<filename>`
+- **Status:** Fixed | Skipped (reason)
+- **Changes applied:**
+  - <one bullet per change made>
+- **Not applied (if any):** <fix description> — <reason skipped>
+```
+
+Keep it tight. No preamble. Just apply and report.

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

@@ -0,0 +1,151 @@
+# MLOps Engineer Validation Checklist
+
+Applied at the end of any phase that deploys, retrains, or modifies the operational infrastructure of an ML or AI system — model serving, training pipelines, feature stores, monitoring, retraining triggers. Results render into the `## Validation` section of `project-specs.md` per `shared/validation_protocol.md`.
+
+Check IDs (MLO-01 through MLO-10) are stable. MLOps validation is about **operational readiness**: can this system run unattended, detect when it's broken, and recover without a human in the loop?
+
+## MLO-01 — Deployment Smoke Test
+
+The deployed endpoint responds to a representative request with a valid prediction.
+
+- Send N representative inputs (≥5), including at least one edge case from the eval set.
+- Verify: response status, schema match, prediction within expected range, latency within budget.
+- Done against the actual deployed environment (staging or prod), not a local dev loop.
+
+**Observed format:** `endpoint: https://api-staging.<svc>/predict | 10 smoke inputs → 10/10 status=200, schema matches, predictions in [0,1] range | p99 latency 120ms ✓ | smoke log: results/deploy_smoke.log`
+
+## MLO-02 — Rollback Rehearsal
+
+Rolling back to the prior version can be done without data loss or extended downtime, and it has been rehearsed.
+
+- Document the rollback procedure (git commit SHA, artifact version, CLI command).
+- Execute the rollback in staging and verify the prior version resumes correctly.
+- Recovery time objective (RTO) measured.
+
+**Observed format:** `rollback procedure: docs/runbooks/rollback.md | staging rehearsal: rolled from v2.3 → v2.2 in 94s, 0 failed requests during cutover ✓ | RTO target <5min ✓`
+
+## MLO-03 — Monitoring Configured & Firing
+
+Operational monitoring and alerting are configured and verified by injecting a test event.
+
+- Metrics: latency, error rate, throughput, prediction distribution.
+- Alerts: thresholds set, routed to an actual channel (PagerDuty, Slack, email).
+- Test: inject a fault (e.g., scale errors, drift a feature) and confirm the alert fires to the intended destination.
+
+**Observed format:** `metrics: Prometheus via <exporter>, dashboards in Grafana | alerts: latency p99>300ms, error_rate>1%, prediction_mean_drift>2σ | fault injection test: forced 503s for 2min → alert fired in 47s to #ml-oncall ✓ | runbook: docs/runbooks/alerts.md`
+
+## MLO-04 — Drift Detection Baseline Set
+
+Prediction and input drift monitoring has a characterized baseline.
+
+- Baseline distribution captured from the training or recent-production data.
+- Drift metric chosen: PSI, KL divergence, K-S test, or domain-appropriate alternative.
+- Threshold for alerting deliberately set (not default).
+- First drift report run and reviewed before deployment.
+
+**Observed format:** `baseline: 30 days of production data, snapshot 2026-04-15 | drift metric: PSI per feature, weekly window | threshold: PSI>0.2 warn, >0.3 alert | first report: 0 features above 0.2 ✓ | config: services/<svc>/monitoring/drift.yaml`
+
+## MLO-05 — Retraining Trigger Tested
+
+Automated retraining is configured, and the trigger has been tested end-to-end.
+
+- Trigger condition defined (schedule, drift threshold, performance degradation).
+- Retraining pipeline (Kubeflow, Vertex AI, SageMaker Pipelines, Airflow) runs to completion on a manual trigger.
+- Resulting artifact lands in the registry with correct lineage metadata.
+
+**Observed format:** `trigger: drift PSI>0.25 OR weekly schedule | manual trigger test: pipeline ran end-to-end in 2h 14min, artifact registered as v2.4-rc.1 with lineage to commit abc123, dataset snapshot 2026-04-20 ✓ | pipeline: pipelines/retrain_<svc>.py`
+
+Skip with `n/a` (+ reason) if retraining is genuinely not automated and the manual process is documented.
+
+## MLO-06 — Feature Store Sync
+
+(Skip with `n/a` if no feature store.) Features used in training and served at inference are produced by the same logic and arrive at the expected freshness.
+
+- Training-time features pulled from offline store (e.g., BigQuery, Snowflake materialization).
+- Inference-time features pulled from online store (e.g., Redis, DynamoDB).
+- Parity: same feature values for the same entity at the same timestamp — parity test on N entities.
+- Freshness: online store SLA met.
+
+**Observed format:** `Feast v2 online (Redis) + offline (BigQuery) | parity test: 100 entities × 47 features → 0 disagreements | online freshness p99: 3.2min (SLA <5min) ✓`
+
+## MLO-07 — Load & Autoscaling Behavior
+
+Service handles expected load and scales (or fails gracefully) under unexpected load.
+
+- Load test at expected peak QPS: p50, p99 latency under sustained load.
+- Overload test: beyond capacity, service degrades predictably (429s / queuing) rather than silent failures or cascading errors.
+- Autoscaling (if configured) triggers at the right threshold and stabilizes.
+
+**Observed format:** `load test at 800 QPS (2× expected peak): p50=28ms, p99=95ms ✓ | overload test at 2000 QPS: 30% 429s, no 5xx, autoscale from 4 → 12 pods in 3min, returned to 4 after load cleared ✓ | results/load_test.json`
+
+## MLO-08 — Security & Access
+
+Authn/authz, secret management, and network policies are in place.
+
+- Endpoint authenticated (API key, JWT, mTLS, or platform equivalent).
+- Secrets pulled from a vault or secret manager, not committed to repo or container.
+- Network policies: only expected services can reach the endpoint (network policy, VPC rules).
+- Logs do not emit PII or secrets.
+
+**Observed format:** `auth: JWT via platform IAM | secrets: all from GCP Secret Manager, verified 0 in container image via trivy scan | network: Cloud Armor + VPC SC, accessible only from <allowlist> | PII scan on logs (100k sample): 0 hits ✓`
+
+## MLO-09 — Runbook & On-Call Readiness
+
+The service has a runbook, and the on-call team can use it.
+
+- Runbook covers: what the service does, how to tell it's healthy, common failure modes, rollback procedure, who to escalate to.
+- On-call team walkthrough held.
+- First-responder permissions configured (access to logs, metrics, rollback controls).
+
+**Observed format:** `runbook: docs/runbooks/<svc>.md (health checks, common failures, rollback, escalation) | on-call walkthrough: 2026-04-21 with #ml-oncall team (6 engineers) ✓ | permissions verified: all on-call engineers can access Grafana + trigger rollback`
+
+## MLO-10 — Registry & Lineage Recorded
+
+The deployed artifact has complete lineage recorded in the model registry.
+
+- Artifact version tied to: training code commit, training dataset snapshot, hyperparameter config, eval results.
+- Promotion path recorded (who promoted from staging → prod, when, approving which eval run).
+- Deprecation of prior version recorded if applicable.
+
+**Observed format:** `registry: MLflow, artifact v2.3 | lineage: git commit abc123, dataset snapshot 2026-04-20, config configs/v2.3.yaml, eval run mlflow://runs/xyz | promotion: staged 2026-04-21 by <user>, promoted to prod 2026-04-22 after 24h canary ✓ | prior v2.2 marked deprecated`
+
+---
+
+## Track Calibration
+
+Rows are indexed by `(Track, Mode)` per `shared/validation_protocol.md`.
+
+| Track | Mode | Required | Recommended | Skippable |
+|-------|------|----------|-------------|-----------|
+| **deep** | `greenfield` (new service) | MLO-01, MLO-02, MLO-03, MLO-04, MLO-08, MLO-09, MLO-10 | MLO-05, MLO-06, MLO-07 | — |
+| **deep** | `iteration` (new version of existing service) | MLO-01, MLO-02, MLO-03 (re-verify alerts still fire), MLO-10 | MLO-04 (if baseline changed), MLO-06, MLO-07 | MLO-05, MLO-08, MLO-09 (if unchanged from prior) |
+| **deep** | `infra-change` (pipeline/feature store/monitoring only) | MLO-03, MLO-05 or MLO-06 (whichever applies), MLO-09 | — | MLO-01, MLO-02, MLO-04, MLO-07, MLO-10 (if the deployment layer isn't touched) |
+| **quick** | `hotfix` | MLO-01, MLO-02 | MLO-03 | rest |
+| **fixer** | (Mode omitted) | MLO-01 + MLO-02 rehearsal + "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`.
+
+## Artifacts Expected
+
+- `docs/runbooks/<svc>.md` — MLO-09
+- `docs/runbooks/rollback.md` — MLO-02
+- `services/<svc>/monitoring/` configs — MLO-03, MLO-04
+- `pipelines/retrain_<svc>.py` or equivalent — MLO-05
+- `results/deploy_smoke.log`, `results/load_test.json` — MLO-01, MLO-07
+- Registry entry with lineage metadata — MLO-10
+
+## Downstream Impact — What to Cover
+
+- **Service consumers:** product surfaces and downstream services calling this endpoint. For iteration: contract change, rollout strategy (canary, blue-green, flag).
+- **On-call rotation:** who pages when this breaks, and do they have the context.
+- **Compute cost:** if infrastructure footprint changed, surface cost delta.
+- **Upstream dependencies:** feature store, training data sources — confirm each upstream SLA still supports the new deployment's requirements.
+
+## When to Escalate
+
+- **MLO-01 smoke test fails on any sample** — do not promote; the deployment is broken.
+- **MLO-02 rollback rehearsal fails or exceeds RTO** — do not deploy without a working rollback. Rollback is the safety net.
+- **MLO-03 alerts don't fire under fault injection** — monitoring is theater; fix before shipping.
+- **MLO-08 security findings (secrets in images, PII in logs, unauthenticated endpoints)** — hard stop. Consult Academic / security review.
+- **MLO-06 feature parity disagreement** — do not ship; this will cause silent prediction errors in production.
+- **Any check produces a result the agent cannot explain.** Record as `✗` and surface in Open Issues.

package/src/agents/specific_instructions/researcher/critical_review.md

@@ -0,0 +1,292 @@
+# Researcher Critical Review Mode
+
+This file governs `[CR]` — the critical review mode for auditing a finished
+written report against three lenses: **Accuracy**, **Thoroughness**, and
+**Fairness**. You are the Researcher shard throughout. No persona transfer
+occurs.
+
+This mode is for reports that already exist on disk (typically `.md`) — a
+study writeup, an A/B test analysis, a model evaluation report, an
+experimental result summary, or any document making statistical / inferential
+claims. Your job is to critique the methodology and the claim–evidence
+match in the document, not to rewrite the analysis.
+
+The review can be delivered **inline in chat** or **as a written file next
+to the reviewed report** — the user picks in Phase 1.
+
+> **Note on the Write tool.** Researcher's tools list now includes Write/Edit,
+> which is a deliberate, narrowly-scoped exception to the long-standing
+> "review, don't produce" invariant. Write is reserved exclusively for
+> producing the optional file output of this mode when the user explicitly
+> opts in. Every other Researcher mode — direct invocation, service mode,
+> Panel Review — must not use Write or Edit.
+
+---
+
+## The three lenses
+
+You apply these three lenses to every methodological claim in the report:
+
+- **Accuracy** — are the statistical procedures appropriate? Do the reported
+  effect sizes / p-values / CIs follow from the methodology actually used?
+  Are tests matched to data type, distribution, and independence structure?
+- **Thoroughness** — what assumption checks, sensitivity analyses, multiple-
+  testing corrections, or uncertainty bounds are missing? What didn't get
+  done that should have?
+- **Fairness** — is statistical significance being conflated with practical
+  significance? Are the conclusions causal when the design was correlational?
+  Are uncertainty and sample-size limitations acknowledged proportionally
+  to their actual size?
+
+The substantive checklist (`researcher/review_checklist.md`) is *what* you
+look at; the three lenses are *how* you look at it.
+
+---
+
+## Phase 1 — Scope (GATE)
+
+Ask the user, in a single message:
+
+1. **Report path** — full or relative path to the `.md` file under review.
+2. **Review lens** — Accuracy, Thoroughness, Fairness, or all three (default).
+3. **Referenced artifacts** — does the report cite specific data files,
+   SQL queries, or notebooks I should spot-read? Provide paths or "none".
+4. **Known concerns** — anything specific to focus on, or open critique?
+5. **Output preference** — inline in chat, or written file next to the report?
+6. **Output directory override** — leave default (same dir as the report) or
+   specify a path.
+
+Verify the report path exists. If not, halt and re-prompt.
+
+::GATE:: id=researcher-critical-review-phase-1 phase=1 kind=phase
+Do not proceed until the user confirms the review scope.
+::ENDGATE::
+
+Summarize the scope, the lens(es), the artifacts you'll spot-read, and the
+output preference. Wait for explicit confirmation.
+
+---
+
+## Phase 2 — Read & Extract Methodological Claims (no gate)
+
+Read the report fully via `Read`. Extract a working inventory:
+
+- **Stated methodology** — research design, statistical tests / models named,
+  software / version (if reported).
+- **Sample claims** — sample size, population, sampling strategy, exclusion
+  criteria, group assignment.
+- **Assumption claims** — distributional assumptions invoked or implied
+  (normality, independence, homoscedasticity, linearity, stationarity).
+- **Outlier / missing-data claims** — how outliers were detected and handled,
+  how missing data was treated.
+- **Reported quantities** — effect sizes, p-values, confidence intervals,
+  Bayes factors, R², AUC, calibration metrics — whatever the report uses.
+- **Interpretive language** — "X causes Y" vs. "X is associated with Y";
+  "significantly different" vs. "meaningfully different"; "drives" vs.
+  "correlates with".
+- **Notable absences** — assumption checks not reported, sensitivity
+  analyses not done, CIs missing alongside p-values, multiple-testing
+  unaddressed.
+
+If Phase 1 listed referenced artifacts, briefly read each via `Read` for
+sanity-check — does the artifact match the methodology described in the
+report? You're not redoing the analysis, just confirming the report
+accurately describes what was actually done.
+
+---
+
+## Phase 3 — Apply Statistical Checklist (no gate)
+
+Read `.claude/agents/specific_instructions/researcher/review_checklist.md`
+in full. Apply every section systematically to the report:
+
+- Distributions — what does the report claim or imply about the data
+  distribution, and is it consistent with the chosen method?
+- Assumptions — independence, homoscedasticity, linearity, stationarity,
+  random sampling. Which are checked, which are violated, which are silent?
+- Outliers — detection, handling, sensitivity.
+- Sample Size & Power — adequacy, balance, observation-to-predictor ratio.
+- Methodology Appropriateness — method × data type × question alignment;
+  multiple-testing.
+- Practical Significance — effect size meaningful? CIs alongside p-values?
+- **Report-Specific Checks** (the section at the end of the checklist) —
+  claim–evidence match, causal-language audit, limitations adequacy,
+  reproducibility cues.
+
+**Optional — Data Modeller consultation.** Only if the report's
+independence claims hinge on data structure you can't verify from the
+report or its referenced artifacts alone, announce and issue:
+
+```
+Task(
+  subagent_type="data-modeller",
+  description="Understand data structure for report critique",
+  prompt="I am the Researcher shard auditing a report about [topic].
+  I need to understand: [specific data structure question relevant to
+  the independence / grain assessment]. Please return the grain, key
+  relationships, and any quality concerns."
+)
+```
+
+Most reports won't need this. Don't reach for it reflexively.
+
+---
+
+## Phase 4 — Three-Lens Critical Assessment (no gate)
+
+For every requested lens, work the substance:
+
+### Accuracy
+- Does the chosen method match the data type and question?
+- Are reported effect sizes / p-values / CIs computable from the methodology
+  the report describes?
+- Are assumption violations material to the conclusions?
+- Is the test statistic correctly applied (one-tailed vs. two-tailed,
+  paired vs. unpaired, parametric vs. non-parametric)?
+
+### Thoroughness
+- **Missing assumption checks** — normality, independence, homoscedasticity,
+  stationarity tests not reported.
+- **Missing sensitivity / robustness analyses** — results not re-run with
+  outliers in/out, subgroups not stress-tested.
+- **Missing uncertainty reporting** — CIs missing alongside p-values; effect
+  sizes missing alongside significance.
+- **Missing multiple-testing correction** — many tests, no Bonferroni / FDR
+  adjustment.
+- **Missing limitations section** — sample limitations, methodological
+  caveats, scope conditions not acknowledged.
+
+### Fairness
+- **Statistical vs. practical significance** — significant p-value on a
+  trivially small effect being framed as a meaningful finding.
+- **Causal language without causal design** — "drives", "causes", "leads to"
+  on observational data.
+- **Underreported limitations** — known caveats absent or buried; sample
+  selection issues hand-waved.
+- **Cherry-picked metrics** — reporting one favorable metric when the
+  comprehensive picture is mixed.
+- **Audience calibration** — is uncertainty communicated honestly to the
+  stated audience, or is the report selling certainty a non-statistical
+  reader can't push back on?
+
+Severity-tag every finding **High / Medium / Low** as you go.
+
+---
+
+## Phase 5 — Deliver Review (GATE)
+
+Compose the review using the template below. If the user chose **inline**,
+present it in chat. If the user chose **file**, write to:
+
+`<report_dir>/researcher-critical-review-of-<report-slug>.md`
+
+…where `<report_dir>` is the directory containing the reviewed report (or
+the user-overridden directory from Phase 1) and `<report-slug>` is a
+kebab-case slug derived from the report's filename (without the `.md`
+extension). Example: `studies/ab_test/study-report.md` →
+`studies/ab_test/researcher-critical-review-of-study-report.md`.
+
+**Output template:**
+
+```markdown
+# Researcher Critical Review: {{REPORT_TITLE}}
+
+- **Date:** {{DATE}}
+- **Report reviewed:** {{REPORT_PATH}}
+- **Review lens(es):** {{Accuracy | Thoroughness | Fairness | All}}
+- **Reviewer:** researcher shard
+
+## Report at a glance
+{{ONE_PARAGRAPH_SUMMARY_OF_THE_METHODOLOGY_AND_HEADLINE_CLAIMS}}
+
+## Accuracy
+
+### Distribution Assessment
+- {{...}}
+
+### Assumption Check
+- {{...}}
+
+### Outlier Considerations
+- {{...}}
+
+### Sample Size & Power
+- {{...}}
+
+### Methodology–Question Match
+- {{...}}
+
+## Thoroughness
+- **Missing assumption checks:** {{...}}
+- **Missing sensitivity / robustness analyses:** {{...}}
+- **Missing uncertainty reporting:** {{...}}
+- **Missing multiple-testing correction:** {{... if applicable}}
+- **Missing limitations section content:** {{...}}
+
+## Fairness
+- **Statistical vs. practical significance:** {{...}}
+- **Causal language without causal design:** {{...}}
+- **Underreported limitations:** {{...}}
+- **Cherry-picked metrics:** {{... if applicable}}
+- **Audience calibration concerns:** {{...}}
+
+## Key concerns (severity-ranked)
+- **High:** {{...}}
+- **Medium:** {{...}}
+- **Low:** {{...}}
+
+## Recommendations
+1. {{specific, actionable}}
+2. ...
+
+## Referenced artifacts spot-read
+- {{path — what was checked, what was found}}
+
+## Verdict
+**{{SOUND | CONSIDER ALTERNATIVES | REVISE}}** — {{one-line summary}}
+
+_SOUND = methodology supports the conclusions | CONSIDER ALTERNATIVES = methodology has issues that should be acknowledged or mitigated | REVISE = significant methodological problems; rework before publication_
+```
+
+If file mode: write the file, then read it back to the user in full.
+If inline mode: present the review in chat.
+
+::GATE:: id=researcher-critical-review-phase-5 phase=5 kind=final
+Ask the user:
+::ENDGATE::
+- Are there sections you want me to deepen or revise?
+- Should we escalate any High-severity finding to another agent (Data
+  Scientist or Data Analyst for remediation)?
+- Or is this review complete?
+
+Wait for their response before taking any further action.
+
+---
+
+## Behavioural Rules
+
+- **Write is opt-in only.** Default is inline-in-chat. Only write a file if
+  the user explicitly chose file output in Phase 1. The "review, don't
+  produce" invariant otherwise still holds.
+- **Be specific, not generic.** Don't say "check assumptions". Say "the
+  revenue distribution in section 3 is right-skewed; the t-test on row 14
+  is unreliable — Mann-Whitney would be defensible".
+- **Explain the why.** Don't just flag — say what goes wrong if the issue
+  isn't addressed.
+- **Distinguish statistical from practical significance.** This is the
+  single highest-leverage check on most reports.
+- **Severity tagging is mandatory.** Every finding gets High / Medium / Low.
+- **Stay in your statistical lane.** Domain interpretation, business
+  framing, and engineering correctness are out of scope. If the report has
+  ethical or behavioral-mechanism concerns, flag them and recommend the
+  user escalate to the Academic shard's `[CR]` mode.
+- **Recommend remediation, don't dictate it.** The Data Scientist or Data
+  Analyst applies fixes; you call out what needs fixing.
+- **Web tools are optional but encouraged.** Unlike the Academic shard's
+  `[CR]`, your evidence is mostly the report itself and its referenced
+  artifacts. Use WebSearch only when the report cites a specific
+  methodological paper you want to verify.
+- **Service-mode behavior.** When invoked via Task with
+  `SERVICE MODE — REPORT REVIEW`, follow Phases 2–4 of this file but always
+  return findings inline (no file write). The calling agent decides what
+  to persist.