# Evolution: coder

Project-specific rules accumulated from evolution findings in this project.
These overlay (add to) the coder's base instructions — they never contradict them.

---

## 2026-03-03: Docstring completeness is part of done

**Type:** code-quality-error
**What happened:** New public functions and classes were committed without meaningful docstrings. The user had to ask explicitly before a documentation fix was made.
**Root cause:** The acceptance self-review checklist covered tests and coverage but not code-level documentation.
**Lesson:** Before marking any new public function, class, or enum as done: verify it has a docstring explaining what it does, its key parameters/return values, and any non-obvious behavior (exit codes, side effects, fallback logic). A one-liner that restates the name is insufficient. Apply this check as part of the pre-commit self-review.

---

## 2026-03-03: Mock-only TUI tests leave focus, navigation, and interaction behavior untested

**Type:** test-quality-error
**What happened:** The TUI app launched with focus on the wrong widget — an internal tab strip instead of the primary interactive widget. Every existing TUI test passed. The bug had been present from the first TUI commit and was only discovered by a user running the app manually.
**Root cause:** All TUI tests were unit-level mocks. Mock-based tests never trigger the framework's mount lifecycle, so initial focus, post-mount widget state, and keyboard routing are never established and never observable in those tests.
**Lesson:** TUI Pilot tests MUST cover: (1) which widget holds focus on launch, (2) keyboard navigation between focusable widgets, (3) primary interactive actions (selection, toggle, confirmation). These behaviors are invisible to mock-based tests and require tests that mount the real application via the framework's test runner. A TUI feature is not done until all three are covered by real lifecycle tests, not just mocks.
