diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md index 3c13444..3a045c8 100644 --- a/agents/.agents/skills/brainstorm-with-docs/SKILL.md +++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md @@ -244,7 +244,9 @@ 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. React by the level of what you find. Text-level defects — wording, +author — a **hot review**: the reviewer carries the author's full context, +which makes it cheap, and shares the author's blind spots, which is its limit. +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 @@ -300,6 +302,8 @@ user explicitly asks to implement. Offer a small set of next actions, such as: * create or update an ADR * update `CONTEXT.md` * create a runbook +* hand the artifact to a **cold review** — a fresh session or agent with no + shared context — where the stakes warrant an independent eye * derive a compact implementation checklist * start implementation (only on explicit request)