docs(skills): плейбук — структурный рефакторинг: ось вкуса, брифы, два Опус-агента

Зачем.
Отдельный осознанный заход, закрывающий открытые вопросы 2026-07-26 и
2026-07-31: две ручки выбора (модель, эффорт) были про силу, вкус ими не
выражался; константы линий дрейфовали через перепечатку; правила
координации прогона #18 жили только в журнале; у Agent-тула нет ручки
effort — карта была нереализуема разовым вызовом.

Что.
- Третья ось выбора — вкус: references/model-matrix.md (матрица Тео с
  поправкой пользователя под gpt-5.6-sol/Opus 5); разрез по подзадачам
  на этапе 1, сначала вкусовая часть.
- «Родословная» разведена на семейство (классы находок) и свежесть
  (независимость); линия дефектов — по различию, уместности — по умению.
- Ступень эффорта выбирается выбором агента: определений столько,
  сколько пар (модель, ступень) — deep-reasoner (high), craftsman
  (medium, исполнение брифов: реализация/ревью/перепроверки; поглотил
  adversarial-reviewer), fast-worker; карта с обоснованиями — SSOT в
  claude-agents.md.
- Константы — файлами в prompts/: line-task/code/rev, self-review;
  line-taste — вкусовая линза с 12 запахами Фаулера из /code-review.
- Правила #18 — в механизм: инкрементальная запись индекса, глубина
  один и проверка среды в мандате, признак жизни / другой путь вердикта
  замене / среда своими глазами в «Сбоях», стенд одной линии, stdin фона.
- lessons дистиллирован (586→533), handoff захода — в handoffs/.

Проверка.
Слепое ревью Опусом по writing-great-skills: CHANGES_REQUIRED
(7 MAJOR, 17 MINOR, 3 NIT) — все закрыты или отклонены с доводом в
lessons; ссылки пакета проверены скриптом, битых нет. Боевой прогон
новой структуры — следующим заходом (чек-лист в handoff).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Dmitry DementievandClaude Fable 5 committed 2026-07-31 17:03:23 +03:00
1 parent 6070810c2d
commit 3e0498e242
12 files changed
+466 -259

No files matched your search

@@ -0,0 +1,3 @@
## Your line
FINDING PREFIX: CODE
Lens: correctness, invariants, regressions, security, test honesty.
@@ -0,0 +1,5 @@
## Your line
FINDING PREFIX: REV
Lens: correctness, invariants, regressions, security, test honesty; plus
compliance with the statement, acceptance criteria, boundaries, intended
observable result.
@@ -0,0 +1,4 @@
## Your line
FINDING PREFIX: TASK
Lens: compliance with the statement, acceptance criteria, boundaries,
intended observable result.
@@ -0,0 +1,38 @@
## Taste
Formally correct but substantively wrong is a finding: work out of
proportion to the task, an added artifact that does not earn its
existence, a check that passes without proving its own claim. Grade a
taste finding by the cost of living with the code, not by whether it
breaks a test.
Match the changes against this smell baseline (Fowler, _Refactoring_,
ch. 3). Two rules bind it: a documented repo standard overrides the
baseline, and every smell is a judgement call to label ("possible
Feature Envy"), never a hard violation. Skip anything tooling already
enforces.
- **Mysterious Name** — the name hides what it does or holds → rename;
if no honest name comes, the design is murky.
- **Duplicated Code** — the same logic shape in more than one place →
extract the shared shape, call it from both.
- **Feature Envy** — a method works another object's data more than its
own → move it onto the data it envies.
- **Data Clumps** — the same few fields or params keep travelling
together → bundle them into one type, pass that.
- **Primitive Obsession** — a primitive or string stands in for a domain
concept → give the concept its own small type.
- **Repeated Switches** — the same type-dispatch cascade recurs across
the change → polymorphism, or one map both sites share.
- **Shotgun Surgery** — one logical change forces scattered edits across
many files → gather what changes together into one module.
- **Divergent Change** — one module edited for several unrelated reasons
→ split so each part changes for one reason.
- **Speculative Generality** — abstraction, parameters, or hooks for
needs the spec does not have → delete; inline until a real need shows.
- **Message Chains** — long `a.b().c().d()` navigation the caller should
not depend on → hide the walk behind one method on the first object.
- **Middle Man** — a unit that mostly delegates onward → cut it, call
the real target direct.
- **Refused Bequest** — an implementer ignores or overrides most of what
it inherits → drop the inheritance, use composition.
@@ -5,6 +5,11 @@
allowed and encouraged; safe empirical checks in temp dirs outside the
repo make a verdict much firmer than reading alone.
- No `git add` / `git commit` / `git checkout`.
- Work alone, depth one: no subagents, no delegating parts of the review.
- Leave the environment as you found it; if you stop or restart services,
verify the restoration actually took effect (e.g. `docker compose ps
-a`) — a trap that should have restored state is not evidence that it
did.
- Output only the findings index and the VERDICT line — no code retelling,
no narrative. Where to put it: your call wrapper says, or it is your
`-o` report if you were invoked via stdin.
@@ -12,7 +17,7 @@
## Findings file format — index only
One line per finding, with a stable ID (FINDING PREFIX comes from your
parameter block):
line block):
PREFIX-N | BLOCKER|MAJOR|MINOR|NIT | file:line (or spec/task-file section) | one-phrase essence | how to verify/reproduce
@@ -0,0 +1,4 @@
Now switch roles: you are a reviewer of your own diff. Walk it against
the task's acceptance criteria and boundaries. Fix what you find, stay
inside the task scope. Return one line: SELF-REVIEW: found N, fixed N —
plus one phrase per unfixed item, if any.