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
@@ -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>
|
||||
|
||||
|
||||
Reference in new issue
Block a user