| name | fix-issue |
| description | End-to-end workflow for fixing a GitHub issue. Use when asked to fix, investigate, or resolve a GitHub issue in sccn/eegprep. |
Skill: Fix GitHub Issue
You are to fix the Github issue indicated by the user.
Background
Read first:
@AGENTS.md
You may not proceed to a new task until you have completed all prior tasks. If
you cannot complete a task, write a Github comment with your last status and why
you failed. A task list is at the end of this document.
Writing Style for All GitHub Comments
Be terse. Every sentence must convey information that the reader does not
already have. Follow these rules in all comments you post:
- No preamble, no filler, no editorializing ("I've thoroughly investigated...",
"After careful analysis...", "This is an interesting problem...").
- No repeating information already in the issue body.
- No restating what code does when a link suffices.
- Max 3-4 sentences of prose per comment section. Use links and code, not words.
- Annotate code links, don't narrate them. Bad: "The key/value arg validation is
in eegobj.py where it checks for paired inputs".
Good:
src/eegprep/functions/eegobj/eegobj.py#L65-L71 - key/value arg validation.
Research
Use gh to fetch the issue. Read the codebase to find all relevant source
files. Post a single comment combining your research and proposed fix.
Before you write code, run a duplicate-work preflight:
- Check open pull requests for the same issue or subsystem (
gh pr list --state open --search "<issue-id or keyword>").
- Check open issues for the same root cause (
gh issue list --state open --search "<keyword>").
- If overlapping work already exists, do not open a parallel implementation PR.
Add a short issue comment summarizing what you found and either:
- hand off to the existing PR, or
- scope your change explicitly to non-overlapping follow-up work.
The comment has two sections: Research and Proposed Fix.
Research section
Title: # Research
- 2-3 sentences: what's broken/missing and why (root cause, not symptoms).
- A
**Relevant code** list: max 5 links, each with a short (<10 word) annotation.
Example:
EEGobj.__init__() routes path strings through pop_loadset(). When
scipy.io.loadmat() fails, pop_loadset() falls back to pop_loadset_h5(),
which opens the HDF5 file without a context manager, so repeated loads can
leak file handles. Root cause: h5py.File(...) is never closed.
Relevant code
Proposed Fix section
Title: # Proposed Fix
There are 2 cases:
-
Bug fix: Show the call chain that triggers the error, then state the fix
in one sentence. Include a code snippet only if the fix is non-obvious.
env.run() returns a tuple; foo() assumes an object and calls .abc().
Fix: unwrap the tuple in RolloutWorker._step() before passing to foo().
-
Design change: The design doc replaces the # Proposed Fix section.
Write it directly in the issue comment (agents cannot commit files before the PR). The 3-4 sentence prose cap applies to # Research; the design doc can be around a thousand words. As required, Use an Explore subagent to gather relevant files/lines, related issues/PRs, and reusable utilities. Summarize findings, note gaps, and save a research note. Ask 3–6 targeted questions: scope boundaries, tests, tradeoffs, open questions. Avoid questions answered by code search. Then draft the design doc as a spec. Keep it concise, cite real files/lines, include non-empty Open Questions, and avoid backward-compat unless needed. Iterate until settled. Send design + spec to a reviewer subagent. Incorporate clear improvements, and ask the user only about ambiguous decisions. Keep everything in one comment.
In both cases: find the minimally disruptive fix. Do not over-engineer.
Implementation
Once you have researched and prepared your design or planned fix, you may
proceed to implementation. You MUST implement your changes in a branch with the
following format agent/{YYYYMMDD}-fix-{issue-id}. You are allowed to create
branches on github as well as submit PRs from those branches.
You will implement a test which demonstrates your changed behavior before
beginning work. Your tests will be minimal and refrain from using mocks.
Testing
- You write your test before you make your fix, and validate your fix works.
- You use an existing test file in
tests/ if appropriate.
- You never use mocks when testing.
- You keep tests simple and minimal. You do not test obvious behavior like "object has an attr".
- You run
./pre-commit.py --fix and resolve all reported issues before uploading.
- You will test using
uv run pytest before uploading.
- You will ensure all tests pass.
Uploading
When all tests pass, you may proceed to upload your branch.
Open a pull request following .agents/skills/pull-request/SKILL.md exactly.
Read that file and use the plain-text format it specifies — no markdown headers,
no bullet lists, no ## Summary sections. Violations will be rejected.
Attach it to the Github issue with a comment summarizing the fix.
Verify CI Status
After opening the pull request, you must verify that CI checks pass:
- Monitor the PR using
gh pr view <number> --json statusCheckRollup
- Wait for the unit tests to complete
- If tests fail, investigate and fix any issues
- Push additional commits to address CI failures
- Do not consider the PR complete until all relevant checks pass
Key checks to monitor:
- unit tests: Must pass - validates your changes don't break existing functionality
- lint-and-format: Must pass - ensures code style compliance
- build-docs: Should pass if you modified documentation
Tasks
The tasks for this skill:
If at any point you are unable to proceed, you must add a comment to the Github
issue with your last status.
RULES
- Never credit yourself in commits or comments.
