refactor(brainstorm-with-docs): понимание ведёт, артефакт — запись

- Зачем:
  - гравитация скилла тянула к «выдать артефакт»; управляющие документы
    раздувались деталями реализации (диагностировано на живом тесте — ADR
    с инлайном SQL).
- Что:
  - gate/stop: «готово» = общее понимание + рекомендованное направление,
    записанное минимально-достаточно, а не «артефакт произведён»; определение
    в одном месте (stop_condition), gate на него ссылается.
  - core_rules: минимально-достаточный артефакт + барьер высоты (без инлайна
    исполняемых артефактов) + single source of truth; приоритет над
    конвенциями репозитория.
  - шаг 2: артефакт(ы) выбираются ПОСЛЕ понимания, набором по жанрам.
  - adr.md/spec.md: Lifetime test → Scope test (ADR↔spec по охвату, не сроку);
    detailed plan — transient и вне scope скилла.
  - description + README: формулировки-цели ведут пониманием, не артефактом.
- Проверка:
  - grep: старый framing (lifetime/transient) убран; cross-ref Scope test
    сходится; определение «готово» не дублируется; витрина не artifact-first.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dmitry DementievandClaude Opus 4.8 committed 2026-06-08 18:56:30 +03:00
1 parent 14adf77424
commit 6f9de57b0c
4 files changed
+48 -22

No files matched your search

@@ -18,11 +18,15 @@ If any of the three is missing, skip it. Easy to reverse → you'll just reverse
it. Not surprising → nobody will wonder. No real alternative → nothing to record
beyond "we did the obvious thing". Do not create an ADR for every small choice.
**Lifetime test (ADR vs spec).** A spec is transient — it describes what's being
built now and goes stale once the work is done. An ADR is durable — it outlives
the spec. So record a decision in an ADR only when it stays relevant *after* the
spec that introduced it is obsolete. Decisions local to the current work belong
in the spec's "Decisions and rejected alternatives" section, not here.
**Scope test (ADR vs spec).** Both an ADR and a spec are durable records, so the
split isn't lifetime — it's scope. A spec captures the shape of *one piece of
work* (what we're building and why); an ADR captures a single decision that is
*cross-cutting* — it matters beyond that one piece of work, and a future reader
elsewhere will need its rationale. So record a decision in an ADR only when it
applies beyond the scope of the spec that introduced it. Decisions local to the
current work belong in the spec's "Decisions and rejected alternatives" section,
not here. (The transient, stale-able document is the detailed implementation
plan — a separate artifact, not produced by this skill.)
## Template
@@ -3,8 +3,9 @@
Use for engineering, architecture, DevOps, integration, migration, or any
non-product feature work where a direction has been chosen but not yet built.
Use the smallest version that preserves the useful thinking. Drop sections that
add nothing for this particular problem — an empty section is noise.
Use the minimum-sufficient version: the smallest form that fully preserves the
understanding, and no smaller. Drop sections that add nothing for this particular
problem — an empty section is noise.
## Template
@@ -57,8 +58,9 @@ in the second.
Do not turn this section into an ADR dump. Keep decisions that are local to this
work here; promote a decision to its own ADR (`artifacts/adr.md`) only when it is
durable, surprising, the result of a real trade-off, and will still matter after
this spec is obsolete (see the lifetime test in `artifacts/adr.md`).
durable, surprising, the result of a real trade-off, and matters beyond the scope
of this work — cross-cutting, relevant to readers elsewhere (see the scope test
in `artifacts/adr.md`).
**Validation** describes how we will know the implementation is correct — tests,
checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.