docs: Add initial Phase 1 change specifications - #35
Conversation
📝 WalkthroughWalkthroughAdds three interconnected proposals: an Ablation Toolkit for systematic ablation studies and automated reporting; a Multi‑Sensory Environment foundation (health, mechanosensation, unified feature extraction); and a Thermotaxis System (TemperatureField, gradient sensing, zone effects) with opt‑in integrations and benchmark extensions. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant CLI as CLI (run_ablation.py)
participant Ablation as AblationStudy
participant Env as Environment (sim)
participant Brain as Brain (Modular/PPO)
participant DB as Results (results.json)
participant Analysis as Analysis Module
participant Report as Report (report.md)
CLI->>Ablation: parse AblationConfig, start run_all
Ablation->>Env: initialize environment (thermotaxis/health flags)
Env->>Brain: step observations (sensory features)
Brain->>Env: choose actions
Env->>Ablation: return step metrics / SimulationResult
loop baseline and ablated runs
Ablation->>Brain: load baseline or ablated architecture / apply masks
Ablation->>Env: run episode(s)
Env->>DB: append results.json
end
Ablation->>Analysis: compute_feature_importance(results.json, importance.json)
Analysis->>Report: generate markdown (report.md) + plots
Report-->>CLI: artifacts saved (results.json, importance.json, report.md)
Note over Ablation,Analysis: New/changed interactions highlighted: ablation config, environment feature flags, and analysis pipeline
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
Pre-merge checks✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (9)
openspec/changes/add-multi-sensory-environment/tasks.md (3)
80-86: Add language identifier to YAML code block.Code blocks should specify the language for syntax highlighting and linting. Update this block to use markdown syntax:
```yaml
226-232: Add language identifier to code block.Specify the language for the dependency diagram block:
-``` +```
276-292: Add language identifier and refactor repetitive sentence structure.The code block needs a language specifier. Additionally, lines 287–291 begin successive sentences with "Work streams," which is awkward. Consolidate them:
-``` +```text 1. Ablation Framework ──┐ │ 2. Health System ───────┼──► 6. Multi-Objective Rewards │ 3. Enhanced Predators ──┤ │ 4. Mechanosensation ────┼──► 5. Unified Feature Extraction │ └──► 7. Evaluation Extensions │ v 8. Food Spawning + 9. Visualization │ v 10. Hierarchical Benchmarks + 11. Config/Docs -``` - -Work streams 1-4 can proceed in parallel. Work stream 5 depends on 4. Work streams 6-7 depend on 1-4. Work streams 8-9 depend on all above. Work stream 10 can proceed independently but should be done before 11. +``` + +Streams 1–4 proceed in parallel. Stream 5 depends on 4. Streams 6–7 depend on 1–4. Streams 8–9 depend on all prior streams. Stream 10 can proceed independently but should be completed before 11.openspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.md (1)
124-125: Simplify redundant phrase "CLI Interface"."CLI" already stands for "Command-Line Interface," so "CLI Interface" is tautological. Rename the requirement:
-### Requirement: Ablation CLI Interface -The system SHALL provide a command-line interface for running ablation studies. +### Requirement: Ablation CLI +The system SHALL provide a command-line interface for running ablation studies.openspec/changes/add-ablation-toolkit/tasks.md (1)
207-221: Add language identifier to dependency diagram code block.Specify the language/format for the code block containing the dependency diagram:
-``` +```text 1. Ablation Framework (core classes) │ ├──► 2. ModularBrain Ablation │ ├──► 3. PPOBrain Ablation │ └──► 4. Feature Importance │ v 5. Reporting │ v 6. CLI + 7. Docs -``` +```openspec/changes/add-multi-sensory-environment/design.md (4)
68-77: Add language identifier to YAML code block.Specify the language for better syntax highlighting:
-``` +```yaml BrainParams │ v extract_sensory_features() ─────────────────────┐ │ │ v v ModularBrain PPOBrain (converts to RX/RY/RZ rotations) (concatenates to input vector) -``` +```
89-95: Add blank lines around table for proper markdown formatting.Tables should be surrounded by blank lines per MD058:
**Mapping**: -| Current | New | Neurons | + +| Current | New | Neurons | |---------|-----|---------| | appetitive_features | food_chemotaxis_features | AWC, AWA | | aversive_features | nociception_features | ASH, ADL | | thermotaxis_features | thermotaxis_features | AFD | | oxygen_features | aerotaxis_features | URX, BAG | | touch_features | mechanosensation_features | ALM, PLM, AVM |
178-185: Add language identifier to ASCII diagram code block.Specify the format to clarify the block's purpose:
-``` +```text basic/ # Single objective (foraging only) survival/ # Food + predators thermotaxis/ # Temperature-aware tasks multisensory/ # Multiple modalities combined ablation/ # Controlled studies -``` +```
214-217: Add blank lines around table for proper markdown formatting.Tables should be surrounded by blank lines:
**Behavior**: + | System | Decreases From | Increases From | Termination | |--------|---------------|----------------|-------------| | Satiety | Time decay (every step) | Eating food | STARVATION | | HP | Predator contact, temperature extremes | Eating food, configurable healing | HEALTH_DEPLETED |
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
openspec/changes/add-ablation-toolkit/proposal.mdopenspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.mdopenspec/changes/add-ablation-toolkit/tasks.mdopenspec/changes/add-multi-sensory-environment/design.mdopenspec/changes/add-multi-sensory-environment/proposal.mdopenspec/changes/add-multi-sensory-environment/specs/brain-architecture/spec.mdopenspec/changes/add-multi-sensory-environment/specs/environment-simulation/spec.mdopenspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-thermotaxis-system/proposal.mdopenspec/changes/add-thermotaxis-system/specs/environment-simulation/spec.mdopenspec/changes/add-thermotaxis-system/tasks.md
🧰 Additional context used
📓 Path-based instructions (2)
openspec/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally marking non-normative guidance
Files:
openspec/changes/add-multi-sensory-environment/design.mdopenspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-multi-sensory-environment/specs/environment-simulation/spec.mdopenspec/changes/add-ablation-toolkit/tasks.mdopenspec/changes/add-thermotaxis-system/proposal.mdopenspec/changes/add-thermotaxis-system/tasks.mdopenspec/changes/add-ablation-toolkit/proposal.mdopenspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.mdopenspec/changes/add-multi-sensory-environment/proposal.mdopenspec/changes/add-multi-sensory-environment/specs/brain-architecture/spec.mdopenspec/changes/add-thermotaxis-system/specs/environment-simulation/spec.md
openspec/changes/*/specs/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/*/specs/**/*.md: In spec delta files, use## ADDED|MODIFIED|REMOVED|RENAMED Requirementssection headers with at least one#### Scenario:subsection per requirement
Use#### Scenario:(exactly 4 hash marks) for scenario headers in spec files, not### Scenario:, bold**Scenario:**, or bullet points
Every requirement in spec deltas must include at least one scenario with- **WHEN** conditionand- **THEN** expected resultformat
Files:
openspec/changes/add-multi-sensory-environment/specs/environment-simulation/spec.mdopenspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.mdopenspec/changes/add-multi-sensory-environment/specs/brain-architecture/spec.mdopenspec/changes/add-thermotaxis-system/specs/environment-simulation/spec.md
🧠 Learnings (7)
📓 Common learnings
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Scaffold change proposals with `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<change-id>/specs/`
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Create `design.md` only when the change is cross-cutting, introduces new external dependencies, involves significant data model changes, has security/performance complexity, or contains authoring ambiguity
Applied to files:
openspec/changes/add-multi-sensory-environment/design.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Use `## ADDED` for new capabilities that stand alone orthogonally; use `## MODIFIED` for changes to existing requirement behavior or scope; use `## RENAMED` for name-only changes
Applied to files:
openspec/changes/add-multi-sensory-environment/design.mdopenspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-multi-sensory-environment/specs/environment-simulation/spec.mdopenspec/changes/add-multi-sensory-environment/proposal.mdopenspec/changes/add-thermotaxis-system/specs/environment-simulation/spec.md
📚 Learning: 2025-12-27T08:02:58.340Z
Learnt from: chrisjz
Repo: SyntheticBrains/nematode PR: 22
File: openspec/changes/add-phase0-foundation-baselines/design.md:64-69
Timestamp: 2025-12-27T08:02:58.340Z
Learning: Design.md files under openspec/changes/ should document architectural or design decisions and rationale, not normative requirements. Do not use SHALL/MUST language in design.md (reserve such language for spec.md files). The strict SHALL/MUST wording should appear only in openspec/changes/*/specs/*/specs.md (spec deltas). Use objective, rationale-focused language in design.md and place any formal requirements in the appropriate spec files.
Applied to files:
openspec/changes/add-multi-sensory-environment/design.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Scaffold change proposals with `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<change-id>/specs/`
Applied to files:
openspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-ablation-toolkit/tasks.mdopenspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: In `tasks.md`, organize implementation work as a numbered checklist with sub-items using `- [ ]` unchecked format; update all items to `- [x]` after completion
Applied to files:
openspec/changes/add-multi-sensory-environment/tasks.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Applies to openspec/changes/*/specs/**/*.md : In spec delta files, use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` section headers with at least one `#### Scenario:` subsection per requirement
Applied to files:
openspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.md
🪛 LanguageTool
openspec/changes/add-multi-sensory-environment/tasks.md
[grammar] ~87-~87: Use a hyphen to join words.
Context: ... count: 1 ``` - [ ] Implement mixed type spawning - [ ] Update gradient comp...
(QB_NEW_EN_HYPHEN)
[style] ~294-~294: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s on 4. Work streams 6-7 depend on 1-4. Work streams 8-9 depend on all above. Work s...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
openspec/changes/add-ablation-toolkit/specs/ablation-analysis/spec.md
[style] ~124-~124: This phrase is redundant (‘I’ stands for ‘Interface’). Use simply “CLIInterface”.
Context: ... differences ### Requirement: Ablation CLI Interface The system SHALL provide a command-line...
(ACRONYM_TAUTOLOGY)
openspec/changes/add-thermotaxis-system/specs/environment-simulation/spec.md
[style] ~90-~90: ‘with success’ might be wordy. Consider a shorter alternative.
Context: ...old - GIVEN a thermotaxis benchmark with success threshold 60% - WHEN agent achieves...
(EN_WORDINESS_PREMIUM_WITH_SUCCESS)
🪛 markdownlint-cli2 (0.18.1)
openspec/changes/add-multi-sensory-environment/design.md
68-68: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
89-89: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
178-178: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
214-214: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
openspec/changes/add-multi-sensory-environment/tasks.md
226-226: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
276-276: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/changes/add-ablation-toolkit/tasks.md
207-207: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
openspec/changes/add-multi-sensory-environment/proposal.md
87-87: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Python 3.11
- GitHub Check: Python 3.12
🔇 Additional comments (7)
openspec/changes/add-ablation-toolkit/proposal.md (1)
1-72: LGTM!This proposal is well-structured and clearly articulates the motivation, scope, and impact of the ablation toolkit. The rationale is compelling, and the design appropriately scopes new analysis capabilities as non-breaking additions.
openspec/changes/add-thermotaxis-system/proposal.md (1)
1-75: LGTM!Excellent proposal with strong biological grounding and clear articulation of the design rationale. The note on spatial vs. temporal sensing and the roadmap reference demonstrates thoughtful trade-off documentation. Backward compatibility is clearly maintained.
openspec/changes/add-multi-sensory-environment/specs/environment-simulation/spec.md (1)
1-204: LGTM!This spec is well-structured and comprehensive. Requirements are clearly stated with SHALL language, scenarios follow proper format with GIVEN/WHEN/THEN structure (using exactly 4-hash scenario headers), and all new capabilities are properly specified with consideration for backward compatibility. The hierarchical benchmark naming scheme is clearly articulated with both new and legacy path examples.
openspec/changes/add-thermotaxis-system/tasks.md (1)
1-203: LGTM!Well-structured task plan with clear prerequisite dependencies, actionable work items, validation criteria, and success metrics. The biological validation section and careful attention to spatial vs. temporal sensing trade-offs show thoughtful engineering. Clear dependency diagram and hierarchical benchmark organization make the implementation plan straightforward to follow.
openspec/changes/add-multi-sensory-environment/proposal.md (1)
1-147: Proposal content is well-structured and comprehensive.The proposal clearly establishes the foundational architecture for Phase 1 multi-sensory capabilities. The Why section effectively motivates the need, the What Changes section methodically describes nine interconnected changes with rationale and impact, and the Impact section correctly identifies affected specs, code modules, and backward-compatibility guarantees. The clarification of the relationship between satiety and HP (lines 36–40) is particularly valuable for downstream implementation.
openspec/changes/add-thermotaxis-system/specs/environment-simulation/spec.md (1)
1-122: Spec delta format and scenarios are exemplary.The file correctly implements the spec delta format with proper
## ADDED Requirementsheader, requirement subsections, and scenario subsections using#### Scenario:(4 hashes). All scenarios follow the WHEN/THEN pattern with clear GIVEN context, actionable conditions, and measurable outcomes. Normative language (SHALL) is used consistently throughout. The scenarios are thorough and complementary, covering linear gradients, hot/cold spots, gradient computation, initialization, per-step sensing, disabled defaults, zone mechanics, and benchmark categorization.openspec/changes/add-multi-sensory-environment/specs/brain-architecture/spec.md (1)
1-172: Spec delta format, structure, and scenarios fully comply with guidelines.The file correctly implements the spec delta format with
## ADDED Requirementsheader, six well-organized requirement sections, and scenario subsections using#### Scenario:(4 hashes). All 19 scenarios follow the WHEN/THEN pattern with clear GIVEN contexts, actionable conditions, and measurable outcomes. Normative language (SHALL) is used consistently. The specifications are comprehensive: BrainParams extensions with backward compatibility (lines 32–37), unified feature extraction for both ModularBrain and PPOBrain (lines 52–64), scientific module naming with C. elegans neuron references (lines 73–78), mechanosensation with rotation ranges (lines 98–111), configurable rewards and health parameters (lines 116–141), and multi-objective evaluation metrics with scoring formulas (lines 146–172). Content is well-aligned with the multi-sensory environment proposal and provides implementation-ready detail.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
openspec/changes/add-multi-sensory-environment/tasks.md (2)
79-90: Add hyphen to compound modifier.On line 87, "mixed type" should be hyphenated as "mixed-type" when used as a compound modifier before the noun "spawning". This applies to other occurrences of "mixed type" in similar contexts.
🔎 Proposed fix
- [ ] Update predator config schema to support type list: ```yaml types: - type: stationary count: 2 - type: pursuit count: 1
- Implement mixed type spawning
+- [ ] Implement mixed-type spawning</details> --- `290-294`: **Revise repetitive sentence structure.** Lines 290–294 begin three successive sentences with "Work streams," which reduces readability. Consider varying the sentence structure for better flow. <details> <summary>🔎 Proposed revision</summary> ```diff -Work streams 1-4 can proceed in parallel. Work stream 5 depends on 4. Work streams 6-7 depend on 1-4. Work streams 8-9 depend on all above. Work stream 10 can proceed independently but should be done before 11. +Work streams 1–4 can proceed in parallel; stream 5 depends on 4. Streams 6–7 depend on 1–4, while streams 8–9 depend on all above. Stream 10 can proceed independently but should be completed before 11.openspec/changes/add-multi-sensory-environment/design.md (2)
88-96: Add blank line before table.Tables should be surrounded by blank lines per markdown style guidelines (MD058). Add a blank line before the table at line 88.
🔎 Proposed fix
**Mapping**: + | Current | New | Neurons |
213-218: Add blank lines around table.Tables should be surrounded by blank lines (MD058). Add a blank line before the table at line 214 and after line 217.
🔎 Proposed fix
**Behavior**: + | System | Decreases From | Increases From | Termination | |--------|---------------|----------------|-------------| | Satiety | Time decay (every step) | Eating food | STARVATION | | HP | Predator contact, temperature extremes | Eating food, configurable healing | HEALTH_DEPLETED | + **Configuration Example**:openspec/changes/add-multi-sensory-environment/proposal.md (1)
87-101: Add language identifier to code block.Fenced code blocks must have a language specifier (MD040). The directory hierarchy block at line 87 should specify
textorplaintextas the language.🔎 Proposed fix
-``` +```text basic/ # Single objective (foraging only) ├── foraging_small/
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
openspec/changes/add-ablation-toolkit/tasks.mdopenspec/changes/add-multi-sensory-environment/design.mdopenspec/changes/add-multi-sensory-environment/proposal.mdopenspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-thermotaxis-system/tasks.md
🧰 Additional context used
📓 Path-based instructions (1)
openspec/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally marking non-normative guidance
Files:
openspec/changes/add-thermotaxis-system/tasks.mdopenspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-multi-sensory-environment/proposal.mdopenspec/changes/add-multi-sensory-environment/design.mdopenspec/changes/add-ablation-toolkit/tasks.md
🧠 Learnings (8)
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Scaffold change proposals with `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<change-id>/specs/`
Applied to files:
openspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-ablation-toolkit/tasks.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: In `tasks.md`, organize implementation work as a numbered checklist with sub-items using `- [ ]` unchecked format; update all items to `- [x]` after completion
Applied to files:
openspec/changes/add-multi-sensory-environment/tasks.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Create `design.md` only when the change is cross-cutting, introduces new external dependencies, involves significant data model changes, has security/performance complexity, or contains authoring ambiguity
Applied to files:
openspec/changes/add-multi-sensory-environment/tasks.mdopenspec/changes/add-multi-sensory-environment/design.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Use `## ADDED` for new capabilities that stand alone orthogonally; use `## MODIFIED` for changes to existing requirement behavior or scope; use `## RENAMED` for name-only changes
Applied to files:
openspec/changes/add-multi-sensory-environment/proposal.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Applies to openspec/changes/*/specs/**/*.md : In spec delta files, use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` section headers with at least one `#### Scenario:` subsection per requirement
Applied to files:
openspec/changes/add-multi-sensory-environment/proposal.md
📚 Learning: 2025-12-27T08:02:58.340Z
Learnt from: chrisjz
Repo: SyntheticBrains/nematode PR: 22
File: openspec/changes/add-phase0-foundation-baselines/design.md:64-69
Timestamp: 2025-12-27T08:02:58.340Z
Learning: design.md files in openspec/changes/ are for technical decisions and design rationale, not normative requirements. SHALL/MUST language is only required in spec.md files (spec deltas) under openspec/changes/*/specs/, not in design.md, proposal.md, or tasks.md files.
Applied to files:
openspec/changes/add-multi-sensory-environment/proposal.md
📚 Learning: 2025-11-29T13:45:51.853Z
Learnt from: CR
Repo: SyntheticBrains/nematode PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-29T13:45:51.853Z
Learning: Applies to openspec/**/*.md : Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally marking non-normative guidance
Applied to files:
openspec/changes/add-multi-sensory-environment/proposal.md
📚 Learning: 2025-12-27T08:02:58.340Z
Learnt from: chrisjz
Repo: SyntheticBrains/nematode PR: 22
File: openspec/changes/add-phase0-foundation-baselines/design.md:64-69
Timestamp: 2025-12-27T08:02:58.340Z
Learning: Design.md files under openspec/changes/ should document architectural or design decisions and rationale, not normative requirements. Do not use SHALL/MUST language in design.md (reserve such language for spec.md files). The strict SHALL/MUST wording should appear only in openspec/changes/*/specs/*/specs.md (spec deltas). Use objective, rationale-focused language in design.md and place any formal requirements in the appropriate spec files.
Applied to files:
openspec/changes/add-multi-sensory-environment/design.md
🪛 LanguageTool
openspec/changes/add-multi-sensory-environment/tasks.md
[grammar] ~87-~87: Use a hyphen to join words.
Context: ... count: 1 ``` - [ ] Implement mixed type spawning - [ ] Update gradient comp...
(QB_NEW_EN_HYPHEN)
[style] ~294-~294: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s on 4. Work streams 6-7 depend on 1-4. Work streams 8-9 depend on all above. Work s...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.18.1)
openspec/changes/add-multi-sensory-environment/design.md
89-89: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
214-214: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (3)
openspec/changes/add-ablation-toolkit/tasks.md (2)
1-234: Clear structure and comprehensive task breakdown.The document is well-organized with logical dependencies, clear section hierarchy, and actionable checklist items. The dependency diagram (lines 207–221) effectively communicates task sequencing, and the cross-references to related proposal and spec files align with the learnings on scaffold structure for change proposals.
40-40: Strengthen normative language in validation and success criteria.Per coding guidelines for
openspec/**/*.mdfiles, normative requirements should use SHALL/MUST instead of "can," "runs," or "generates." Update the validation statements and success criteria to use prescriptive language:
- Line 40: "Framework can enumerate" → "Framework SHALL enumerate"
- Line 62: "Ablated ModularBrain runs without errors" → "Ablated ModularBrain SHALL run without errors"
- Line 83: "Ablated PPOBrain runs without errors" → "Ablated PPOBrain SHALL run without errors"
- Line 112: "Importance scores computed correctly" → "Importance scores SHALL be computed correctly"
- Line 161: "Report generates correctly" → "Report SHALL generate correctly"
- Line 187: "CLI runs ablation study end-to-end" → "CLI SHALL run ablation study end-to-end"
- Lines 229–233: All success criteria use "Can" → change to "SHALL" to make them binding
🔎 Proposed normative language updates
- **Validation**: Framework can enumerate and run ablation conditions + **Validation**: Framework SHALL enumerate and run ablation conditions - **Validation**: Ablated ModularBrain runs without errors, produces different behavior + **Validation**: Ablated ModularBrain SHALL run without errors and produce different behavior - **Validation**: Ablated PPOBrain runs without errors, produces different behavior + **Validation**: Ablated PPOBrain SHALL run without errors and produce different behavior - **Validation**: Importance scores computed correctly for test cases + **Validation**: Importance scores SHALL be computed correctly for test cases - **Validation**: Report generates correctly with all sections + **Validation**: Report SHALL generate correctly with all sections - **Validation**: CLI runs ablation study end-to-end + **Validation**: CLI SHALL run ablation study end-to-end - - [ ] Can ablate individual modules from ModularBrain + - [ ] SHALL ablate individual modules from ModularBrain - - [ ] Can ablate hidden layers from PPOBrain + - [ ] SHALL ablate hidden layers from PPOBrain - - [ ] Feature importance scores correctly identify critical modules + - [ ] Feature importance scores SHALL correctly identify critical modules - - [ ] Automated reports are readable and informative + - [ ] Automated reports SHALL be readable and informative - - [ ] CLI allows running ablation studies without code changes + - [ ] CLI SHALL allow running ablation studies without code changes - - [ ] Results are reproducible with seed control + - [ ] Results SHALL be reproducible with seed controlAs per coding guidelines for openspec files, use SHALL/MUST for normative requirements.
Also applies to: 62-62, 83-83, 112-112, 161-161, 187-187, 229-233
⛔ Skipped due to learnings
Learnt from: CR Repo: SyntheticBrains/nematode PR: 0 File: openspec/AGENTS.md:0-0 Timestamp: 2025-11-29T13:45:51.853Z Learning: Applies to openspec/**/*.md : Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally marking non-normative guidanceLearnt from: chrisjz Repo: SyntheticBrains/nematode PR: 22 File: openspec/changes/add-phase0-foundation-baselines/design.md:64-69 Timestamp: 2025-12-27T08:02:58.340Z Learning: design.md files in openspec/changes/ are for technical decisions and design rationale, not normative requirements. SHALL/MUST language is only required in spec.md files (spec deltas) under openspec/changes/*/specs/, not in design.md, proposal.md, or tasks.md files.Learnt from: CR Repo: SyntheticBrains/nematode PR: 0 File: openspec/AGENTS.md:0-0 Timestamp: 2025-11-29T13:45:51.853Z Learning: Use `openspec validate <change-id> --strict` to comprehensively validate change proposals before requesting approvalLearnt from: CR Repo: SyntheticBrains/nematode PR: 0 File: openspec/AGENTS.md:0-0 Timestamp: 2025-11-29T13:45:51.853Z Learning: Applies to openspec/changes/*/specs/**/*.md : In spec delta files, use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` section headers with at least one `#### Scenario:` subsection per requirementLearnt from: CR Repo: SyntheticBrains/nematode PR: 0 File: openspec/AGENTS.md:0-0 Timestamp: 2025-11-29T13:45:51.853Z Learning: In `tasks.md`, organize implementation work as a numbered checklist with sub-items using `- [ ]` unchecked format; update all items to `- [x]` after completionLearnt from: CR Repo: SyntheticBrains/nematode PR: 0 File: openspec/AGENTS.md:0-0 Timestamp: 2025-11-29T13:45:51.853Z Learning: Applies to openspec/changes/*/specs/**/*.md : Every requirement in spec deltas must include at least one scenario with `- **WHEN** condition` and `- **THEN** expected result` formatLearnt from: CR Repo: SyntheticBrains/nematode PR: 0 File: openspec/AGENTS.md:0-0 Timestamp: 2025-11-29T13:45:51.853Z Learning: Scaffold change proposals with `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<change-id>/specs/`openspec/changes/add-thermotaxis-system/tasks.md (1)
1-203: Well-structured thermotaxis implementation plan.The tasks are clearly organized, dependencies are explicit, and success criteria are measurable. The integration with the multi-sensory environment foundation is well-articulated, and the hierarchical benchmark naming follows the proposal's conventions. No concerns to raise.
…roposals docs: Add initial Phase 1 change specifications
1 participant
Changes:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.