From 9ce4c6f769c0c4ae1f778d7f870df74ab6d80ff5 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Sat, 1 Aug 2026 19:12:59 +0300 Subject: [PATCH] =?UTF-8?q?docs(skills):=20brainstorm-with-docs=20?= =?UTF-8?q?=E2=80=94=20=D0=BF=D0=B5=D1=80=D0=B5=D1=87=D0=B8=D1=82=D1=8B?= =?UTF-8?q?=D0=B2=D0=B0=D0=BD=D0=B8=D0=B5=20=D1=80=D0=B5=D0=B0=D0=B3=D0=B8?= =?UTF-8?q?=D1=80=D1=83=D0=B5=D1=82=20=D0=BF=D0=BE=20=D1=83=D1=80=D0=BE?= =?UTF-8?q?=D0=B2=D0=BD=D1=8E=20=D0=BD=D0=B0=D1=85=D0=BE=D0=B4=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Текстовые огрехи горячее ревью правит молча по месту; находку уровня решений (противоречие, дыра в охвате) предъявляет владельцу, не исправляя и не замалчивая. Довод владельца: текстовые находки видны и неопасны, а противоречия при перечитывании не раз оказывались важными — плоский запрет переоткрывать решения заставлял бы молчать или чинить мимо владельца. Co-Authored-By: Claude Opus 5 --- .../.agents/skills/brainstorm-with-docs/ROADMAP.md | 13 ++++++++++--- agents/.agents/skills/brainstorm-with-docs/SKILL.md | 11 +++++++---- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md index b7275b0..89cf6bc 100644 --- a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md +++ b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md @@ -156,9 +156,16 @@ shaped by three inputs: Landed shape — two tiers: `` runs at step 6 on the plan (can send the run back to the interview; no file exists yet), step 7 writes the file once -directly, then re-reads it end-to-end as a reader and fixes text-level defects -in place (does not reopen decisions). Unlike upstream, the review itself is -kept — `to-spec` has none; ours has content worth keeping. +directly, then re-reads it end-to-end as a reader. Unlike upstream, the review +itself is kept — `to-spec` has none; ours has content worth keeping. + +Follow-up (same day): the re-read's reaction now splits by the level of the +find. Text-level — fix in place, silently. Decision-level (contradiction with +docs or between sections, coverage hole, unhandled scenario) — present to the +user, neither silently fixed nor suppressed. Owner's evidence: text-level finds +are visible and harmless, but contradictions caught on re-read have mattered +more than once; a flat "don't reopen decisions" ban would force the agent to +either suppress such a find or fix it past the owner. ## v2 — remaining diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md index cdf6ea5..3c13444 100644 --- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md +++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md @@ -244,10 +244,13 @@ Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in as part of step 6 rather than guessing. Create directories lazily. After writing, re-read the written file end-to-end as its reader, not its -author, and fix what you find in place — wording, structure drift, sections -that disagree with each other, template mismatches. This pass is cheap and -regularly catches real defects; it polishes text, it does not reopen decisions -(those passed `` at step 6). +author. React by the level of what you find. Text-level defects — wording, +structure drift, template mismatches — fix in place, silently. A +decision-level find — a contradiction with existing docs or between the +artifact's own sections, a hole in coverage, an unhandled scenario — present +to the user instead: neither fix it silently nor suppress it. Reopening a +decision is the user's call. This re-read is cheap and regularly catches both +kinds. Then go to ``.