added lessons learned

Author: DinisCruz

docs/dev-briefs/v0.32.1__improve-test-coverage/v0.32.1__lessons-learned__improve-test-coverage.md

@@ -0,0 +1,126 @@
+# Lessons Learned: Improve Test Coverage
+
+**Version**: v0.32.1
+**Date**: January 2025
+**Related Brief**: `v0.32.1__dev-brief__improve-test-coverage.md`
+**Related Debrief**: `v0.32.1__debrief__improve-test-coverage.md`
+
+---
+
+## User Guidance Received During Session
+
+This document captures the specific guidance and corrections provided by the developer during the test coverage improvement session. These patterns should be followed in future sessions.
+
+---
+
+## 1. Bug Documentation Convention
+
+### Guidance Received
+
+When discovering bugs during testing:
+
+**a) Naming Convention**: Add `__bug__` to the test method name
+
+```python
+# Instead of:
+def test__enhance_with_signature__type_safe_detection(self):
+
+# Use:
+def test__bug__enhance_with_signature__type_safe_detection(self):
+```
+
+**b) Comment Format**: Prefix bug comments with `todo:` for IDE visibility
+
+```python
+# Instead of:
+# Note: The actual _enhance_with_signature has a bug where...
+assert endpoint.request_schema is None  # BUG: stays None
+
+# Use:
+# todo: BUG: The actual _enhance_with_signature tries to set request_schema
+#       to a string but schema expects Type. Exception is silently caught.
+assert endpoint.request_schema is None  # todo: BUG: stays None due to type mismatch
+```
+
+**Reason**: The `todo:` prefix makes bugs visible in PyCharm's TODO panel, making them easier to track and fix later.
+
+---
+
+## 2. Import Organization
+
+### Guidance Received
+
+Never add imports inline within test methods. Always add them at the module level with correct alignment.
+
+```python
+# Instead of:
+def test__enhance_with_signature__with_path_param_update(self):
+    with self.extractor as _:
+        from osbot_fast_api.client.schemas.enums.Enum__Param__Location import Enum__Param__Location
+        # ... test code
+
+# Use:
+from osbot_fast_api.client.schemas.enums.Enum__Param__Location import Enum__Param__Location
+
+def test__enhance_with_signature__with_path_param_update(self):
+    with self.extractor as _:
+        # ... test code
+```
+
+**Reason**: Keeps imports organized and consistent with project conventions. Imports should be alphabetically sorted and aligned.
+
+---
+
+## 3. Document Separation
+
+### Guidance Received (from Session 1)
+
+Keep the original dev-brief document unchanged as a historical record of the plan. Create a separate debrief document to track progress and capture what was actually done.
+
+**Document Structure**:
+- `v0.32.1__dev-brief__*.md` - Original plan (immutable after creation)
+- `v0.32.1__debrief__*.md` - Progress tracking, stats, session log
+- `v0.32.1__lessons-learned__*.md` - Guidance received, patterns learned
+
+**Reason**: Preserves the original intent and allows comparison between planned vs actual work.
+
+---
+
+## 4. Type_Safe Testing Patterns
+
+### From Project Guidance Documents
+
+The project has specific testing conventions documented in `docs/llm-briefs/type_safety/`:
+
+**Context Manager Pattern**:
+```python
+def test_something(self):
+    with SomeClass() as _:
+        assert _.field == expected_value
+```
+
+**Inline Comments (Not Docstrings)**:
+```python
+def test_something(self):                    # Brief description of test
+    with SomeClass() as _:
+        result = _.method()                  # explain what this does
+        assert result == expected            # explain the assertion
+```
+
+**Method Naming**:
+```
+test__<method_name>__<scenario>
+```
+
+---
+
+## Summary of Key Patterns
+
+| Pattern | Convention |
+|---------|------------|
+| Bug tests | Prefix with `test__bug__` |
+| Bug comments | Use `# todo: BUG:` prefix |
+| Imports | Module level only, aligned |
+| Dev docs | Separate brief/debrief/lessons |
+| Folder names | Don't hardcode, be flexible |
+| Test style | Context manager with `_`, inline comments |