Eegprep Feature Development

EEGPrep Feature Development

Use this workflow when building a new EEGPrep feature.

Workflow

1. Switch to origin/develop, pull from origin, and create a new branch with an appropriate name.

2. For every feature to be developed, look at EEGLAB first and find equivalent implementations if they exist. Go through those implementations thoroughly. Match functionality and UX where relevant, and inspect every plausible user flow and edge case.

3. As you work maintain a running .notes/implementation-notes.html file that captures anything I should know about how the implementation diverges from or interprets the spec, including:

• Design decisions: choices you made where the spec was ambiguous
• Deviations: places where you intentionally departed from the spec, and why
• Tradeoffs: alternatives you considered and why you picked what you did
• Open questions: anything you'd want me to confirm or revise

4. Plan how to build the features within EEGPrep's existing structure. Read and follow AGENTS.md. Plan thoroughly, and break down the work into steps.

5. Execute the plan and write code. Do not take shortcuts. Maintain current coding conventions and follow AGENTS.md. Write tests as described there. Aim for more than 90% coverage for the changed feature code, and ensure the tests pass. Remember, while we are doing a porting project, EEGPrep must work well standalone and must be a delight to use for EEG Researchers. For user-facing pop_* or menu actions, preserve the eegprep-console workspace contract: return (EEG, com) with return_com=True, update GUI state through EEGPrepSession, and keep EEG/ALLEEG/history visible from both the GUI and the console. Make the GUI-plus-console workflow feel seamless for researchers who switch between menus/dialogs, command history, and workspace inspection. Whenever a user-facing API, GUI, console, workflow, plugin, or help behavior changes, update the relevant Sphinx docs and packaged help resources in the same branch. The docs should describe EEGPrep as a standalone Python/Qt application first, with EEGLAB comparisons only where they help users migrate, understand parity decisions, or handle file/indexing boundaries. For mixed GUI plus eegprep-console features, document both the user workflow and the EEGPrepSession state that stays synchronized.

6. For features that involve a GUI component, use the eeglab-gui-visual-parity skill to iteratively develop the GUI so the UI/UX is familiar to EEGLAB users. Follow EEGPrep's current GUI conventions, keep performance and user experience high, and do not take shortcuts. You must ensure that there is visual parity with EEGLAB for GUI based features; alignment, arrangement, button placement, labels, text fields, default values, enabled states, and control flow are important.

7. Simulate how users would exercise each feature with the gui-agent-flow-qa skill and Codex's GUI Agent. Cover typical user flows, including loading data from sample_data, and use every feature developed in the branch as a user would. Also cover edge cases that are likely from a user's point of view. For interactive features, include mixed GUI plus eegprep-console flows: act in the GUI, inspect/use EEG in the console, then run a console command and verify the GUI/history refresh. Wherever relevant use the cursor and keyboard like the user would actually use the app. Fix any bugs that surface.

8. After implementation and GUI parity/QA work, write additional regression tests and integration tests for behaviors discovered during testing, including tests/test_console_workspace.py when shared workspace sync or console wrappers are affected.

9. Review the current feature branch against origin/develop. Use the github-pr-review skill when appropriate.

10. Act on review findings. Do not take shortcuts while addressing findings. If any findings are not fixed, report them to the user at the end. If GUI features are involved, return to Step 5, then repeat Step 8 until the branch looks good.

11. When implementation matches the plan and all required tests succeed, create a draft PR to origin/develop as described in AGENTS.md. The PR must include all features requested by the user.

12. After creating the PR, tell the user everything that was done, especially anything that should be flagged for their attention.