Initial commit

skills/python-test-strategy/reference/coverage.md

@@ -0,0 +1,54 @@
+# Code Coverage Configuration
+
+## Goals
+
+- **Target**: 95%+ coverage for all implementation files
+- Prevents untested code paths
+- Detects breaking changes early
+
+## Configuration File
+
+`.coveragerc` at project root controls coverage:
+
+```ini
+[report]
+exclude_lines =
+    pragma: no cover
+    if __name__ == .__main__.:
+    raise NotImplementedError
+
+omit =
+    */tests/*
+    */venv/*
+```
+
+## Running Coverage
+
+```bash
+# Individual module with coverage report
+.venv/bin/python tests/subpackage/test_module.py
+
+# Entire package
+.venv/bin/python tests/subpackage/all.py
+
+# All tests
+.venv/bin/python tests/all.py
+```
+
+Output: HTML report in `htmlcov/` showing covered/uncovered lines.
+
+## Marking Code as Non-Testable
+
+Use `# pragma: no cover` for untestable code:
+
+```python
+if sys.platform == "win32":  # pragma: no cover
+    return "windows"
+```
+
+Use for:
+- Platform-specific code
+- Emergency fallbacks
+- Code that shouldn't occur in normal operation
+
+Don't use for regular logic or error handling.

skills/python-test-strategy/reference/naming.md

@@ -0,0 +1,45 @@
+# Test File Naming & Organization
+
+## Convention
+
+Test files mirror source directory structure with consistent naming:
+
+```
+Source: <project>/<subpackage>/<module>.py
+Test:   tests/<subpackage>/test_<subpackage>_<module>.py
+```
+
+## Examples
+
+| Source | Test |
+|--------|------|
+| `learn_haystack/math/calculator.py` | `tests/math/test_math_calculator.py` |
+| `learn_haystack/math/ops/add.py` | `tests/math/ops/test_math_ops_add.py` |
+| `learn_haystack/utils.py` | `tests/test_utils.py` |
+
+## Finding Test Location
+
+Use the script to determine correct test path:
+```bash
+python scripts/locate_test_file.py /absolute/path/to/source.py
+```
+
+## Directory Structure
+
+Test directories mirror source packages:
+```
+learn_haystack/          tests/
+├── math/        →      ├── math/
+│   └── ops/     →      │   └── ops/
+└── utils.py     →      └── test_utils.py
+
+tests/math/all.py       # Run all tests in math package
+tests/math/ops/all.py   # Run all tests in ops subpackage
+tests/all.py            # Run all project tests
+```
+
+## Why This Pattern
+
+- Unique names prevent collisions across packages
+- Directory mirroring makes tests easy to find
+- Full path in filename supports tooling (IDE jumps, auto-generation)

skills/python-test-strategy/reference/public-api.md

@@ -0,0 +1,57 @@
+# Public API Testing
+
+## API Module
+
+Create `api.py` that exports all public interfaces (one import per line):
+
+```python
+# project/api.py
+from .math.operations import add_numbers
+from .math.operations import subtract_numbers
+from .utils.helpers import format_output
+from .core.engine import create_engine
+```
+
+One import per line makes changes clear in diffs and easier to maintain.
+
+## Test Public API
+
+Test file at `tests/test_api.py` verifies all exports are accessible:
+
+```python
+from project import api
+
+def test_api():
+    """Verify all public APIs are importable."""
+    _ = api.add_numbers
+    _ = api.subtract_numbers
+    _ = api.format_output
+    _ = api.create_engine
+```
+
+## Purpose
+
+- Catch accidental removal of public exports
+- Prevent breaking changes to API
+- Document what users can import
+- Fail tests if API changes unexpectedly
+
+## Best Practices
+
+1. **Export only stable APIs** - Functions and classes that are unlikely to change
+2. **Keep minimal** - Don't export internal utilities
+3. **Document** - Add docstring to `api.py` explaining what's exported
+4. **Group logically** - Organize imports by functional area
+
+## Deprecation
+
+Mark deprecated APIs before removal:
+
+```python
+import warnings
+
+def old_function():
+    """Deprecated: Use new_function() instead."""
+    warnings.warn("Use new_function instead", DeprecationWarning, stacklevel=2)
+    return new_function()
+```