Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture

[suraj-ranganath]

🤖 Phase 1 establishes the source of truth for the final standalone parity epic.

Summary

Expand the parity audit beyond the PR #152 core matrix into a final product-completion matrix covering bundled plugins, memory/storage behavior, optional external-toolbox workflows, and documentation. This phase does not port large features; it decides precisely what is still non-stale and how later phases prove completion.

Scope

• Add or extend committed matrix/tooling for remaining areas not fully covered by docs/parity/eeglab_core_parity_matrix.json:
  • plugins/clean_rawdata
  • plugins/firfilt
  • plugins/ICLabel and plugins/ICLabel/viewprops
  • plugins/dipfit
  • functions/@eegobj, functions/@memmapdata, functions/@mmo
  • docs/tutorial coverage compared to EEGLAB concepts/tutorial structure
  • optional dependency workflows such as LIMO/PAC/FieldTrip-backed behavior
• Define status values for this final epic: implemented, port, consolidated, stale_skip, matlab_runtime_skip, optional_dependency, external_plugin, and docs_gap or similar.
• Define optional-dependency rules: when EEGPrep should implement a standalone path, when to use an optional dependency, and when to show clear user-facing limitations.
• Define docs architecture modeled after EEGLAB user docs: concepts, GUI tutorials, command-line/console history, preprocessing, data structures, rejection/ICA, STUDY, extensions/plugins, API reference, and migration guides.
• Update .notes/eeglab-migration-gap-audit.md or add a new final-epic audit note with concrete phase ownership.

Acceptance Criteria

• A machine-readable final parity/docs matrix exists and validates in CI or tests.
• Every remaining non-stale workflow is assigned to Phase 2-8 or explicitly classified as out of scope with rationale.
• Stale MATLAB demos/tests/shims remain skipped and are not planned as bloat.
• Runtime rule is restated and tested: installed package code does not depend on src/eegprep/eeglab.
• Documentation architecture is defined before docs writers start.
• Phase agents can select work from the matrix without asking product-scope questions.

Required References

• AGENTS.md
• .notes/eeglab-migration-gap-audit.md
• docs/parity/eeglab_core_parity_matrix.json
• src/eegprep/eeglab/plugins/
• docs/source/
• .agents/skills/eegprep-project-management/SKILL.md

/goal

/goal Build the final EEGPrep standalone parity audit foundation for the epic. Compare EEGPrep against the vendored EEGLAB plugin, object/storage, optional-toolbox, and documentation surfaces; classify every still-relevant non-stale workflow into an implement/optional-dependency/skip/docs status with phase ownership; define docs architecture modeled after EEGLAB user docs; add validation tests/tooling so unclassified rows fail; keep runtime code independent of src/eegprep/eeglab; and verify with focused tests, ruff/format/ty, and pre-commit. Do not port feature code in this phase except tiny validators/docs scaffolding needed for the contract.

[claude]

🤖 Plan:

• Read AGENTS.md, fix-issue skill, pull-request skill
• Fetch issue Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158 and parent epic Epic: Complete EEGPrep standalone EEGLAB parity and documentation #157
• Duplicate-work preflight (open PRs/issues)
• Inspect existing parity matrix infrastructure on PR [Parity] Complete remaining EEGLAB core gaps #152 branch
• Post analysis comment (this issue is multi-module design work, not a small PR)

Research

This is Phase 1 of epic #157 — a scope/design phase that defines an expanded parity matrix, new status taxonomy values (optional_dependency, external_plugin, docs_gap), an optional-dependency rule set, a Sphinx docs architecture, and validation tooling spanning bundled plugins, EEGLAB MATLAB classes, and docs coverage. By the explicit content of the issue and its acceptance criteria it is multi-module design work that will exceed 100 LOC and must coordinate with seven downstream phase issues (#159–#165), so per the fix-issue rules it is not eligible for a direct PR — a human should sign off on scope before implementation.

The current state already contains most of the foundations Phase 1 builds on, but several pieces live on the unmerged PR #152 branch (feature/eeglab-core-parity-completion) and not on develop. Phase 1 cannot land on develop until #152 merges or it must be stacked on feature/eeglab-full-standalone-completion as the epic prescribes.

Relevant code / artifacts

