| name | research-session-workflow |
| description | Starts a research session and logs EXP and NOTE entries with timestamps. Use when beginning research work, logging experiments, or writing discussion notes. Promote findings to PAPER_OUTLINE only when drafting the paper. |
| disable-model-invocation | true |
Research session workflow
Session start
- docs/research/README.md — load one linked doc, not the full log
- EXPERIMENT_LOG.md § Current phase / Recommended next step
- One
EXP-… row from the same log index if needed
- Skim DISCUSSION_NOTES.md for open questions (newest first)
North star: PIPELINE_ARCHITECTURE.md.
During work
Tag changes by pipeline stage: pre | model | post | metric | train.
Plan docs with JSON/schemas: design-doc-fields.mdc and DATASET_PREP_PIPELINE.md §6.3.
Log experiment (EXP-YYYYMMDD-NN)
Same turn, no ask: After any measurable run or offline eval (debug_ar_onset_overfit.py, eval_dense_onset.py, threshold sweep, training finish), prepend or update EXPERIMENT_LOG.md in the same session — do not offer to log or wait for user confirmation.
Complete the series: When a thread has multiple runs (run1, run2, v3, v4, offline --ar_decode logs under logs/), append every run’s key numbers to the same EXP-… entry in the session you discover them — not only the latest run and not vague “local v4” hand-waves.
Before suggesting a re-run: grep EXPERIMENT_LOG.md and logs/ for the checkpoint/config — if decode already exists on disk, read it and update the log instead of proposing the job again.
Prepend to EXPERIMENT_LOG.md after measurable runs:
- Top of
## Experiment entries + new index row at top
- Timestamp:
YYYY-MM-DD HH:MM:SS from system clock (Get-Date -Format "yyyy-MM-dd HH:mm:ss" / date +"%Y-%m-%d %H:%M:%S"). No approximate suffixes.
- Track, status, config paths, key numbers, conclusion
- Increment
NN per calendar day; check latest ID before prepending
Template: _EXPERIMENT_ENTRY_TEMPLATE.md
Log discussion (NOTE-YYYYMMDD-NN)
Prepend to DISCUSSION_NOTES.md for design insights, Q&A, failure analysis — even without a new run.
Fields: Timestamp, Topic, Context, Discovery, Implication, Open (optional), Related.
Template: _DISCUSSION_NOTE_TEMPLATE.md
Update paper (optional — when drafting for publication)
Do not log every run in PAPER_OUTLINE.md. EXPERIMENT_LOG.md is the authoritative experiment record.
When a result is paper-worthy, promote it to the outline:
| Section | Action |
|---|
| Abstract / Results | Selected numbers and claims only |
| Methods | Align with PIPELINE_ARCHITECTURE.md |
| Discussion | Hypotheses supported by promoted EXP + NOTE |
Cite EXP-… / NOTE-…. Link back to EXPERIMENT_LOG for full history.
Session end
