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:
1 parent
50640d8cb5
commit
f24b342123
4 files changed
+37
-10
No files matched your search
@@ -18,6 +18,12 @@ 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.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -40,6 +40,13 @@ add nothing for this particular problem — an empty section is noise.
|
||||
|
||||
## Notes on key sections
|
||||
|
||||
**Options considered vs Decisions.** Keep these two sections doing different jobs
|
||||
so the rejected options aren't written twice. *Options considered* is the
|
||||
landscape *before* the choice — the candidates and their trade-offs as they
|
||||
stood. *Decisions and rejected alternatives* is the outcome *after* the choice —
|
||||
what was picked and why each alternative was rejected. Frame in the first, judge
|
||||
in the second.
|
||||
|
||||
**Decisions and rejected alternatives** is the highest-value section. Capture:
|
||||
|
||||
- accepted decisions and the reason behind each
|
||||
@@ -48,9 +55,10 @@ add nothing for this particular problem — an empty section is noise.
|
||||
- sequencing decisions
|
||||
- assumptions future agents must not silently re-derive
|
||||
|
||||
Do not turn this section into an ADR dump. Promote a decision to its own ADR
|
||||
(`artifacts/adr.md`) only when it is durable, surprising, and the result of a
|
||||
real trade-off.
|
||||
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`).
|
||||
|
||||
**Validation** describes how we will know the implementation is correct — tests,
|
||||
checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.
|
||||
Reference in new issue
Block a user