Skip to content

Add per-flow CHANGELOG.md convention to pipeio

Proposal

Introduce a convention for each pipeio flow to have its own CHANGELOG.md at the flow root (e.g. code/pipelines/<flow>/CHANGELOG.md). This captures high-level design history that git log can't easily convey.

What belongs in a flow CHANGELOG

  • Strategy shifts — e.g. "template subtraction → time-sample masking", with rationale linking to meeting/idea notes
  • DAG reorganizations — when rule order changes and why (e.g. "ttl_removal moved before feature extraction so badlabel sees clean data")
  • Architecture decisions — tier structures, auto-skip logic, method choices
  • Key discoveries that drive design — e.g. "TDM row scan order", "sub-01-only contamination", pulse properties
  • Cross-references to notio notes (meetings, ideas, results) and external refs

What doesn't belong

  • Every bug fix or parameter tweak (git log is authoritative)
  • Internal refactors that don't change behavior
  • Info already in CLAUDE.md, theory.md, or flow spec

Why this is valuable

  1. Onboarding — new agent/human can read the CHANGELOG to understand why the flow looks the way it does, without grepping through months of commits
  2. Meeting handoffs — decisions made in meetings (e.g. Ramon's masking strategy) often span multiple commits; CHANGELOG captures the "why" once, linked to the meeting note
  3. Regret prevention — documents what was tried and why it was abandoned, so nobody reintroduces it six months later
  4. Memory scaffolding — agent memory can reference CHANGELOG entries instead of caching the same info

Example

Created today for pixecog's preprocess_ieeg flow: code/pipelines/preprocess_ieeg/CHANGELOG.md — two entries documenting: - 2026-04-11: template subtraction → time-sample masking (with DAG reorder) - 2026-04-10: two-tier badlabel, auto-skip TTL, pre-lowpass LNR

Each entry has strategy, why, refs to notio notes. ~60 lines of markdown total.

Possible pipeio integration

  • pipeio_flow_new could scaffold an empty CHANGELOG.md with a header template
  • pipeio_mod_audit / pipeio_docs_collect could surface CHANGELOG in the flow index / docs site
  • pipeio_flow_status could show "last changelog entry: YYYY-MM-DD" as a freshness signal
  • Optional pipeio_changelog_add tool that takes a date + title + rationale and appends a properly-formatted entry with notio note auto-linking

Relation to existing docs

  • theory.md describes current state (how the mod works now)
  • spec.md describes interface (inputs/outputs/params)
  • CHANGELOG.md describes history (why we're here, what we tried)

All three are complementary. Theory goes stale if not updated when strategy changes; CHANGELOG provides the audit trail that motivates theory rewrites.

Raised from pixecog preprocess_ieeg after the TTL removal strategy change (template subtraction → time-sample masking, 2026-04-11 Ramon meeting).

Source context: pixecog

PixEcog (pixecog): Neuropixels and ECoG dataset and analysis

Recent commits: 

ef3592f preprocess_motion: report, updated index with report link, docs collect
456d660 Update preprocess_motion flow index, docs collect, snakemake report
d57e895 Add preprocess_motion flow: pipeline code, rawprep, utils, docs, CHANGELOG

README:

type: readme

Quick Start for Collaborators

Follow this checklist to get started with Pixecog documentation and workflows.

🐀 Pixecog Project — Compact Overview

Core principles

  • One immutable BIDS raw dataset (raw/) as the canonical baseline
  • Each analysis pipeline ha