improve tdd skill structure

.github/workflows/skill-apply-optimize.yml

@@ -0,0 +1,19 @@
+name: Apply Skill Optimization
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  apply:
+    if: >-
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/apply-optimize')
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review-and-optimize@d81583861aaf29d1da7f10e6539efef4e27b0dd5
+        with:
+          mode: 'apply'

.github/workflows/skill-review.yml

@@ -0,0 +1,17 @@
+name: Skill Review & Optimize
+on:
+  pull_request:
+    paths: ['**/SKILL.md']
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review-and-optimize@d81583861aaf29d1da7f10e6539efef4e27b0dd5
+        with:
+          optimize: 'true'
+          tessl-token: ${{ secrets.TESSL_API_TOKEN }}

skill/tdd/SKILL.md

@@ -1,44 +1,90 @@
 ---
 name: tdd
-description: Apply Test-Driven Development workflow for new features and bugfixes.
+description: >
+  Apply Test-Driven Development workflow for new features, bugfixes, and refactors.
+  Write failing tests first, implement minimal code to pass, then refactor.
+  Use when the user asks to add a feature, fix a bug, write tests, ensure test coverage,
+  do red-green-refactor, or follow TDD practices.
 ---
 
 # TDD Protocol
 
-## Core Principle
+Write tests first, then implement. Every feature or bugfix starts with a failing test.
 
-- **TDD First**: Test-Driven Development is the default approach.
-- **Goal**: Prioritize behavioral correctness and regression safety over formal compliance.
+## Process
 
-## Workflow
+### 1. Requirement synthesis
 
-1. **Requirement Synthesis**: Briefly summarize the requirements before coding.
-2. **Test Specification**: Write tests describing the expected behavior (unit, integration, or E2E).
-3. **Implementation**: Update the logic only to the extent required to satisfy those tests.
+Summarize the expected behavior in 1-3 bullet points before writing any code or tests.
 
-## Mandatory Rules
+**Verify:** confirm understanding with the user if requirements are ambiguous.
 
-- **No Test, No Code**: Every new feature or bugfix must include relevant test coverage.
-- **Black-Box Testing**: Validate observable behavior, not internal implementation details.
-- **Merge Requirement**: Tests are mandatory for completion unless an explicit exception is documented.
+### 2. Write failing tests (Red)
 
-## Preferred Practice
+Write tests that describe the expected behavior. Choose the right test level:
 
-- **Red-Green-Refactor**: Start with a failing test whenever practical.
-- **Right-Sized Testing**:
-  - **Unit Tests**: For pure logic and isolated functions.
-  - **Integration Tests**: For system interactions and API boundaries.
-  - **E2E Tests**: For critical user journeys and "happy paths."
+| Level | When to use | Examples |
+|---|---|---|
+| Unit | Pure logic, isolated functions, data transformations | Validators, parsers, calculators |
+| Integration | System interactions, API boundaries, DB queries | Service layers, API endpoints, repositories |
+| E2E | Critical user journeys, full-stack flows | Login flow, checkout, onboarding |
 
-## Explicit Exceptions (Must be justified)
+```bash
+# Run the new tests to confirm they fail
+<test-runner> <test-file>
+```
 
-- Pure refactoring (where behavior remains identical).
-- Exploratory spikes or R&D.
-- UI/Styling iterations where unit tests offer diminishing returns.
-- Complex integrations where mocking is counterproductive.
-- Emergency hotfixes (requires a follow-up ticket for test debt).
+**Verify:** tests must fail for the right reason (missing implementation, not syntax errors or misconfiguration). If tests error instead of fail, fix the test setup first.
 
-## Quality Bar
+### 3. Implement (Green)
 
-- **Readability**: Tests must serve as documentation for the feature.
-- **Reliability**: Tests must be deterministic (no flakes) and decoupled from implementation internals.
+Write the minimum code required to make all failing tests pass. Do not add behavior beyond what tests require.
+
+```bash
+# Run tests again to confirm they pass
+<test-runner> <test-file>
+```
+
+**Verify:** all new tests pass. If any test fails, fix the implementation (not the test) unless the test itself has a bug.
+
+### 4. Refactor
+
+Improve code quality while keeping all tests green. Run the full test suite after refactoring.
+
+```bash
+# Run full suite to catch regressions
+<test-runner>
+```
+
+**Verify:** no regressions. If a test breaks during refactor, revert the refactor step and retry with a smaller change.
+
+## Test quality rules
+
+| Rule | Rationale |
+|---|---|
+| Test observable behavior, not internals | Survives refactoring without test changes |
+| Each test has a single assertion focus | Clear failure messages, easier debugging |
+| Tests must be deterministic | No flakes, no time/order dependencies |
+| Tests serve as documentation | A new developer should understand the feature from tests alone |
+| Use descriptive test names | Name should describe the scenario and expected outcome |
+
+## Error recovery
+
+| Problem | Action |
+|---|---|
+| Tests fail for wrong reason (import error, config) | Fix test infrastructure first, then re-run |
+| Cannot determine correct test level | Default to unit tests; escalate to integration only when mocking becomes excessive |
+| Existing tests break after implementation | Check if existing tests encode wrong behavior; if correct, fix implementation |
+| Test runner not found or not configured | Check project for `package.json` scripts, `Makefile`, `pytest.ini`, or similar; ask user if unclear |
+| Flaky test detected | Isolate non-determinism (time, network, concurrency); mock or pin the source |
+
+## Exceptions
+
+These scenarios may skip the test-first step. Each requires explicit justification:
+
+| Exception | Required follow-up |
+|---|---|
+| Pure refactoring (identical behavior) | Run existing test suite to confirm no regressions |
+| Exploratory spike / R&D | Create a follow-up ticket for test coverage |
+| UI/styling changes with low test ROI | Verify manually; document what was checked |
+| Emergency hotfix | Create a follow-up ticket for test debt within 24h |