From 79dddcbad437dd8e28739297cd330740e7b6906d Mon Sep 17 00:00:00 2001 From: stepan_romankov Date: Thu, 21 May 2026 11:32:55 +0200 Subject: [PATCH] docs(skill): add "keep related scenarios in one tree" guidance When one scenario mutates state another reads back (grant -> read-shows-present vs. revoke -> read-shows-absent), consolidate into a single RunWith tree instead of fragmenting one-file-per-action. Independent features still get their own files. Wording chosen via A/B eval (5 configs x 3 prompts): all four candidate wordings produced the correct one-tree consolidation and none over-merged independent features; the decision-first phrasing won as the leanest (100 words) while opening with the exact question the reader must answer. Co-Authored-By: Claude Opus 4.7 --- cmd/claude-setup/skill/SKILL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cmd/claude-setup/skill/SKILL.md b/cmd/claude-setup/skill/SKILL.md index f3c6143..e898777 100644 --- a/cmd/claude-setup/skill/SKILL.md +++ b/cmd/claude-setup/skill/SKILL.md @@ -30,6 +30,12 @@ For samurai test files, top-to-bottom: Rationale: tests on top so the file's contract is visible immediately; setup stays local when it has a single caller, and graduates to a helper when it doesn't; helpers are appendix. +### Keep related scenarios in one tree + +Decision test: does one scenario's mutation produce the state another scenario reads back? If yes, they belong in the same file and the same `RunWith` tree — the shared mutation is the parent, the divergent read-backs are the leaves (grant → "read shows present" vs. revoke → "read shows absent"). This is the branching state-mutating tree samurai exists for. + +Splitting such scenarios one-file-per-action duplicates the setup and the context type and hides the grant/revoke/read-back relationship behind file boundaries. Independent features — where no scenario observes another's mutation — still get their own files. + ## When to Use USE samurai when ALL of these hold: