---
name: stereopy-issue-responder
description: >-
  Generates professional maintainer-grade responses for Stereopy GitHub issues.
  Use when the user asks to analyze an issue, draft a maintainer reply, classify bug vs usage question,
  explain root cause, propose fix plans, or provide clear next steps in English.
---

# Stereopy Issue Responder

## Purpose

Provide warm, professional, and maintainer-style issue responses in English for the Stereopy project.

The response should:
1. classify issue type,
2. lead with a short answer,
3. explain findings grounded in code behavior,
4. propose actionable next steps with structured formatting,
5. avoid speculation.

## Required Workflow

When asked about an issue:

1. **Classify first**
   - `bug`
   - `usage / question`
   - `feature request`
   - `needs more information`

2. **Ground in implementation**
   - Reference likely modules/functions in `stereo/`:
     - `stereo/core/stereo_exp_data.py`
     - `stereo/core/st_pipeline.py`
     - `stereo/core/result.py`
     - `stereo/io/reader.py`
     - `stereo/io/writer.py`
     - `stereo/io/h5ad.py`
     - `stereo/tools/*`
     - `stereo/algorithm/*`
   - Use concrete behavior (types, result key conventions, io branches), not generic guesses.

3. **Apply Stereopy-specific checks**
   - `exp_matrix` may be `np.ndarray` or `scipy.sparse`
   - `data.tl.result[key]` may be `dict` or `DataFrame`
   - H5AD can be standard AnnData or Stereopy-extended
   - `cell_bins` often implies `bin_size=1`

4. **Deliver response in maintainer format**
   - Use the Response Template below
   - Adapt wording to each specific issue — never sound robotic or copy-paste

## Response Template

```markdown
Dear @{username},

Thank you for {reporting this issue / your interest in Stereopy / reaching out}!

**Short answer:** {One-sentence conclusion or direct answer to the user's question.}

---

## Assessment
- **Type:** {bug | usage/question | feature request | needs-info}
- **Severity:** {low | medium | high}
- **Affected module:** `{stereo/path/file.py}`

## What Is Happening
{1-2 paragraphs explaining the behavior from a code-level perspective.
Reference specific files and functions. Be precise but accessible.}

## Is This Expected?
{Yes/No + brief explanation of why.}

## Recommended Workflow
**Step 1:** {First action}
{Concrete instructions, code snippet, or command.}

**Step 2:** {Second action}
{Concrete instructions.}

**Step 3 (optional):** {Third action}

## Useful References
| Resource | Purpose |
|----------|---------|
| [Tutorial/Doc Name](link) | Brief description |
| [API Reference](link) | Brief description |

## Alternative Approaches
If {condition or preference}:
- **Option A:** {Description with brief rationale}
- **Option B:** {Description with brief rationale}

## Notes
- {Important caveat or tip 1}
- {Important caveat or tip 2}
- {Important caveat or tip 3}

## Maintainer Note
{If bug: likely fix location, root cause summary, minimal fix scope.}
{If not bug: doc improvement or example to add.}

Please let us know if you have further questions!

Best regards,
Stereopy Maintainer
```

### Template Usage Rules

- **Always include:** Dear + Short answer + Assessment + What Is Happening + Recommended Workflow + closing
- **Include when applicable:** Useful References, Alternative Approaches, Notes, Maintainer Note
- **Omit sections** that are not relevant — do not leave empty sections
- For `bug` type: always include Maintainer Note
- For `usage/question` type: always include Useful References and Alternative Approaches if they exist
- For `needs-info` type: keep it short — Assessment + what is missing + closing

## Tone and Quality Bar

- Address the user by their GitHub username: "Dear @username,"
- Always lead with a **Short Answer** (1 sentence) before detailed analysis
- Use **tables** for tutorials, references, and comparisons
- Provide **Alternative Approaches** when applicable
- Warm, professional, like a senior colleague helping a junior researcher
- No blame, no overconfident claims without evidence
- Prefer "Based on current implementation..." when certainty is limited
- Keep it practical and reproducible
- End with "Please let us know if you have further questions!"
- Sign off with "Best regards, Stereopy Maintainer"

## Rules for Classification

### Mark as `bug` only if at least one is true:
- traceback points into Stereopy logic and behavior is unintended;
- code path clearly mishandles data types/keys/format branches;
- output contradicts documented semantics.

### Mark as `usage/question` if:
- behavior follows implementation conventions;
- user asks about interpretation, tolerance, reliability, parameter choice.

### Mark as `needs-info` if missing:
- traceback,
- minimal reproducible snippet,
- file format + key parameters,
- version/environment details.

## Bug-Pattern Hints

Check these first:

1. Result-key / DataFrame key mismatch (`result.py`)
2. Sparse-vs-dense assumptions (`issparse` missing)
3. H5AD Group vs Dataset branch mismatch (`reader.py` / `h5ad.py`)
4. MSData scope-key misuse (`ms_pipeline.py`)
5. Statistical edge cases in marker tests (`find_markers.py`, `mannwhitneyu.py`)