Imported from yzhaoinuw/preprocess_sleep_data (AGENTS.md). Install upstream with npx skills add yzhaoinuw/preprocess_sleep_data. Copyright stays with the author.

Guidelines and Tips for Agents

This file is the first thing any agent (Claude, Codex, or other) should read when joining a session on this repo. It defines the runtime, the common tasks, the conventions, and the project-specific reminders. Keep it short and current.

Startup Rule

At the beginning of a new chat or agent session for this project, read this file first and do not automatically read every markdown file in the repository. Use the Documentation map below to decide which other files are relevant to the current task.

Runtime Environment

When running code, tests, or the application for this repository, use:

• MATLAB R2025a

Typical startup:

matlab

After activation, use that environment for commands such as:

• MATLAB scripts, function smoke checks, and one-off inspection commands.

Common Tasks

Short recipes for the things you'll usually do in a session. All commands assume the env above is active.

Run the app for manual testing:

[app launch command]

Run the test suite (the CI-equivalent subset — skips slow or optional-dependency tests):

[test command — e.g. `pytest -v -m "not slow"` or `npm run test:unit`]

Run the full suite, including any slow or optional-dependency tests:

[full test command]

Pre-flight checklist before committing:

• Formatter / linter is clean (matches the CI format job): [formatter command]
• Test suite is green (matches the CI test job): [test command]
• A new entry has been prepended to work_log.md describing what was done, intended profiling signal if any, and the verification commands that were actually run.

If the change touches active modules, confirm imports still work — the smoke tests in [tests/test_smoke.py or equivalent] cover this.

Branch Handoff Discipline

Before switching away from an experimental or feature branch, fully resolve the work on that branch. Confirm whether the branch contains all intended changes, whether those changes are committed, and whether the user expects them merged, pushed, or intentionally left parked.

Do not switch to the integration branch ([main] — replace with your project's integration branch, often main, master, or dev) or start new work on another branch while important experimental-branch changes are only local, unmerged, or unverified. If related work accidentally lands on the integration branch, move that work back onto the experimental branch first and retest the combined behavior there before updating the integration branch.

Useful checks before switching or merging (portable git commands; run in any shell):

git status --short --branch
git log --oneline --left-right --cherry-pick [main]...HEAD
git merge-base --is-ancestor [main] HEAD

Documentation

Read these documents only as needed. The map below names each file and when it's worth opening.

• work_log.md and work_log_archive/

  • Use when the task needs recent implementation history, experiment outcomes, or verification breadcrumbs.
  • The live work_log.md holds at most the 5 most recent unique calendar dates. Default to reading only the two most recent dated entries.
  • Find date anchors with ripgrep and read only the slice you need: rg -n '^## [0-9]{4}-[0-9]{2}-[0-9]{2}' work_log.md
  • When older context is needed, open the matching file under work_log_archive/ by its date-range filename, or grep across both at once: rg -n '^## [0-9]{4}-[0-9]{2}-[0-9]{2}' work_log.md work_log_archive/
  • When prepending a dated entry, if today's calendar date already has a ## YYYY-MM-DD header at the top, add a new ### session subsection under it. Do not start a second ## YYYY-MM-DD header for the same date.
  • When prepending a new date would push the live log past 5 unique calendar dates, move the oldest 5 dates as a chunk into a new file at work_log_archive/work_log_<earliest>_to_<latest>.md. The live file always holds at most 5 unique dates; each archive file always holds exactly 5.

• next_steps.md

  • Use when planning or continuing unfinished work from previous sessions.
  • The "Currently Hot" pointer at the top names the active threads — read it first to know what's in flight.
  • Remove items after they are completed. Add new planned follow-ups when they become concrete.

• project_overview.md

  • Use when onboarding to the codebase structure or when a task touches an unfamiliar area.
  • The "What Looks Active vs. Legacy" section is the single most important map before editing — many repos accumulate parallel implementations, and this section keeps an agent from editing the wrong file.

• README.md

  • Use when changing user-facing setup, packaging, usage, or input-file expectations.

• CONTRIBUTING.md (if present)

  • Use when changing collaboration workflow, branch/test expectations, or documentation conventions.

The same anchor-grep pattern works for any structured Markdown doc in the repo — grep -n '^## ' <file> for the section map, then a targeted slice read rather than loading the whole file.

Git Ownership Note

If Git reports a "detected dubious ownership" warning for this repo, mark this repository as safe.

Windows (PowerShell):

git config --global --add safe.directory C:/path/to/this/repo

macOS / Linux:

git config --global --add safe.directory "$HOME/path/to/this/repo"

This is the preferred fix unless the repository ownership itself needs to be changed at the OS level.

Pre-commit Note

If your stack uses pre-commit and it cannot write to its default cache location, set a repo-local cache before running it.

Windows (PowerShell):

$env:PRE_COMMIT_HOME = "C:\path\to\this\repo\.pre-commit-cache"
python -m pre_commit run --all-files

macOS / Linux:

export PRE_COMMIT_HOME="$PWD/.pre-commit-cache"
python -m pre_commit run --all-files

Adjust the formatter / linter invocation for your stack (e.g., npx lint-staged, cargo fmt, gofmt -l .).

Commit Message Guidelines

Commit messages should use:

• a short title line
• a short body with flat bullet points for additional requested changes when a commit contains multiple user-requested updates

Commit message bullets should describe high-level added or changed behavior, not implementation details.

For feature commits, mention only the user-facing behavior that was added or changed.

Do not mention tests, docs, project memory updates, or behind-the-scenes implementation details in a feature commit message unless that internal work is itself the main purpose of the commit.

Project-Specific Reminders

• preprocess_sleep_data.m is the active main preprocessing function. Read it with README.md before editing helper scripts.
• video_start_time is a signed offset for mapping EEG/EMG time to video time: video_time = eeg_time + video_start_time. As of version 0.2.8, single-bin, single-video Viewpoint-only exports compute it from Info.BinFiles(1).TStart - Info.VideosFiles(1).Files(1).TStart.
• Do not broaden video-alignment behavior to multi-bin Viewpoint, Viewpoint plus separate TDT photometry, or TDT-only exports until the follow-ups in next_steps.md are checked.
• README.md is UTF-16 LE with a BOM. Preserve that encoding when editing it.