OpeItcLoc03/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(tdd-criteria): review findings — v0.1.0→v0.2.0

Browse Source 
- Remove session-authorship trigger loophole (applies to ALL code changes)
- Add composite-tasks paragraph (criterion applies per artefact, not per task)
- Add refactoring carve-out (existing passing tests sufficient, no new tests)
- Expand file-extension list (go, rs, java, rb, ex, swift, kt, cs, php)
- Clarify wrapper line-count (non-blank non-comment lines)
- Add spike-survivor fallback (TODO/GitHub issue if no .tasks/)
- Fix "чужая schema" → "foreign schema" in algorithm + design doc
- Define TDD procedurally (red→green→refactor) in Default mode section
- Sync design doc with same changes
- Rebuild dist + dist-hermes + reinstall

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
vitya
2026-05-07 10:12:17 +03:00
parent e260fe6cb1
commit 94b4c441e6
6 changed files with 46 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
.tasks/STATUS.md
View File

@@ -1,5 +1,5 @@
# Task Board
_Updated: 2026-05-07 (board cleanup: 4 stale → done, hermes-converter-ci unblocked; active: none)_
_Updated: 2026-05-07 (tdd-criteria-review done → v0.2.0)_
<!--
Canonical layout. One block per task. Per-task deep context lives in
@@ -468,37 +468,13 @@ Both layers are needed. Either alone leaves a path-of-least-resistance route to
---
## ⚪ [tdd-criteria-review] — Code-review checkpoint для брейнсторма `tdd-criteria` (промоушен 2026-05-07).
## 🟢 [tdd-criteria-review] — Code-review checkpoint для брейнсторма `tdd-criteria` (промоушен 2026-05-07).
**Спецификация:** `~/projects/claude-skills/.wiki/concepts/tdd-criteria-design.md` (промоушен в commit `a03d280`).
**Импл-таски (review против их acceptance criteria):** `tdd-criteria-skill-write`, `tdd-criteria-hermes-mapping`, `tdd-criteria-build-install`.
**Кто делает:** **не имплементер.** Следующая сессия в `claude-skills` (другая модель / другой день / другой агент) поднимает таску с чистым контекстом. «Я только что это написал» bias = главный риск; brainstorm проводился в `.meeting-room`, импл — в `claude-skills`, ревьюер — третья сессия.
**Чек-лист ревью:**
1. **Прочитать спецификацию** (`.wiki/concepts/tdd-criteria-design.md`) — особенно секции «Decision algorithm», «Ironclad rules», «Permissive — accepted-risk zones», «Anti-loophole».
2. **Открыть `skills/tdd-criteria/SKILL.md`** и проверить:
- Frontmatter имеет `name: tdd-criteria`, `version: 0.1.0`, multi-line `description:` с триггер-фразами включающими «TDD», «test-driven», «skip-tdd», «следуй TDD».
- Все 4 Ironclad-правила и все 4 Permissive carve-outs присутствуют.
- Ведущий «Why this exists» аргумент — про anti-vandalism / contract-vs-artefact, не «good practice».
- **Нет** Claude-tool-refs в body (`Read`, `Edit`, `Glob`, `Bash`, `WebFetch`). `grep -E '(\\bRead\\b|\\bEdit\\b|\\bGlob\\b|\\bBash\\b)' SKILL.md` должно вернуть 0 хитов в content (frontmatter description допускает упоминание trigger-phrases).
- Длина ≤200 строк. Если больше — флаг.
3. **Открыть `hermes/mapping.yaml`** — entry `tdd-criteria: { mode: auto, category: software-development }`, **без** `replace-rules`. Если есть replace-rules — это значит SKILL.md имеет Claude-specific refs, что нарушает design.
4. **Verify build artefacts**: `dist/tdd-criteria.skill` существует и не пустой; `dist-hermes/software-development/tdd-criteria/SKILL.md` существует и совпадает с источником (для `mode: auto` без replace-rules — byte-identical).
5. **Verify install**: `~/.claude/skills/tdd-criteria/SKILL.md` существует, совпадает с источником.
6. **Smoke**: в новой Claude-сессии задать вопрос вида «нужны ли мне тесты для CSS-файла?» — skill `tdd-criteria` должен подцепиться по description, ответить «нет, [skip-tdd: visual]», без рассуждений «зависит от».
7. **Sanity-check на anti-vandalism rationale**: спросить себя «если бы я был агентом без этого скила и видел "messy code" — у меня есть signal не удалять?». Если SKILL.md формулирует только classical 4 аргумента (bug fix / pure logic / contract / security) — это значит ведущий argument потерялся при адаптации из design в SKILL. Это finding высокого приоритета.
**Findings → новые follow-up tasks** через `mcp__projects-meta__tasks_create` с slug-format `tdd-criteria-<gap>-fix` (например `tdd-criteria-trigger-phrase-fix`, `tdd-criteria-rationale-restore-fix`).
**Закрытие:** только когда (а) все findings зафайлены отдельными tasks, ИЛИ (б) ревьюер подтвердил «нет findings» в close-note (с явным «прошёл по 7 пунктам checklist-а»).
**Status:** ready
**Where I stopped:** unblocked — skill-write, mapping, build-install all shipped
**Next action:** Открыть свежую сессию в `claude-skills` (НЕ в `.meeting-room` и НЕ ту, в которой импл делался). Пройти 7-пунктный чек-лист в description. Findings — отдельные `tdd-criteria-*-fix` tasks. Закрыть с close-note.
**Status:** done
**Where I stopped:** Review complete. 7-point checklist passed. 4 findings applied directly as v0.2.0 (trigger-loophole fix, composite-tasks + refactoring sections, file-extension expansion, wrapper line-count clarification, spike-survivor .tasks/ fallback, foreign-schema fix). 3 minor items deferred as wontfix (retroactivity marker — negligible risk; spike-survivor already has fallback; refactoring is now documented). SKILL.md 0.1.0→0.2.0, design doc amended, rebuilt + reinstalled + hermes rebuilt.
**Next action:** (none — kept until merged)
**Branch:** master
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: .meeting-room / 2026-05-07T04:03:12.170Z -->
<!-- created-by: OpeItcLoc03@DESKTOP-NSESKTOP-NSEF0UK / from: claude-skills / 2026-05-07 -->
---

