[coder-xieshijie]

What changes

• explain-as-fool: lead with one sentence and one concrete scenario, most important point first. A first explanation of a problem or a fix covers what the problem is, when it happens, what it causes and how the fix resolves it. A decision states what is decided, the options, the recommendation and what happens otherwise.
• agent-prompt-rules §1:
  • 1.2: the report keeps what was observed apart from what is inferred, and names what is not verified, in a line rather than as caveats throughout.
  • 1.3: where the dispatcher knows the answer is likely to be, or which source to try when one comes up empty, it says so: that is context only it has, not a method.
  • 1.5: for a kind of decision that will come up again, hand over the criterion and what to assume when no one can be asked; the executor reports the assumptions it made.
• docs/basis.md: section 8 names the general principles underneath the rules (first principles, Occam's razor, separation of concerns, a single source of truth, most important first, reversible and irreversible decisions, feedback control, independent verification, limited attention) and where each shows.

Basis (agent-prompt-rules §4)

Change	Gap it fills	Source
1.2 observed vs inferred, not verified	Reports state inferences as findings; the reader cannot tell what to check	Fable 5 · Ground progress claims during long runs; Prompting best practices · Research and information gathering
1.3 where to look	Executors search where the context is not, and come back to ask	Multi-agent research system · Prompt engineering ("guidance on the tools and sources to use"; "context that only exists in Slack")
1.5 criterion for recurring decisions	Each instance of the same decision comes back to the user	Multi-agent research system · Prompt engineering ("heuristics rather than rigid rules"); Fable 5.1 · Finish the whole task (already cited: "state the assumption you made")
explain-as-fool	172 bare invocations in two months of the author's sessions; a reader stuck on a fix had to restate "what is the problem, when does it happen, what does it cause, how does the fix solve it"	The author's own template; not a vendor rule (explain-as-fool is not a prompt for agents)

The cited passages were added verbatim to the excerpt files.

Before and after

Fresh claude -p --bare sessions, no tools, the Skill version appended to the system prompt as the invoked Skill, model claude-opus-5-5, 3 runs per version per case. A separate session scored the replies blind (versions shuffled and relabeled) against a fixed rubric.

Case	Criterion	Before	After
explain: a fix proposal the reader did not follow	first sentence states the point	0/3	3/3
	states the decision asked of the reader, with a recommendation and the other choice	0–1/3	3/3
explain: a migration-number decision	what to decide, options, recommendation, consequence	3/3 each	3/3 each
explain: "why fix it this way, isn't it the model's fault?"	gives one concrete scenario	0/3	3/3
	opening answers the question	2/3	2–3/3
prompt rules: brief for fixing 12 flaky tests	asks the report to separate observed from inferred and name what is not verified	0/3	3/3
	criterion for which to fix, default when no one can be asked, where the evidence is	3/3 each	3/3 each
prompt rules: brief for a bug with a feedback id / logs / reproduce order	asks for observed vs inferred and what is not verified	0/3	3/3
	criterion for when to fix and when to only report	2/3	3/3

Not shown by the runs: a rule to answer only the part a follow-up asks about scored 0/3 in every version, so it was dropped. The source order and the decision criterion were already passed on by the old rules when the request stated them; the change makes them explicit for briefs where the dispatcher has to supply them itself. Replies are about 10–20% longer in the explain cases with a fix proposal and shorter in the decision case.

Checks

node scripts/check-links.mjs, node skills/agent-prompt-rules/scripts/check-links.mjs, node --test skills/agent-prompt-rules/scripts/check-links.test.mjs: pass.