• .notes/eeglab-migration-gap-audit.md — 570-line existing audit; source-of-truth seed for the expanded matrix.
• docs/parity/eeglab_core_parity_matrix.json (PR [Parity] Complete remaining EEGLAB core gaps #152 only) — 608-row matrix covering categories 1–7; needs additive coverage for plugins / classes / docs.
• tools/eeglab_parity_matrix.py (PR [Parity] Complete remaining EEGLAB core gaps #152 only) — validator enforcing row schema, status taxonomy, scope, stale-policy fields; natural place to extend taxonomy and scope.
• tests/test_eeglab_parity_matrix.py (PR [Parity] Complete remaining EEGLAB core gaps #152 only) — enforces "every in-scope EEGLAB path classified"; needs new tests for plugin/class/docs scope and the new statuses.
• docs/source/ — current Sphinx layout (user_guide/, api/, examples/) that Phase 1 reorganizes into an EEGLAB-style manual outline.

Dependency / blocker check

• PR [Parity] Complete remaining EEGLAB core gaps #152 (epic Epic: Complete EEGPrep remaining EEGLAB core parity gaps #131 Phase 1) is OPEN, all 8 CI checks SUCCESS, mergeable; the matrix tooling Phase 1 must extend lives only on that branch.
• No competing PRs touch docs/parity/ or tools/eeglab_parity_matrix.py. Work is non-overlapping with in-flight PR Fix EEGBrowser visual parity axes #130 (EEGBrowser visual parity).
• The .agents/skills/eegprep-project-management/SKILL.md referenced by epic Epic: Complete EEGPrep standalone EEGLAB parity and documentation #157 also only exists on PR [Parity] Complete remaining EEGLAB core gaps #152's branch.
• The vendored src/eegprep/eeglab/ tree referenced by the issue is not present on develop; the validator's "EEGLAB reference tree missing" path will fire until [Parity] Complete remaining EEGLAB core gaps #152 lands or the tree is restored.

Proposed Approach (design — not implementing yet)

Recommended decomposition for a human reviewer before implementation begins. Phase 1 is naturally three sub-deliverables that can land as one PR stacked on #152's branch.

1. Expanded matrix scope and status taxonomy. Extend tools/eeglab_parity_matrix.py with a second discovery surface for plugin/class/docs paths and add the new statuses (optional_dependency, external_plugin, docs_gap) on top of the existing seven. Add an epic field on rows so the original 608 PR [Parity] Complete remaining EEGLAB core gaps #152 rows stay tagged epic: "131" and new rows are epic: "157" — this avoids destabilizing [Parity] Complete remaining EEGLAB core gaps #152's green test. New in-scope roots: plugins/clean_rawdata/**/*.m, plugins/firfilt/**/*.m, plugins/ICLabel/**/*.m (incl. viewprops/), plugins/dipfit/**/*.m, functions/@eegobj/*.m, functions/@memmapdata/*.m, functions/@mmo/*.m. Each row needs responsible_phase in {phase_2..phase_8, none} matching Phase 2: clean_rawdata and FIRFilt bundled-plugin completion #159–Phase 8: Final integration, QA, release hardening, and evidence #165.

2. Optional-dependency rule contract. Codify the three-way decision (standalone implementation vs. optional dep vs. user-facing limitation) as a small machine-readable section in the matrix metadata, plus a validator rule: rows with status optional_dependency must name the dependency, the fallback behavior, and a docs link. Prevents each downstream phase relitigating the question.

3. Docs architecture spec. Add .notes/eeglab-docs-architecture.md (not Sphinx files yet — Phase 7 Phase 7: EEGLAB-style Sphinx documentation and tutorials #164 writes those) defining the EEGLAB-style TOC: installation, concepts (data structure, events, epochs, channel locations, ICA, STUDY, history/console), GUI tutorials, console tutorials, scripting/API, plugin/extension authoring, EEGLAB migration, troubleshooting, API reference. Record the mapping from existing docs/source/user_guide/ files to spec sections so Phase 7 reorganizes rather than rewrites.

4. Runtime-contract test. Add tests/test_runtime_eeglab_independence.py asserting no module under src/eegprep/** imports from or reads src/eegprep/eeglab/. Codifies the rule that PR [Parity] Complete remaining EEGLAB core gaps #152 follows but doesn't enforce.

Estimated size: ~150–300 LOC of tooling + tests, plus the two .notes/ documents. No package runtime code changes.

Open Questions

1. Stacking target. Phase 1 PR targets feature/eeglab-full-standalone-completion per epic Epic: Complete EEGPrep standalone EEGLAB parity and documentation #157, waiting for [Parity] Complete remaining EEGLAB core gaps #152 to merge, or rebases onto develop after [Parity] Complete remaining EEGLAB core gaps #152 merges? The epic prescribes the former.
2. Matrix file split vs. extend. Keep one eeglab_core_parity_matrix.json and add new rows with epic/status tagging, or add a sibling eeglab_final_parity_matrix.json? Extending preserves a single validator; splitting isolates churn from [Parity] Complete remaining EEGLAB core gaps #152's frozen test set. Recommend extending with an epic field.
3. @eegobj / @memmapdata / @mmo classification. These were explicitly out_of_scope in PR [Parity] Complete remaining EEGLAB core gaps #152's matrix metadata. Should they classify as port (real Python equivalents), consolidated (folded into EEGPrepSession / numpy memmap), or matlab_runtime_skip? Phase 5 (Phase 5: Large-dataset storage and storedisk semantics #162) owns storedisk semantics — Phase 1 needs the classification, not the implementation.
4. docs_gap semantics. Row-level status (this MATLAB function has no doc equivalent yet) or a separate matrix entirely (per-tutorial coverage)?
5. Optional-dependency scope. Cover FieldTrip / LIMO / Manopt / PAC toolboxes (all named in epic Epic: Complete EEGPrep standalone EEGLAB parity and documentation #157 and phase issues), or only ones with existing EEGPrep call sites? A finite enumeration prevents scope creep into Phase 4 (Phase 4: STUDY statistics, PAC, and LIMO-compatible workflows #161) territory.

Not opening a PR yet — please answer (1)–(5) above (or confirm "extend single matrix with epic field, stack on #157 branch, defer @eegobj classification to Phase 5") and I'll implement Phase 1 in a stacked branch agent/20260607-fix-158 on top of #152's branch.

[suraj-ranganath]

🤖 Phase 1 PR #166 has merged into feature/eeglab-full-standalone-completion. Closing this phase issue as completed.