12
.wiki/concepts/tdd-criteria-design.md
View File

@@ -4,7 +4,7 @@ source: .meeting-room/.archive/2026-05-07-tdd-criteria.md
status: promoted
type: design
title: tdd-criteria-design
amended: "2026-05-07: added test-immutability defence (Anti-loophole rule 4) after user noted symmetric vandalism risk on tests"
amended: "2026-05-07: added test-immutability defence (Anti-loophole rule 4) after user noted symmetric vandalism risk on tests; 2026-05-07 v0.2.0 review: removed session-authorship trigger loophole, added composite-tasks/refactoring sections, expanded file-extension list, clarified wrapper line-count"
ingested_at: '2026-05-07T04:01:23.616Z'
ingested_by: OpeItcLoc03@DESKTOP-NSEF0UK
source_project: .meeting-room
@@ -55,7 +55,7 @@ Walk through 8 questions top-to-bottom. First «yes» determines mode. All «no
```
1. Это исправление бага? → TDD (red-test первым)
2. Это код, потребляющий внешний контракт → TDD (contract-test)
(SDK, REST API, чужая schema)?
(SDK, REST API, foreign schema)?
3. Это security / auth / money / identifiers? → TDD
4. Это pure logic — функция (input → output) → TDD
без I/O, без global state, bounded inputs?
@@ -73,6 +73,10 @@ Walk through 8 questions top-to-bottom. First «yes» determines mode. All «no
(default) → TDD
```
**Composite tasks.** A task that doesn't fit one category is composite — break it down per artefact type. The criterion applies per artefact, not per task.
**Refactoring.** Restructuring existing code without changing observable behaviour, where existing tests already cover it, does not require new tests. If the refactoring introduces new behaviour, that part is a separate artefact subject to the decision algorithm.
## Ironclad — why TDD is cheaper than skipping
| # | Rule | Checkable property | Why TDD here |
@@ -93,7 +97,7 @@ Not «TDD doesn't apply». **«You accept that an agent can vandalise this witho
| 5 | Visual / config | CSS, layout, design tokens, `.env.example`, prompts, wiki, README | `[skip-tdd: visual]` | Eyeball on next render. Visual regression infra exists (Playwright screenshots, Percy) but heavyweight for most projects. |
| 6 | Spike | Explicit POC «throwaway» in commit/PR/task subject | `[skip-tdd: spike]` | Throwaway by contract — deletion isn't a problem. **Survivor rule**: if spike code reaches master, the same merge-commit creates `[backfill-tests-<slug>]` task. Otherwise this category becomes the loophole. |
| 7 | One-shot | Migrations, ETL backfill, ad-hoc cleanup; runs once | `[skip-tdd: oneshot]` | Test never re-executes — cost not recovered. After run, deletion is irrelevant. |
| 8 | Wrapper | ≤10 lines, no branching (re-export, glue) | `[skip-tdd: wrapper]` | Test on `function foo(x) { return bar(x) }` re-states `bar`. Reconstruct cost ≈ delete cost. The defence is on `bar`, not `foo`. |
| 8 | Wrapper | ≤10 non-blank non-comment lines, no branching (re-export, glue) | `[skip-tdd: wrapper]` | Test on `function foo(x) { return bar(x) }` re-states `bar`. Reconstruct cost ≈ delete cost. The defence is on `bar`, not `foo`. |
## Anti-loophole
@@ -149,7 +153,7 @@ Example: «add a user-profile-settings page»:
- Validation form (email format, password strength) → Ironclad-4 (security) → TDD
- API call wrapper for save → Ironclad-3 (third-party contract if PUT to external endpoint) → TDD
- Update Pinia store reducer → Ironclad-2 (pure logic if bounded reducer) → TDD
- Hook `useProfileForm` composing the above → wrapper if ≤10 lines glue, else Ironclad-2
- Hook `useProfileForm` composing the above → wrapper if ≤10 non-blank non-comment lines glue, else Ironclad-2
One «task» yields 4-5 commits with different modes. **The criterion applies per artefact, not per task.** This is the point — no «overall this is exploratory».

