---
name: general-instructions
description: General workflow instructions for Claude Code agents working in this repository. Covers environment setup, coding workflow, documentation, testing, and error-handling practices.
---

# General Instructions for Claude Code Agents

The following rules apply to **every** task you perform in this repository.

---

## 1. Use the `graph-signal-diffusion` Conda Environment for All Python Execution

All unit tests, smoke tests, and any other Python execution **must** run inside the Conda environment `graph-signal-diffusion`.
Follow the full instructions in `.github/skills/graph-signal-diffusion-python/SKILL.md`. Key points:

- **Preferred:** `conda run -n graph-signal-diffusion <command>` (single-command form).
- **Acceptable:** `conda activate graph-signal-diffusion` followed immediately by the command in the same terminal session.
- **Never** run `python`, `pytest`, or any test command outside `graph-signal-diffusion`.

---

## 2. Describe Your Approach Before Writing Code

Before writing **any** code, describe your planned approach and **wait for explicit approval** from the user.
The only exception is when the user explicitly tells you to start implementing right away.

---

## 3. Ask Clarifying Questions When Requirements Are Ambiguous

If the requirements or task description are ambiguous, incomplete, or open to multiple interpretations, **ask clarifying questions before writing any code**.
Do not guess or make assumptions that could lead to wasted effort.

---

## 4. Suggest Edge Cases and Test Cases After Writing Code

After you finish writing code, you **must**:

1. List the edge cases that could affect correctness.
2. Suggest concrete test cases that cover those edge cases.

This helps catch issues early and ensures thorough testing.

---

## 5. Document Code Changes in `docs/agent_summaries/`

After completing a coding task, create (or update) a summary document in `docs/agent_summaries/` in **Markdown (.md)** format.
The document should include:

- What was changed and why.
- Files modified or created.
- Any relevant design decisions.

After writing the document, **tell the user the exact file path** of the summary you just wrote.

---

## 6. Bug Fixing: Reproduce First with a Unit Test

When you encounter or are asked to fix a bug:

1. **First**, write a unit test that reliably **reproduces** the bug.
2. **Then**, implement the fix.
3. **Finally**, verify the fix by running the test until it passes.

Do not attempt a fix without a reproducing test.

---

## 7. Handle Previously-Created Failing Tests Gracefully

If any previously-created unit tests fail **and** the failure is **not** caused by your recent changes:

- **Do not** silently delete or modify those tests.
- **Ask the user** whether they want to remove or update the failing test script before taking action.

---

## 8. Break Large Tasks into Smaller Ones

If a task requires changes to **more than 5 files**, **stop** and break it into smaller, independently deliverable sub-tasks.
Present the breakdown to the user for approval before proceeding.

---

## 9. Reflect on Corrections and Prevent Repeat Mistakes

Every time the user corrects you:

1. **Reflect** on what you did wrong.
2. **Document** the mistake, its root cause, and a concrete prevention plan in `docs/agent_summaries/` (Markdown format).
3. **Tell the user** which file you wrote.
4. Follow the prevention plan in all future work to ensure the same mistake is never repeated.