cursor,windsurf(rules[dev-loop]) Sync with latest python loop

Author: tony

.cursor/rules/avoid-debug-loops.mdc

@@ -0,0 +1,57 @@
+---
+description: When stuck in debugging loops, break the cycle by minimizing to an MVP, removing debugging cruft, and documenting the issue completely for a fresh approach
+globs: *.py
+alwaysApply: true
+---
+# Avoid Debug Loops
+
+When debugging becomes circular and unproductive, follow these steps:
+
+## Detection
+- You have made multiple unsuccessful attempts to fix the same issue
+- You are adding increasingly complex code to address errors
+- Each fix creates new errors in a cascading pattern
+- You are uncertain about the root cause after 2-3 iterations
+
+## Action Plan
+
+1. **Pause and acknowledge the loop**
+   - Explicitly state that you are in a potential debug loop
+   - Review what approaches have been tried and failed
+
+2. **Minimize to MVP**
+   - Remove all debugging cruft and experimental code
+   - Revert to the simplest version that demonstrates the issue
+   - Focus on isolating the core problem without added complexity
+
+3. **Comprehensive Documentation**
+   - Provide a clear summary of the issue
+   - Include minimal but complete code examples that reproduce the problem
+   - Document exact error messages and unexpected behaviors
+   - Explain your current understanding of potential causes
+
+4. **Format for Portability**
+   - Present the problem in quadruple backticks for easy copying:
+
+````
+# Problem Summary
+[Concise explanation of the issue]
+
+## Minimal Reproduction Code
+```python
+# Minimal code example that reproduces the issue
+```
+
+## Error/Unexpected Output
+```
+[Exact error messages or unexpected output]
+```
+
+## Failed Approaches
+[Brief summary of approaches already tried]
+
+## Suspected Cause
+[Your current hypothesis about what might be causing the issue]
+````
+
+This format enables the user to easily copy the entire problem statement into a fresh conversation for a clean-slate approach.

.cursor/rules/git-commits.mdc

@@ -1,6 +1,7 @@
 ---
 description: git-commits: Git commit message standards and AI assistance
 globs: git-commits: Git commit message standards and AI assistance | *.git/* .gitignore .github/* CHANGELOG.md CHANGES.md
+alwaysApply: true
 ---
 # Optimized Git Commit Standards
 

.cursor/rules/notes-llms-txt.mdc

@@ -0,0 +1,42 @@
+---
+description: LLM-friendly markdown format for notes directories
+globs: notes/**/*.md,**/notes/**/*.md
+alwaysApply: true
+---
+
+# Instructions for Generating LLM-Optimized Markdown Content
+
+When creating or editing markdown files within the specified directories, adhere to the following guidelines to ensure the content is optimized for LLM understanding and efficient token usage:
+
+1. **Conciseness and Clarity**:
+   - **Be Brief**: Present information succinctly, avoiding unnecessary elaboration.
+   - **Use Clear Language**: Employ straightforward language to convey ideas effectively.
+
+2. **Structured Formatting**:
+   - **Headings**: Utilize markdown headings (`#`, `##`, `###`, etc.) to organize content hierarchically.
+   - **Lists**: Use bullet points (`-`) or numbered lists (`1.`, `2.`, etc.) to enumerate items clearly.
+   - **Code Blocks**: Enclose code snippets within triple backticks (```) to distinguish them from regular text.
+
+3. **Semantic Elements**:
+   - **Emphasis**: Use asterisks (`*`) or underscores (`_`) for italicizing text to denote emphasis.
+   - **Strong Emphasis**: Use double asterisks (`**`) or double underscores (`__`) for bold text to highlight critical points.
+   - **Inline Code**: Use single backticks (`) for inline code references.
+
+4. **Linking and References**:
+   - **Hyperlinks**: Format links using `[Link Text](mdc:URL)` to provide direct access to external resources.
+   - **References**: When citing sources, use footnotes or inline citations to maintain readability.
+
+5. **Avoid Redundancy**:
+   - **Eliminate Repetition**: Ensure that information is not unnecessarily repeated within the document.
+   - **Use Summaries**: Provide brief summaries where detailed explanations are not essential.
+
+6. **Standard Compliance**:
+   - **llms.txt Conformance**: Structure the document in alignment with the `llms.txt` standard, which includes:
+     - An H1 heading with the project or site name.
+     - A blockquote summarizing the project's purpose.
+     - Additional markdown sections providing detailed information.
+     - H2-delimited sections containing lists of URLs for further details.
+
+By following these guidelines, the markdown files will be tailored for optimal LLM processing, ensuring that the content is both accessible and efficiently tokenized for AI applications.
+
+For more information on the `llms.txt` standard, refer to the official documentation: https://llmstxt.org/

.windsurfrules

@@ -0,0 +1,136 @@
+# libtmux Python Project Rules
+
+<project_stack>
+- uv - Python package management and virtual environments
+- ruff - Fast Python linter and formatter
+- py.test - Testing framework
+  - pytest-watcher - Continuous test runner
+- mypy - Static type checking
+- doctest - Testing code examples in documentation
+</project_stack>
+
+<coding_style>
+- Use a consistent coding style throughout the project
+- Format code with ruff before committing
+- Run linting and type checking before finalizing changes
+- Verify tests pass after each significant change
+</coding_style>
+
+<python_docstrings>
+- Use reStructuredText format for all docstrings in src/**/*.py files
+- Keep the main description on the first line after the opening `"""`
+- Use NumPy docstyle for parameter and return value documentation
+- Format docstrings as follows:
+  ```python
+  """Short description of the function or class.
+
+  Detailed description using reStructuredText format.
+
+  Parameters
+  ----------
+  param1 : type
+      Description of param1
+  param2 : type
+      Description of param2
+
+  Returns
+  -------
+  type
+      Description of return value
+  """
+  ```
+</python_docstrings>
+
+<python_doctests>
+- Use narrative descriptions for test sections rather than inline comments
+- Format doctests as follows:
+  ```python
+  """
+  Examples
+  --------
+  Create an instance:
+
+  >>> obj = ExampleClass()
+  
+  Verify a property:
+  
+  >>> obj.property
+  'expected value'
+  """
+  ```
+- Add blank lines between test sections for improved readability
+- Keep doctests simple and focused on demonstrating usage
+- Move complex examples to dedicated test files at tests/examples/<path_to_module>/test_<example>.py
+- Utilize pytest fixtures via doctest_namespace for complex scenarios
+</python_doctests>
+
+<testing_practices>
+- Run tests with `uv run py.test` before committing changes
+- Use pytest-watcher for continuous testing: `uv run ptw . --now --doctest-modules`
+- Fix any test failures before proceeding with additional changes
+</testing_practices>
+
+<git_workflow>
+- Make atomic commits with conventional commit messages
+- Start with an initial commit of functional changes
+- Follow with separate commits for formatting, linting, and type checking fixes
+</git_workflow>
+
+<git_commit_standards>
+- Use the following commit message format:
+  ```
+  Component/File(commit-type[Subcomponent/method]): Concise description
+
+  why: Explanation of necessity or impact.
+  what:
+  - Specific technical changes made
+  - Focused on a single topic
+
+  refs: #issue-number, breaking changes, or relevant links
+  ```
+
+- Common commit types:
+  - **feat**: New features or enhancements
+  - **fix**: Bug fixes
+  - **refactor**: Code restructuring without functional change
+  - **docs**: Documentation updates
+  - **chore**: Maintenance (dependencies, tooling, config)
+  - **test**: Test-related updates
+  - **style**: Code style and formatting
+
+- Prefix Python package changes with:
+  - `py(deps):` for standard packages
+  - `py(deps[dev]):` for development packages
+  - `py(deps[extra]):` for extras/sub-packages
+
+- General guidelines:
+  - Subject line: Maximum 50 characters
+  - Body lines: Maximum 72 characters
+  - Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
+  - Limit to one topic per commit
+  - Separate subject from body with a blank line
+  - Mark breaking changes clearly: `BREAKING:`
+</git_commit_standards>
+
+<pytest_testing_guidelines>
+- Use fixtures from conftest.py instead of monkeypatch and MagicMock when available
+- For instance, if using libtmux, use provided fixtures: server, session, window, and pane
+- Document in test docstrings why standard fixtures weren't used for exceptional cases
+- Use tmp_path (pathlib.Path) fixture over Python's tempfile
+- Use monkeypatch fixture over unittest.mock
+</pytest_testing_guidelines>
+
+<import_guidelines>
+- Prefer namespace imports over importing specific symbols
+- Import modules and access attributes through the namespace:
+  - Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
+  - This applies to standard library modules like pathlib, os, and similar cases
+- For typing, use `import typing as t` and access via the namespace:
+  - Access typing elements as `t.NamedTuple`, `t.TypedDict`, etc.
+  - Note primitive types like unions can be done via `|` pipes
+  - Primitive types like list and dict can be done via `list` and `dict` directly
+- Benefits of namespace imports:
+  - Improves code readability by making the source of symbols clear
+  - Reduces potential naming conflicts
+  - Makes import statements more maintainable
+</import_guidelines>