Experiment Journal

1. Load experiment_journal.md if it exists
2. Load configuration_suggestions.md to know existing config IDs
3. Identify the next available config ID letter(s)
4. Review recent entries for context

Step 2 — Record Trial Results

For each completed trial, add a dated journal entry:

## Trial {ID} — {Date} — {Config Name}

### Setup
- **Config**: {Config ID from configuration_suggestions.md}
- **Changed params**: {param1}: {old}→{new}, {param2}: {old}→{new}
- **Run command**: `{exact command used}`
- **Duration**: {training time}

### Observations
- {observation 1 with specific numbers}
- {observation 2}
- Loss curves: {description of behavior}
- Convergence: {did it converge? at what step?}

### Metrics
| Metric | Baseline | This Trial | Delta |
|--------|----------|------------|-------|
| {metric1} | {val} | {val} | {+/-} |
| {metric2} | {val} | {val} | {+/-} |

### Analysis
{Scientific analysis of WHY the results are what they are.
Reference specific metrics, loss curves, and parameter interactions.
Compare to predictions from the hypothesis.}

### Conclusion
- **Hypothesis confirmed/refuted**: {brief statement}
- **Key insight**: {what we learned}
- **Next step**: {what to try next and why}

### Investigation Level
- [x] Parameter tuning
- [ ] Loss/metric analysis  
- [ ] Architecture investigation

Step 3 — Add Configuration Entry

If new configs are proposed, add them to configuration_suggestions.md using the project's existing format:

1. Find the next config ID: Look at existing <!-- CONFIG_START id: X --> blocks and use the next letter

2. Write the CONFIG block with all required fields:

   • id: Next available letter (A, B, C, ... Z, AA, AB, ...)
   • name: Descriptive name
   • priority: P0 (critical) to P5 (speculative)
   • status: new for fresh proposals
   • hypothesis: Scientific hypothesis
   • risk: What could go wrong
   • metrics_to_watch: List of metrics to monitor
   • params: Dict of parameter changes

   YAML safety for metrics_to_watch: List items that contain YAML special characters (>, <, :, #, ', ", {, }, [, ], %, @, `) MUST be wrapped in double quotes. Always quote to be safe — unquoted values containing > are parsed as YAML block scalars and will silently break parsing. Example:

   metrics_to_watch:
     - "IC Ret 30s (target: > 0.03, match v14's +0.059)"
     - "NaN eval loss (should NOT occur with detach_above=3)"
     - "BSS(live) (target: >= v17's +0.056)"
   

   Rule: If in doubt, quote every metrics_to_watch item.

3. Write the human-readable section below the CONFIG block with:

   • Hypothesis explanation
   • Risk explanation
   • Bash command snippet with the params
   • "Changed from default" summary
   • Key metrics to watch

Step 4 — Update Priority Rankings

If the priority table at the bottom of configuration_suggestions.md exists, update it:

• Add new configs with their priorities
• Adjust existing priorities based on new evidence
• Add rationale for priority changes

Step 5 — Create Journal Entry for Architectural Changes

For architecture changes (Phase 3 findings), use an extended format:

## Architecture Change {ID} — {Date}

### Motivation
{Why parameter/loss changes were insufficient — reference specific trials}

### Change Description  
{Detailed technical description of the architecture change}

### Implementation
- **Files modified**: {list}
- **Flag**: `--{flag_name}` (default: off)
- **Backward compatible**: {yes/no}

### Literature Reference
- {Paper title, authors, year}
- {Key finding that applies to our case}

### Before/After Diagram
\```
Before: Input → [A] → [B] → [C] → Output
After:  Input → [A] → [B'] → [B_new] → [C] → Output
\```

Journal Quality Standards

1. Date everything: Every entry has a date
2. Numbers, not adjectives: "IC improved from 0.008 to 0.025" not "IC improved a lot"
3. Compare to baseline: Always reference the baseline trial
4. Record negative results: Failed experiments are as valuable as successful ones
5. Link configs: Every trial references its config ID
6. Hypothesize first: The hypothesis should be written BEFORE running the trial (it's recorded in the config entry)
7. Be honest about attribution: If multiple things changed, note that attribution is uncertain

Config ID Assignment

Follow the existing convention in configuration_suggestions.md:

• Single letters: A through Z
• Combinations: G+F, I+F (for composed configs)
• The ID must be unique across all configs
• Check ALL existing <!-- CONFIG_START id: --> blocks before assigning