diff --git a/.github/workflows/skill-apply-optimize.yml b/.github/workflows/skill-apply-optimize.yml new file mode 100644 index 0000000..d32d8d8 --- /dev/null +++ b/.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' diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml new file mode 100644 index 0000000..84ab000 --- /dev/null +++ b/.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 }} diff --git a/skill/tdd/SKILL.md b/skill/tdd/SKILL.md index 9cc161e..5180589 100644 --- a/skill/tdd/SKILL.md +++ b/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 + +``` -- 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 + +``` + +**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 + +``` + +**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 |