docs(brainstorm-with-docs): уточнены границы артефактов по внешнему ревью

- Зачем:
  - внешнее ревью выявило риск двойной записи решений (spec/ADR) и
    терминологическую путаницу; правки документные, поведение не меняют.
- Что:
  - adr.md и spec.md: добавлен lifetime-критерий ADR vs spec (ADR — для
    решений, переживающих спеку; локальные остаются в спеке).
  - spec.md: разведены Options considered (до выбора) и Decisions (после).
  - SKILL.md: блок <validation> переименован в <self_review>, чтобы не
    путать с секцией ## Validation в spec.md.
  - README.md: честнее описано авто-срабатывание на Codex.
  - SKILL.md: у SEAM зафиксирован TODO(F1) про строку дивергенции
    (отложена ради чистого baseline на обкатке).
- Проверка:
  - python3 yaml-парс frontmatter; нет висячих ссылок на <validation>.
This commit is contained in:
ddadmin committed 2026-06-02 23:43:09 +03:00
1 parent 50640d8cb5
commit f24b342123
4 files changed
+37 -10

No files matched your search

@@ -143,9 +143,16 @@ in [artifacts/context.md](artifacts/context.md) — don't batch them.
## 5. Synthesize options
<!-- SEAM: v2 will prepend a divergence phase (idea-generation toolkit +
"at least one option the user didn't already imply") before this
convergence step. Keep this step self-contained so it can be split. -->
<!-- SEAM / TODO(v2): prepend a divergence phase before this convergence step.
Full version = idea-generation toolkit (axis of variation, archetype
stances, inversion, steal-from-adjacent-domain, cost-shifting, pre-mortem,
constraint relaxation, null option).
TODO(F1): cheap pre-step — add one <core_rule>: "among the options, at least
one must be something the user did not already imply." Deliberately deferred
now to keep the v1 live-test baseline clean (we want to see how badly pure
convergence collapses into variations of one idea). Reconsider landing this
single line right after the first live test, before the full toolkit.
Keep this step self-contained so it can be split. -->
Present 2-3 viable approaches. For each: short description, when it fits,
benefits, trade-offs, risks, operational implications, documentation impact, and
@@ -178,7 +185,7 @@ Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in
`docs/runbooks/`). If the location isn't obvious, propose a path and confirm it
as part of step 6 rather than guessing. Create directories lazily.
Then go to `<validation>` and `<stop_condition>`.
Then go to `<self_review>` and `<stop_condition>`.
</how_to_do_it>
@@ -198,7 +205,10 @@ runbook. If it's a validation rule for this work → the spec.
</shared_project_language>
<validation>
<self_review>
This is a review of the document itself — distinct from a spec's `## Validation`
section, which lists acceptance criteria for the implementation.
Before presenting the final artifact, review it for: unclear terms, missing
constraints, hidden assumptions, contradictions with existing docs, unnecessary
@@ -209,7 +219,7 @@ runbook, and context that does (or does not) belong in `CONTEXT.md`.
If it's too large, propose splitting it. If it's too vague, continue the
interview.
</validation>
</self_review>
<stop_condition>