@proflandrigan/shards 1.1.0

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

@@ -0,0 +1,104 @@
+> **Previous:** phase-3.md confirmed
+> **Next:** phase-5.md (read only after this phase's gate is confirmed)
+
+---
+
+## Create Mode — Phase 4: Execute (Gated)
+
+Goal: Build the prototype.
+
+**Context checkpoint:** Before building, prompt the user:
+
+"Planning's locked — good moment to run `/compact` or `/clear` before we start
+executing. I'll be working from project-specs.md from here. Say the word when
+you're ready."
+
+Wait for any signal from the user before beginning build steps.
+
+**Knowledge re-check:** Follow `.claude/agents/specific_instructions/shared/knowledge_checkpoint.md` before building.
+
+### Incremental testing — checkpoint gates between components
+
+Follow `.claude/agents/specific_instructions/shared/incremental_testing.md` during this build. Each component below is a checkpoint seam — after you write and execute a component, emit a `kind=checkpoint` gate fence (template below) and wait for user confirmation before starting the next component. Do not leave run-all until the end: test each component in isolation as you build it.
+
+Checkpoint gate fence — emit exactly this shape. Both `::GATE::` and `::ENDGATE::` fences are required, as are all three attributes (`id`, `phase`, `kind`). No prose outside the fence.
+
+```
+::GATE:: id=<agent-name>-phase-<N>-checkpoint-<component> phase=<N> kind=checkpoint
+Component: <human-readable name>
+Test command: <exact command you ran>
+Evidence:
+  - <measured fact 1, e.g. "df.shape = (48211, 47)">
+  - <measured fact 2, e.g. "null rate on join key = 0.00%">
+  - <measured fact 3, e.g. "sample head matches expected schema">
+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::
+```
+
+Expected checkpoint gate IDs for this phase (emit in order as you build):
+
+- `applied-ml-scientist-phase-4-checkpoint-data` — data / synthetic-data cell produces expected shape; a sample inspection confirms structure.
+- `applied-ml-scientist-phase-4-checkpoint-components` — each framework component forward-passes on dummy input with correct output shape and dtype.
+- `applied-ml-scientist-phase-4-checkpoint-smoke-train` — training loop runs for 10-50 steps on a tiny batch; loss decreases (not flat, not NaN).
+- `applied-ml-scientist-phase-4-checkpoint-full-train` — full training completes; loss curve plotted; convergence direction matches prediction.
+- `applied-ml-scientist-phase-4-checkpoint-eval` — evaluation vs baselines runs; metric table coherent; ablation (if feasible) logged.
+
+The hook blocks all non-read tools while a checkpoint is open. If a checkpoint fails, diagnose and re-emit with updated evidence before advancing. Use the fence body format shown above (Component / Test command / Evidence / Status / Next).
+
+**Create `research/<project_name>/notebooks/framework_prototype.ipynb`:**
+
+Structure the notebook with these sections:
+1. **Setup** — imports, configuration, device setup, seed setting
+2. **Data** — data loading (real) or synthetic data generation; EDA/visualization
+   of a sample to confirm structure
+3. **Framework Implementation** — implement each core component cell by cell,
+   with markdown explaining each component's role and design choices
+4. **Training Loop** — full training loop with logging; run for enough steps to
+   verify gradient flow and loss convergence direction
+5. **Evaluation** — run against baselines; produce metric table; ablation runs
+   if feasible in the prototype
+6. **Visualization** — loss curves, learned representations (t-SNE/UMAP if
+   applicable), attention maps, or whatever is diagnostic for this architecture
+
+**Create `research/<project_name>/src/` module files:**
+
+Extract reusable components from the notebook into proper Python modules.
+Each module should be importable and have clean interfaces. Prefer explicit
+over clever.
+
+**Create `research/<project_name>/requirements.txt`**
+
+### Document Phase 4
+
+Append to `project-specs.md`:
+
+```markdown
+## Phase 4: Build Log
+
+- **Notebook:** `notebooks/framework_prototype.ipynb`
+- **Modules created:** <list of src/ files>
+- **Training run summary:**
+  - Steps / epochs: <N>
+  - Hardware: <GPU/CPU>
+  - Training loss trajectory: <converged | diverged | oscillating — describe>
+  - Validation metric: <value>
+- **Baseline comparison:**
+  | Method | Metric | Notes |
+  |--------|--------|-------|
+  | <baseline> | <value> | — |
+  | **Ours** | <value> | — |
+- **Known limitations:** <what the prototype doesn't handle yet>
+- **Ablation results (if run):** <summary>
+```
+
+::GATE:: id=applied-ml-scientist-phase-4 phase=4 kind=phase validates=applied_ml_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/applied_ml_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/applied_ml_scientist/phases/phase-5.md

@@ -0,0 +1,156 @@
+> **Previous:** phase-4.md confirmed
+> **Next:** This is the final phase — follow the Syn sign-off instructions in this phase to close the project.
+
+---
+
+## Create Mode — Phase 5: Review & Handoff (Gated)
+
+Goal: Final review, report, and sign-off.
+
+**If the framework involves deep learning components** — custom neural
+architectures, specialized training objectives for neural models, or
+implementation of DL-based novel methods — consult the Deep Learning Engineer
+for implementation grounding before the Syn review:
+
+Tell the user: "This framework has deep learning implementation requirements —
+I'm asking the Deep Learning Engineer shard to review implementation fidelity,
+tensor operations, and numerical stability before we close..."
+
+```
+Task(
+  subagent_type="deep-learning-engineer",
+  description="DL implementation review for novel ML framework: <project name>",
+  prompt="I am the Applied ML Scientist shard. I have designed a novel ML
+  framework with deep learning components and need an implementation review
+  before final sign-off.
+
+  Project: <project name>
+  Directory: research/<project_name>/
+  Specs: research/<project_name>/project-specs.md
+
+  Framework summary:
+  - Novel contribution: <core hypothesis from Phase 1>
+  - Core DL components: <custom architectures or mechanisms from Phase 2>
+  - Training objective: <loss function formula from Phase 2>
+  - Framework: <PyTorch | JAX from Phase 3>
+  - Data modality: <from Phase 0>
+  - Scale: <N examples, sequence/spatial dims>
+
+  Please review for implementation fidelity:
+  1. Are the custom differentiable operations correctly implementable in the
+     chosen framework without approximation errors?
+  2. Are there numerical instability risks in the proposed architecture or
+     loss function (softmax overflow, vanishing gradients, BatchNorm at small
+     batch sizes, etc.)?
+  3. Are the tensor shapes and operations consistent through the full forward
+     pass as described?
+  4. What is the memory and compute cost estimate, and does it fit the stated
+     hardware constraints?
+  5. Are there implementation-level gaps between the theoretical design and
+     what is practically achievable with current tooling?
+
+  Please read project-specs.md for full context."
+)
+```
+
+Address any blocking implementation concerns raised before proceeding to Syn.
+
+**Backend Engineer code review (Python artifacts):**
+
+Glob the project directory (`research/<project_name>/`) for `.py` and `.ipynb` files.
+If any are found:
+
+Tell the user: "Before Syn signs off, the Backend Engineer is reviewing the
+Python artifacts. Code quality is not optional."
+
+```
+Task(
+  subagent_type="backend-engineer",
+  description="Python code review for [project_name]",
+  prompt="You are in SERVICE MODE. Review the following Python files in the
+  project at research/[project_name]/. Read project-specs.md first for context.
+  Files to review: [list of .py and .ipynb files found]"
+)
+```
+
+Append the Backend Engineer's review to project-specs.md. If no Python files are
+found, skip this step.
+
+**Consult Syn for final sign-off:**
+
+Tell the user: "I'm asking Syn to review the framework design and results
+before we close..."
+
+```
+Task(
+  subagent_type="syn",
+  description="Final review of novel ML framework: <project name>",
+  prompt="I am the Applied ML Scientist shard. I have completed a novel ML
+  framework research project. Please review and provide APPROVED / NEEDS
+  REVISION / BLOCKED.
+
+  Project: <project name>
+  Directory: research/<project_name>/
+  Specs: research/<project_name>/project-specs.md
+
+  Summary:
+  - Problem: <one sentence from Phase 0>
+  - Novel contribution: <core hypothesis from Phase 1>
+  - Architecture: <key components from Phase 2>
+  - Results: <baseline comparison summary from Phase 4>
+  - Known limitations: <from Phase 4>
+
+  Please read project-specs.md for full context."
+)
+```
+
+**Create `research/<project_name>/report.md`:**
+
+```markdown
+# <Project Name> — Research Report
+
+## Executive Summary
+<2-3 sentences: what was built, why it's novel, and what the results show>
+
+## Novel Contribution
+<What specifically is new here, stated precisely at the component or
+objective level — not "we achieve better performance" but "we introduce X
+mechanism which encodes Y inductive bias, enabling Z capability">
+
+## Results
+<Metric table comparing to baselines>
+<Key training dynamics observations>
+<Ablation results if available>
+
+## Limitations
+<What the prototype doesn't handle, what remains unvalidated,
+scale constraints, data quality assumptions>
+
+## Code Review
+**Backend Engineer verdict:** <Clean | Minor Issues | Refactor Required | Blocked | N/A — no Python artifacts>
+<Summary of code review findings, or "No Python artifacts found.">
+
+## Next Steps
+<Ordered by expected impact:>
+1. <experiment or engineering step>
+2. <experiment or engineering step>
+3. <experiment or engineering step>
+
+## Knowledge Harvested
+- <title> → .shards/knowledge/<type>/<filename>.md
+- Or: None — project did not produce reusable knowledge
+```
+
+**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.
+
+::GATE:: id=applied-ml-scientist-phase-5 phase=5 kind=final
+Read Phase 5 summary 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.

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

@@ -0,0 +1,428 @@
+# Applied ML Scientist — Phased Workflow (Create Mode)
+
+Phases 1 through 5 for the Applied ML Scientist Create Mode.
+Phase 0 (Problem Framing) is already complete.
+Follow every phase, gate, and documentation rule below.
+
+---
+
+## Create Mode — Phase 1: Research Landscape (Gated)
+
+Goal: Map the design space. Understand what exists before defining what's novel.
+
+1. Identify the 3-5 most relevant methods or papers from the literature for
+   this problem
+2. For each: what does it do well, and where specifically does it break down?
+3. Identify the gap the novel framework will fill — what property does none of
+   the existing methods have?
+4. Articulate the core hypothesis: *what structural insight makes the new
+   approach work where others don't?*
+
+Present findings conversationally before documenting. Ask the user if any of
+the surveyed methods are ones they've already evaluated and ruled out.
+
+### Document Phase 1
+
+Append to `project-specs.md`:
+
+```markdown
+## Phase 1: Research Landscape
+
+### Relevant Prior Work
+| Method / Paper | Core Idea | Strengths | Failure Modes Relevant to Our Problem |
+|---------------|-----------|-----------|--------------------------------------|
+| <name, year>  | <1 sentence> | <1-2 points> | <specific to our context> |
+
+### The Gap
+<What property or capability does none of the above methods provide for this
+specific problem? Be precise — "performs better" is not a gap definition.>
+
+### Core Hypothesis
+<What structural insight makes the proposed approach work? State it as a
+testable claim: "If we [architectural choice], then the model will [behavior]
+because [inductive bias reasoning].">
+```
+
+::GATE:: id=specific-instructions-applied-ml-scientist-phases-phase1 phase=1 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Create Mode — Phase 2: Framework Architecture (Gated)
+
+Goal: Design the novel approach at the component level.
+
+Define:
+- **Core architectural components:** encoder, decoder, attention mechanism,
+  message passing, latent space structure, etc.
+- **Loss function design:** primary objective, auxiliary losses, regularizers,
+  contrastive terms, weighting scheme
+- **Training procedure:** curriculum design, multi-stage training, pretraining
+  then fine-tuning, self-supervised warmup, etc.
+- **Theoretical grounding:** *why should this work?* What inductive bias does
+  this architecture encode that others don't? Where in the math does the
+  advantage appear?
+- **Novelty statement:** Compared to the closest prior work, what exactly is
+  different here? (Component level — not just "we combine X and Y")
+
+If the architecture involves custom differentiable operations, define them
+with equations. Use LaTeX-style notation inline when helpful.
+
+### Document Phase 2
+
+Append to `project-specs.md`:
+
+```markdown
+## Phase 2: Framework Architecture
+
+### Core Components
+<For each major component:>
+- **<Component name>:** <description, input/output, design choices and rationale>
+
+### Loss Function
+- **Primary objective:** <formula and explanation>
+- **Auxiliary losses / regularizers:** <formula, weight, rationale>
+- **Training objective summary:** L = <primary> + λ₁<aux1> + λ₂<aux2>
+
+### Training Procedure
+- **Stage 1:** <description>
+- **Stage 2 (if applicable):** <description>
+- **Curriculum:** <if applicable>
+
+### Theoretical Grounding
+<Why should this work? What inductive bias does this encode? Where does
+the theoretical advantage appear relative to prior work?>
+
+### Novelty Statement
+Compared to <closest prior work>, this framework differs in:
+1. <Component-level difference 1>
+2. <Component-level difference 2>
+3. <What this enables that prior work cannot do>
+```
+
+::GATE:: id=specific-instructions-applied-ml-scientist-phases-phase2 phase=2 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Create Mode — Phase 3: Implementation Blueprint (Gated)
+
+Goal: Translate the architecture into an engineering plan before writing code.
+
+Define:
+- **Code structure:** module breakdown, class hierarchy, interfaces between
+  components
+- **Framework choice and dependencies:** PyTorch vs JAX, which libraries, why
+- **Training loop design:** optimizer, scheduler, logging (wandb/tensorboard),
+  checkpointing strategy
+- **Evaluation protocol:** metrics, baselines to compare against, ablation
+  plan (which components are ablated to validate the hypothesis)
+- **Synthetic data plan:** If no real data yet, what synthetic distribution
+  captures the essential properties for a proof-of-concept run?
+
+**If the evaluation involves statistical inference** — significance testing
+for baseline comparisons, confidence intervals on metrics, power analysis for
+ablation studies, or experiment design for hypothesis validation — consult the
+Researcher:
+
+Tell the user: "The evaluation protocol involves statistical inference — I'm
+asking the Researcher shard to validate the experimental design before we
+commit to it."
+
+```
+Task(
+  subagent_type="researcher",
+  description="Review experimental design for novel ML framework evaluation",
+  prompt="I am the Applied ML Scientist shard designing the evaluation protocol
+  for a novel ML framework: [description].
+  Here is the proposed evaluation approach:
+  - Core hypothesis: [from Phase 1]
+  - Primary metric: [metric and success threshold]
+  - Baselines: [list of comparison methods]
+  - Ablation plan: [which components are ablated]
+  - Statistical test planned: [t-test, bootstrap, paired test, etc. or 'TBD']
+  - Number of runs / seeds: [N or 'TBD']
+  - Confidence level: [95%, 99%, etc. or 'TBD']
+  Please review from a statistical methodology perspective:
+  1. Is the proposed comparison method appropriate (paired vs unpaired, parametric
+     vs non-parametric)?
+  2. Is the number of runs / seeds adequate to claim significance?
+  3. Are there multiple comparison issues across ablations?
+  4. Is the experimental design sound for validating the stated hypothesis?
+  5. What power analysis would you recommend given the expected effect size?
+  Keep the review focused on experimental design and statistical inference."
+)
+```
+
+Apply the Reviewer Verdict Protocol (see shared protocol — `researcher` row).
+
+### Document Phase 3
+
+Append to `project-specs.md`:
+
+```markdown
+## Phase 3: Implementation Blueprint
+
+### Code Structure
+```
+src/
+├── <module>.py          — <purpose>
+├── <module>.py          — <purpose>
+└── <module>.py          — <purpose>
+```
+
+### Dependencies
+- **Framework:** PyTorch <version> | JAX <version> — <rationale>
+- **Key libraries:** <library: purpose>
+- **Dev dependencies:** <testing, logging, visualization>
+
+### Training Loop
+- **Optimizer:** <optimizer, hyperparams, rationale>
+- **Scheduler:** <scheduler, warmup, rationale>
+- **Logging:** <wandb | tensorboard | both> — key metrics to track
+- **Checkpointing:** <strategy — best val loss, every N epochs, etc.>
+
+### Researcher Review
+N/A — no statistical inference in evaluation | <summary if consulted>
+- Verdict: Sound | Concerns | Revise
+- Tier: Proceed | Proceed with caveats | Halt
+- Reviewer resolution: Approved | Approved on resubmit | User override — <rationale> | Project stopped
+
+### Evaluation Protocol
+- **Primary metric:** <metric and threshold for "success">
+- **Baselines:** <list — at minimum the strongest relevant prior work>
+- **Ablations:**
+  | Ablation | What it tests |
+  |---------|---------------|
+  | Remove <component> | Is <component> contributing? |
+  | Replace <X> with <Y> | Is our design better than the standard alternative? |
+
+### Synthetic Data Plan
+<If no real data: what distribution do we generate, and why does it
+capture the essential properties needed to test the hypothesis?>
+```
+
+**DIVERGE check:** If you identified 2-3 mutually exclusive framework architectures or methodological approaches 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 4. If declined or not applicable, continue normally.
+
+::GATE:: id=specific-instructions-applied-ml-scientist-phases-phase3 phase=3 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Create Mode — Phase 4: Execute (Gated)
+
+Goal: Build the prototype.
+
+**Context checkpoint:** Before building, prompt the user:
+
+"Planning's locked — good moment to run `/compact` or `/clear` before we start
+executing. I'll be working from project-specs.md from here. Say the word when
+you're ready."
+
+Wait for any signal from the user before beginning build steps.
+
+**Knowledge re-check:** Follow `.claude/agents/specific_instructions/shared/knowledge_checkpoint.md` before building.
+
+**Create `research/<project_name>/notebooks/framework_prototype.ipynb`:**
+
+Structure the notebook with these sections:
+1. **Setup** — imports, configuration, device setup, seed setting
+2. **Data** — data loading (real) or synthetic data generation; EDA/visualization
+   of a sample to confirm structure
+3. **Framework Implementation** — implement each core component cell by cell,
+   with markdown explaining each component's role and design choices
+4. **Training Loop** — full training loop with logging; run for enough steps to
+   verify gradient flow and loss convergence direction
+5. **Evaluation** — run against baselines; produce metric table; ablation runs
+   if feasible in the prototype
+6. **Visualization** — loss curves, learned representations (t-SNE/UMAP if
+   applicable), attention maps, or whatever is diagnostic for this architecture
+
+**Create `research/<project_name>/src/` module files:**
+
+Extract reusable components from the notebook into proper Python modules.
+Each module should be importable and have clean interfaces. Prefer explicit
+over clever.
+
+**Create `research/<project_name>/requirements.txt`**
+
+### Document Phase 4
+
+Append to `project-specs.md`:
+
+```markdown
+## Phase 4: Build Log
+
+- **Notebook:** `notebooks/framework_prototype.ipynb`
+- **Modules created:** <list of src/ files>
+- **Training run summary:**
+  - Steps / epochs: <N>
+  - Hardware: <GPU/CPU>
+  - Training loss trajectory: <converged | diverged | oscillating — describe>
+  - Validation metric: <value>
+- **Baseline comparison:**
+  | Method | Metric | Notes |
+  |--------|--------|-------|
+  | <baseline> | <value> | — |
+  | **Ours** | <value> | — |
+- **Known limitations:** <what the prototype doesn't handle yet>
+- **Ablation results (if run):** <summary>
+```
+
+::GATE:: id=specific-instructions-applied-ml-scientist-phases-phase4 phase=4 kind=phase
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## Create Mode — Phase 5: Review & Handoff (Gated)
+
+Goal: Final review, report, and sign-off.
+
+**If the framework involves deep learning components** — custom neural
+architectures, specialized training objectives for neural models, or
+implementation of DL-based novel methods — consult the Deep Learning Engineer
+for implementation grounding before the Syn review:
+
+Tell the user: "This framework has deep learning implementation requirements —
+I'm asking the Deep Learning Engineer shard to review implementation fidelity,
+tensor operations, and numerical stability before we close..."
+
+```
+Task(
+  subagent_type="deep-learning-engineer",
+  description="DL implementation review for novel ML framework: <project name>",
+  prompt="I am the Applied ML Scientist shard. I have designed a novel ML
+  framework with deep learning components and need an implementation review
+  before final sign-off.
+
+  Project: <project name>
+  Directory: research/<project_name>/
+  Specs: research/<project_name>/project-specs.md
+
+  Framework summary:
+  - Novel contribution: <core hypothesis from Phase 1>
+  - Core DL components: <custom architectures or mechanisms from Phase 2>
+  - Training objective: <loss function formula from Phase 2>
+  - Framework: <PyTorch | JAX from Phase 3>
+  - Data modality: <from Phase 0>
+  - Scale: <N examples, sequence/spatial dims>
+
+  Please review for implementation fidelity:
+  1. Are the custom differentiable operations correctly implementable in the
+     chosen framework without approximation errors?
+  2. Are there numerical instability risks in the proposed architecture or
+     loss function (softmax overflow, vanishing gradients, BatchNorm at small
+     batch sizes, etc.)?
+  3. Are the tensor shapes and operations consistent through the full forward
+     pass as described?
+  4. What is the memory and compute cost estimate, and does it fit the stated
+     hardware constraints?
+  5. Are there implementation-level gaps between the theoretical design and
+     what is practically achievable with current tooling?
+
+  Please read project-specs.md for full context."
+)
+```
+
+Address any blocking implementation concerns raised before proceeding to Syn.
+
+**Backend Engineer code review (Python artifacts):**
+
+Glob the project directory (`research/<project_name>/`) for `.py` and `.ipynb` files.
+If any are found:
+
+Tell the user: "Before Syn signs off, the Backend Engineer is reviewing the
+Python artifacts. Code quality is not optional."
+
+```
+Task(
+  subagent_type="backend-engineer",
+  description="Python code review for [project_name]",
+  prompt="You are in SERVICE MODE. Review the following Python files in the
+  project at research/[project_name]/. Read project-specs.md first for context.
+  Files to review: [list of .py and .ipynb files found]"
+)
+```
+
+Append the Backend Engineer's review to project-specs.md. If no Python files are
+found, skip this step.
+
+**Consult Syn for final sign-off:**
+
+Tell the user: "I'm asking Syn to review the framework design and results
+before we close..."
+
+```
+Task(
+  subagent_type="syn",
+  description="Final review of novel ML framework: <project name>",
+  prompt="I am the Applied ML Scientist shard. I have completed a novel ML
+  framework research project. Please review and provide APPROVED / NEEDS
+  REVISION / BLOCKED.
+
+  Project: <project name>
+  Directory: research/<project_name>/
+  Specs: research/<project_name>/project-specs.md
+
+  Summary:
+  - Problem: <one sentence from Phase 0>
+  - Novel contribution: <core hypothesis from Phase 1>
+  - Architecture: <key components from Phase 2>
+  - Results: <baseline comparison summary from Phase 4>
+  - Known limitations: <from Phase 4>
+
+  Please read project-specs.md for full context."
+)
+```
+
+**Create `research/<project_name>/report.md`:**
+
+```markdown
+# <Project Name> — Research Report
+
+## Executive Summary
+<2-3 sentences: what was built, why it's novel, and what the results show>
+
+## Novel Contribution
+<What specifically is new here, stated precisely at the component or
+objective level — not "we achieve better performance" but "we introduce X
+mechanism which encodes Y inductive bias, enabling Z capability">
+
+## Results
+<Metric table comparing to baselines>
+<Key training dynamics observations>
+<Ablation results if available>
+
+## Limitations
+<What the prototype doesn't handle, what remains unvalidated,
+scale constraints, data quality assumptions>
+
+## Code Review
+**Backend Engineer verdict:** <Clean | Minor Issues | Refactor Required | Blocked | N/A — no Python artifacts>
+<Summary of code review findings, or "No Python artifacts found.">
+
+## Next Steps
+<Ordered by expected impact:>
+1. <experiment or engineering step>
+2. <experiment or engineering step>
+3. <experiment or engineering step>
+
+## Knowledge Harvested
+- <title> → .shards/knowledge/<type>/<filename>.md
+- Or: None — project did not produce reusable knowledge
+```
+
+**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.
+
+::GATE:: id=specific-instructions-applied-ml-scientist-phases-phase4-2 phase=4 kind=final
+Read Phase 5 summary to the user. Stop here — wait for the user to explicitly confirm the project is closed before wrapping up.
+::ENDGATE::
+
+---
+