Repository navigation
docs(playbooks): add leading words, the no-op test and the context-boundary line to the authoring guidance #8645
Copy link
Copy link
Labels
agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.Fully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.Triaged, unblocked, and fully specified; eligible to pick up.
Description
Refs: #7582
Agent Brief
Type: Task
Summary: Carry "leading words" into the skill criteria's Body section and give /docs-hygiene:write-for-agents a leading-words section, a sentence-level no-op test and the line that hiding later steps only works across a real context boundary. All additions; no cut.
Current behavior:
plugins/docs-hygiene/skills/write-for-agents/SKILL.md:129-132("Prompt the positive") has one clause: "pretrained leading words are the compact anchors that steer". Nothing tells an author to look for them, and nothing about them reaches skill bodies: the criteria's## Bodysection (plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md:67) does not mention them.- write-for-agents has no test for a sentence that changes nothing, and its "Give every step a completion criterion" section (
SKILL.md:95) does not say when hiding later steps works. - Comparing two wordings is supported:
/evals:plugin-evalcompares runs with--baseline <before.json> --margin <m>.
Desired behavior:
skill-criteria.md## Body: one bullet. Choose leading words on purpose: prefer a term the model already holds (TDD, tautological, tracer bullet, a loop that goes red) over a spelled-out description; keep a chosen term only when a with-and-without comparison (/evals:plugin-eval --baseline) shows it moves behavior. Point at write-for-agents for the doctrine instead of restating it.- write-for-agents, new section "Leading words": a leading word is a compact concept the model already holds from pretraining, repeated as a token, never re-explained, so it anchors a region of behavior in few tokens. Prefer an existing word to a coined one; a coined word must be defined and recruits no prior. Look for triads spelled out at several sites and pointers spending a sentence on one idea: each is a candidate to collapse into one word.
- write-for-agents, the no-op test, sentence by sentence: an instruction the model already follows by default spends load and says nothing. Whether it changes behavior is settled by running the document, not by debate. A sentence that fails is deleted whole. A word too weak to beat the default is a no-op too; the fix is a stronger word.
- write-for-agents, in the completion-criterion section: hiding later steps from the agent works only across a real context boundary (a hand-off or a subagent dispatch); an inline call leaves the later steps in context.
- One eval case for write-for-agents: given a draft rule with a spelled-out triad and a sentence the model already obeys by default, the output proposes one leading word and deletes the no-op sentence whole.
- No existing sentence is removed from either file.
Key interfaces:
plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md## Body.plugins/docs-hygiene/skills/write-for-agents/SKILL.md.
Acceptance criteria:
- The diff adds the Body bullet, the "Leading words" section, the no-op test and the context-boundary line, and deletes no line in either file.
-
plugins/skill-quality/scripts/check-evals-quality.sh plugins/docs-hygiene/skills/write-for-agents/evals/evals.jsonexits 0, with the new case asserting the behavior named. -
scripts/check-changelog-fragments.sh --checkpasses, with onepatchfragment each forplaybooksanddocs-hygiene, naming Matt Pocock'swriting-for-agentsas the source. - CI's
check-skillspasses on the PR (a PR check; this run does not run it).
Out of scope:
- The description standard, check 3 and check 12 (B2's two-attempt slice), the router-under-5k rule, the hand-off phrasing eval, trims and consolidations: they wait for skill-quality: skill authoring, quality and catalog #7582's own sub-plan (B7) and its probes.
- The
docs/upstream/mattpocock-skills.mdrow. - Editing either skill's description.
Origin:
- Leading words in the criteria with a
--baselinecomparison; write-for-agents leading-words section, sentence-level no-op test, context-boundary line: Matt's, D4, Q525.
Do not run with: none open.
Slice of #7582, drafted by the poteto-review session from the thread's recorded decisions.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.Fully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.Triaged, unblocked, and fully specified; eligible to pick up.
Type
Fields
No fields configured for Task.
Activity