2
.wiki/log.md
View File

@@ -53,3 +53,5 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
## [2026-05-06] ingest | concepts/hermes-skills-rollout-design
## [2026-05-07] ingest | concepts/tdd-criteria-design
## [2026-05-07] review | tdd-criteria v0.2.0 — 4 findings applied: trigger-loophole fix (removed session-authorship clause), composite-tasks + refactoring sections, expanded file-extension list, clarified wrapper line-count + spike-survivor fallback + foreign-schema fix; design doc synced

27
dist-hermes/software-development/tdd-criteria/SKILL.md
View File

@@ -1,13 +1,12 @@
---
name: tdd-criteria
version: 0.1.0
version: 0.2.0
description: >
TDD by default with four bright-line carve-outs. Applies before any code
change the agent didn't author this session. Triggers: "TDD",
"test-driven", "следуй TDD", "use TDD", "should I write tests",
"skip tdd", "[skip-tdd: ...]", "[test-modify: ...]", "tdd-criteria".
Cross-agent policy — no tool refs. Full rationale:
.wiki/concepts/tdd-criteria-design.md
change. Triggers: "TDD", "test-driven", "следуй TDD", "use TDD",
"should I write tests", "skip tdd", "[skip-tdd: ...]",
"[test-modify: ...]", "tdd-criteria". Cross-agent policy — no tool refs.
Full rationale: .wiki/concepts/tdd-criteria-design.md
---
# tdd-criteria
@@ -18,29 +17,33 @@ description: >
**At session start** — when `CLAUDE.md` contains the line `follow tdd-criteria`.
**Before any code change** the agent didn't author this session — touching a `*.ts`, `*.js`, `*.py`, or similar source file triggers the decision algorithm below.
**Before any code change** — touching a `*.ts`, `*.js`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.rb`, `*.ex`, `*.swift`, `*.kt`, `*.cs`, `*.php`, or similar source file triggers the decision algorithm below.
**On explicit reference** — when the user says "TDD", "test-driven", "следуй TDD", "use TDD", "should I write tests", "skip tdd", "tdd-criteria", or includes `[skip-tdd: ...]` or `[test-modify: ...]` in a commit subject.
## Default mode
TDD by default. Skip only if one of four bright-line carve-outs matches and is marked in the commit subject.
TDD by default: write a failing test first, then write the minimum code to make it pass, then refactor. Skip only if one of four bright-line carve-outs matches and is marked in the commit subject.
## Decision algorithm (8 questions, top-down)
Walk through in order. First «yes» determines mode. All «no» → TDD by default.
1. **Bug fix?** → TDD (red-test first)
2. **Consuming external contract** (SDK, REST API, чужая schema)? → TDD (contract-test)
2. **Consuming external contract** (SDK, REST API, foreign schema)? → TDD (contract-test)
3. **Security / auth / money / identifiers?** → TDD
4. **Pure logic** — function (input → output) without I/O, global state, bounded inputs? → TDD
5. **Visual / config** — CSS, layout, design tokens, `.env.example`, prompts, wiki, README? → SKIP, `[skip-tdd: visual]`
6. **Spike** — explicit POC «throwaway» in commit/PR/task subject? → SKIP, `[skip-tdd: spike]` + spike-survivor task if code survives
7. **One-shot** — migration, ETL backfill, ad-hoc cleanup, runs once? → SKIP, `[skip-tdd: oneshot]`
8. **Transit wrapper** ≤10 lines — no branching, re-export / glue? → SKIP, `[skip-tdd: wrapper]`
8. **Transit wrapper** ≤10 non-blank non-comment lines — no branching, re-export / glue? → SKIP, `[skip-tdd: wrapper]`
(default) → TDD
**Composite tasks.** A task that doesn't fit one category is composite — break it down per artefact type. The criterion applies per artefact, not per task. Example: a settings page = CSS layout `[skip-tdd: visual]` + validation logic `[TDD]` + API wrapper `[TDD]`.
**Refactoring** — restructuring code without changing observable behaviour, with existing tests covering it — does not require new tests. Existing tests must still pass. If refactoring introduces new behaviour, that part is subject to the decision algorithm as a separate artefact.
## Ironclad rules (TDD obligatory)
1. **Bug fix** — if there's an issue / failure log / repro, write a red-test codifying the repro. Marginal cost: 5 min. Marginal benefit: regression test forever.
@@ -57,14 +60,14 @@ In all four, recovery cost from silent deletion is high. The test is the only ar
| 5 | Visual / config | CSS, layout, tokens, `.env.example`, prompts, wiki | `[skip-tdd: visual]` |
| 6 | Spike | «POC, throwaway» in commit/PR/task subject | `[skip-tdd: spike]` |
| 7 | One-shot | Migration, ETL, ad-hoc cleanup; runs once | `[skip-tdd: oneshot]` |
| 8 | Wrapper | ≤10 lines, no branching, re-export / glue | `[skip-tdd: wrapper]` |
| 8 | Wrapper | ≤10 non-blank non-comment lines, no branching, re-export / glue | `[skip-tdd: wrapper]` |
These are **accepted-risk zones** — you accept that an agent can vandalise without immediate signal, because recovery is cheap (eyeball next render; throwaway by contract; runs once; reconstruct ≤ delete).
## Anti-loophole
1. **Skip without category is invalid.** One of four explicit categories required — not «other reasons». No marker = violation.
2. **Spike survivor rule.** Merged spike → same merge-commit creates `[backfill-tests-<slug>]` task. Otherwise «spike» becomes «skipped tests forever».
2. **Spike survivor rule.** Merged spike → same merge-commit creates `[backfill-tests-<slug>]` task (in `.tasks/` if available, otherwise a TODO comment or GitHub issue). Otherwise «spike» becomes «skipped tests forever».
3. **Friction is the point.** `[skip-tdd: visual]` 50× in a design-system rework is irritating — that's the fence. Re-evaluate after ≥2 weeks, not before.
4. **Tests are append-only by default.** Modifying an assertion, deleting a test, or disabling it (`it.skip`/`xit`/`@pytest.mark.skip`/`@Disabled`) requires:
- **Marker in commit subject:** `[test-modify: <test-name>: was <X>; is <Y>; reason: <Z>]` — `<X>` and `<Y>` are **literal assertion expressions**, not paraphrased. Example: `[test-modify: validates email: was expect(isValid("a@b")).toBe(true); is expect(isValid("a@b.com")).toBe(true); reason: tightened spec to require TLD]`

BIN
dist/tdd-criteria.skill vendored
View File

Binary file not shown.

27
skills/tdd-criteria/SKILL.md
View File

@@ -1,13 +1,12 @@
---
name: tdd-criteria
version: 0.1.0
version: 0.2.0
description: >
TDD by default with four bright-line carve-outs. Applies before any code
change the agent didn't author this session. Triggers: "TDD",
"test-driven", "следуй TDD", "use TDD", "should I write tests",
"skip tdd", "[skip-tdd: ...]", "[test-modify: ...]", "tdd-criteria".
Cross-agent policy — no tool refs. Full rationale:
.wiki/concepts/tdd-criteria-design.md
change. Triggers: "TDD", "test-driven", "следуй TDD", "use TDD",
"should I write tests", "skip tdd", "[skip-tdd: ...]",
"[test-modify: ...]", "tdd-criteria". Cross-agent policy — no tool refs.
Full rationale: .wiki/concepts/tdd-criteria-design.md
---
# tdd-criteria
@@ -18,29 +17,33 @@ description: >
**At session start** — when `CLAUDE.md` contains the line `follow tdd-criteria`.
**Before any code change** the agent didn't author this session — touching a `*.ts`, `*.js`, `*.py`, or similar source file triggers the decision algorithm below.
**Before any code change** — touching a `*.ts`, `*.js`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.rb`, `*.ex`, `*.swift`, `*.kt`, `*.cs`, `*.php`, or similar source file triggers the decision algorithm below.
**On explicit reference** — when the user says "TDD", "test-driven", "следуй TDD", "use TDD", "should I write tests", "skip tdd", "tdd-criteria", or includes `[skip-tdd: ...]` or `[test-modify: ...]` in a commit subject.
## Default mode
TDD by default. Skip only if one of four bright-line carve-outs matches and is marked in the commit subject.
TDD by default: write a failing test first, then write the minimum code to make it pass, then refactor. Skip only if one of four bright-line carve-outs matches and is marked in the commit subject.
## Decision algorithm (8 questions, top-down)
Walk through in order. First «yes» determines mode. All «no» → TDD by default.
1. **Bug fix?** → TDD (red-test first)
2. **Consuming external contract** (SDK, REST API, чужая schema)? → TDD (contract-test)
2. **Consuming external contract** (SDK, REST API, foreign schema)? → TDD (contract-test)
3. **Security / auth / money / identifiers?** → TDD
4. **Pure logic** — function (input → output) without I/O, global state, bounded inputs? → TDD
5. **Visual / config** — CSS, layout, design tokens, `.env.example`, prompts, wiki, README? → SKIP, `[skip-tdd: visual]`
6. **Spike** — explicit POC «throwaway» in commit/PR/task subject? → SKIP, `[skip-tdd: spike]` + spike-survivor task if code survives
7. **One-shot** — migration, ETL backfill, ad-hoc cleanup, runs once? → SKIP, `[skip-tdd: oneshot]`
8. **Transit wrapper** ≤10 lines — no branching, re-export / glue? → SKIP, `[skip-tdd: wrapper]`
8. **Transit wrapper** ≤10 non-blank non-comment lines — no branching, re-export / glue? → SKIP, `[skip-tdd: wrapper]`
(default) → TDD
**Composite tasks.** A task that doesn't fit one category is composite — break it down per artefact type. The criterion applies per artefact, not per task. Example: a settings page = CSS layout `[skip-tdd: visual]` + validation logic `[TDD]` + API wrapper `[TDD]`.
**Refactoring** — restructuring code without changing observable behaviour, with existing tests covering it — does not require new tests. Existing tests must still pass. If refactoring introduces new behaviour, that part is subject to the decision algorithm as a separate artefact.
## Ironclad rules (TDD obligatory)
1. **Bug fix** — if there's an issue / failure log / repro, write a red-test codifying the repro. Marginal cost: 5 min. Marginal benefit: regression test forever.
@@ -57,14 +60,14 @@ In all four, recovery cost from silent deletion is high. The test is the only ar
| 5 | Visual / config | CSS, layout, tokens, `.env.example`, prompts, wiki | `[skip-tdd: visual]` |
| 6 | Spike | «POC, throwaway» in commit/PR/task subject | `[skip-tdd: spike]` |
| 7 | One-shot | Migration, ETL, ad-hoc cleanup; runs once | `[skip-tdd: oneshot]` |
| 8 | Wrapper | ≤10 lines, no branching, re-export / glue | `[skip-tdd: wrapper]` |
| 8 | Wrapper | ≤10 non-blank non-comment lines, no branching, re-export / glue | `[skip-tdd: wrapper]` |
These are **accepted-risk zones** — you accept that an agent can vandalise without immediate signal, because recovery is cheap (eyeball next render; throwaway by contract; runs once; reconstruct ≤ delete).
## Anti-loophole
1. **Skip without category is invalid.** One of four explicit categories required — not «other reasons». No marker = violation.
2. **Spike survivor rule.** Merged spike → same merge-commit creates `[backfill-tests-<slug>]` task. Otherwise «spike» becomes «skipped tests forever».
2. **Spike survivor rule.** Merged spike → same merge-commit creates `[backfill-tests-<slug>]` task (in `.tasks/` if available, otherwise a TODO comment or GitHub issue). Otherwise «spike» becomes «skipped tests forever».
3. **Friction is the point.** `[skip-tdd: visual]` 50× in a design-system rework is irritating — that's the fence. Re-evaluate after ≥2 weeks, not before.
4. **Tests are append-only by default.** Modifying an assertion, deleting a test, or disabling it (`it.skip`/`xit`/`@pytest.mark.skip`/`@Disabled`) requires:
- **Marker in commit subject:** `[test-modify: <test-name>: was <X>; is <Y>; reason: <Z>]` — `<X>` and `<Y>` are **literal assertion expressions**, not paraphrased. Example: `[test-modify: validates email: was expect(isValid("a@b")).toBe(true); is expect(isValid("a@b.com")).toBe(true); reason: tightened spec to require TLD]`