Skip to content

docs(playbooks): add leading words, the no-op test and the context-boundary line to the authoring guidance #8645

Closed

Description

@kyle-sexton

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 ## Body section (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-eval compares 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.json exits 0, with the new case asserting the behavior named.
  • scripts/check-changelog-fragments.sh --check passes, with one patch fragment each for playbooks and docs-hygiene, naming Matt Pocock's writing-for-agents as the source.
  • CI's check-skills passes 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.md row.
  • Editing either skill's description.

Origin:

  • Leading words in the criteria with a --baseline comparison; 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions