# Augment Guidelines

## Development Process

### Project Stack

The project uses the following tools and technologies:

- **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

### Development Workflow

1. **Start with Formatting**

```

uv run ruff format .

```

2. **Run Tests**

```

uv run py.test

```

For continuous testing during development, use pytest-watcher:

```

# Watch all tests

uv run ptw .

# Watch and run tests immediately, including doctests

uv run ptw . --now --doctest-modules

# Watch specific files or directories

uv run ptw . --now --doctest-modules src/libtmux/_internal/

```

3. **Commit Initial Changes**

Make an atomic commit for your changes using conventional commits.

4. **Run Linting and Type Checking**

```

uv run ruff check . --fix --show-fixes

uv run mypy

```

5. **Verify Tests Again**

```

uv run py.test

```

6. **Final Commit**

Make a final commit with any linting/typing fixes.

### Python Code Standards

#### Docstring Guidelines

For `src/**/*.py` files, follow these docstring guidelines:

1. **Use reStructuredText format** for all docstrings.

```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

"""

```

2. **Keep the main description on the first line** after the opening `"""`.

3. **Use NumPy docstyle** for parameter and return value documentation.

#### Doctest Guidelines

For doctests in `src/**/*.py` files:

1. **Use narrative descriptions** for test sections rather than inline comments:

```python

"""Example function.

Examples

--------

Create an instance:

>>> obj = ExampleClass()

Verify a property:

>>> obj.property

'expected value'

"""

```

2. **Move complex examples** to dedicated test files at `tests/examples/<path_to_module>/test_<example>.py` if they require elaborate setup or multiple steps.

3. **Utilize pytest fixtures** via `doctest_namespace` for more complex test scenarios:

```python

"""Example with fixture.

Examples

--------

>>> # doctest_namespace contains all pytest fixtures from conftest.py

>>> example_fixture = getfixture('example_fixture')

>>> example_fixture.method()

'expected result'

"""

```

4. **Keep doctests simple and focused** on demonstrating usage rather than comprehensive testing.

5. **Add blank lines between test sections** for improved readability.

6. **Test your doctests continuously** using pytest-watcher during development:

```

# Watch specific modules for doctest changes

uv run ptw . --now --doctest-modules src/path/to/module.py

```

#### Pytest Testing Guidelines

1. **Use existing fixtures over mocks**:

- 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

2. **Preferred pytest patterns**:

- Use `tmp_path` (pathlib.Path) fixture over Python's `tempfile`

- Use `monkeypatch` fixture over `unittest.mock`

#### Import Guidelines

1. **Prefer namespace imports**:

- Import modules and access attributes through the namespace instead of importing specific symbols

- Example: 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

2. **Standard aliases**:

- For `typing` module, use `import typing as t`

- Access typing elements via the namespace: `t.NamedTuple`, `t.TypedDict`, etc.

- Note primitive types like unions can be done via `|` pipes and primitive types like list and dict can be done via `list` and `dict` directly.

3. **Benefits of namespace imports**:

- Improves code readability by making the source of symbols clear

- Reduces potential naming conflicts

- Makes import statements more maintainable

## Git Commit Standards

### 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

```

### Component Patterns

#### General Code Changes

```

Component/File(feat[method]): Add feature

Component/File(fix[method]): Fix bug

Component/File(refactor[method]): Code restructure

```

#### Packages and Dependencies

| Language | Standard Packages | Dev Packages | Extras / Sub-packages |

|------------|------------------------------------|-------------------------------|-----------------------------------------------|

| General | `lang(deps):` | `lang(deps[dev]):` | |

| Python | `py(deps):` | `py(deps[dev]):` | `py(deps[extra]):` |

| JavaScript | `js(deps):` | `js(deps[dev]):` | `js(deps[subpackage]):`, `js(deps[dev{subpackage}]):` |

##### Examples

- `py(deps[dev]): Update pytest to v8.1`

- `js(deps[ui-components]): Upgrade Button component package`

- `js(deps[dev{linting}]): Add ESLint plugin`

#### Documentation Changes

Prefix with `docs:`

```

docs(Component/File[Subcomponent/method]): Update API usage guide

```

#### Test Changes

Prefix with `tests:`

```

tests(Component/File[Subcomponent/method]): Add edge case tests

```

### Commit Types Summary

- **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

### 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:`

- Use `See also:` to provide external references

### Good Commit Example

```

Pane(feat[capture_pane]): Add screenshot capture support

why: Provide visual debugging capability

what:

- Implement capturePane method with image export

- Integrate with existing Pane component logic

- Document usage in Pane README

refs: #485

See also: https://example.com/docs/pane-capture

```

### Bad Commit Example

```

fixed stuff and improved some functions

```

## Avoiding 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]

````

## LLM-Optimized Markdown Content Guidelines

When creating or editing markdown files within notes directories, adhere to the following guidelines:

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.

For more information on the `llms.txt` standard, refer to the official documentation: https://llmstxt.org/