diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 300f028..af30865 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -25,7 +25,7 @@ "repository": "https://github.com/rookslog/stylewright", "license": "MIT", "category": "writing", - "keywords": ["anti-slop", "de-slop", "compressed-deliberation", "navigable-references", "proportionate-execution", "concision", "agent-output", "style"] + "keywords": ["anti-slop", "de-slop", "compressed-deliberation", "navigable-references", "proportionate-execution", "subagent-returns", "concision", "agent-output", "style"] } ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index d4965ed..28c2fdc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,22 @@ and [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### Added +- The `subagent-returns` skill, in the craft tier. An agent whose reader is + another agent writes a return value, and the calling agent sees the final + message and no part of the run behind it. So the skill holds that message to + the caller: put every fact it needs there, fill the shape the caller asked + for, carry the data rather than the journey, say where each claim came from, + return a failure as a result, and size the message to the decision it serves. + It governs that message alone, because a file one agent leaves for another to + open is a channel where the premise does not hold. + Two rules refuse the trade the length rules could otherwise buy, because a + shorter return that drops a finding costs the caller more than it saves. The + skill came out of an operator request, so every prescription in it is an `E` + row, and the matrix carries no `G` row and no source version. No arm has + been run. A study of this skill needs a runner that can drive a delegation and + keep what came back, which is the gap `proportionate-execution` already + records for a session, and `source/craft/subagent-returns.md` says so. + - A verdict corpus, mined from this repository's own review threads, and the scorer support that reads it. This repository disposes of every review finding with a fenced `review-verdict` block, so it already holds a labelled corpus of diff --git a/README.md b/README.md index dfc6a4e..cbd523d 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ Install one tier, the other, or both. | `navigable-references` | craft | None. The rule is ours, and no measurement stands behind it yet. See `source/craft/navigable-references.md`. | Not applicable. Nothing is reproduced. | | `proportionate-execution` | craft | None. Anthropic documents the behaviours, and every rule answering them is ours. See `source/craft/proportionate-execution.md`. | No source wording is reproduced, so no reproduction right is relied on. See the same record. | | `de-slop` | craft | None. Every rule is ours, and no measurement stands behind it yet. See `source/craft/de-slop.md`. | Not applicable. Nothing is reproduced. | +| `subagent-returns` | craft | None. The skill came out of an operator request, and every rule is ours. See `source/craft/subagent-returns.md`. | Not applicable. Nothing is reproduced. | A craft skill has no standard behind it, so measurement is the only evidence its rules can have. `bench/` holds that protocol, and `bench/README.md` states the @@ -50,8 +51,9 @@ clean, which is how we learned the skill we were about to write would have been aimed at the wrong thing. That is the evidence a craft rule can have, and not the evidence each one -already has. `navigable-references` and `de-slop` ship with none, and each source record -says so in those words. Read both as discipline that we assert. +already has. `navigable-references`, `de-slop` and `subagent-returns` ship with +none, and each source record says so in those words. Read all three as +discipline that we assert. `de-slop` gives a shape to write toward, and names the departures from it. It governs rhetorical moves and never words. No skill here ships a list of @@ -66,6 +68,10 @@ ADR-0005 accepted that gap when it admitted operating discipline to this tier, so no rule in that skill claims a measured effect until the runner can drive a session. +`subagent-returns` sits behind the same wall. It governs the one message a +subagent returns to the agent that spawned it, so an arm has to drive a +delegation and keep what came back. The runner cannot do that either. + More skills are in progress. See `CONTRIBUTING.md` to add one. ## The resident fragment diff --git a/grounding/craft/subagent-returns.md b/grounding/craft/subagent-returns.md new file mode 100644 index 0000000..ed127a8 --- /dev/null +++ b/grounding/craft/subagent-returns.md @@ -0,0 +1,112 @@ +# Grounding: subagent-returns + +Disposes of every unit of content in `skills/craft/subagent-returns/SKILL.md`. + +- A **`G` row** traces to an external source. Its rule cell names the rule. +- An **`E` row** is our own editorial guidance. Its rule cell is empty. +- An **`N` row** is narrative. It orients the reader and asserts no rule, so it + claims no authority at all. Its rule cell is empty. + +The `Audited` cell of a `G` row says whether a person has read that row against +the source. The `Source text` cell carries the words of the rule it cites. +There is no `G` row here, so every cell in both columns is empty, and both are +waiting for the first row that cites anything. + +**Quotation:** forbidden. There is no source, so there is nothing to quote. The +source record at `source/craft/subagent-returns.md` states the same status. +Anyone who finds a source for a rule here records it and its licence there +first, and edits this line in the same pass. + +This file stays in the repository. It does not install with the skill. + +Checked by `stylewright ground --check --skill subagent-returns`. + +## There is no `G` row here + +The skill this file grades came out of an operator request and nothing else. No +standard, no vendor documentation, and no published guidance says any of it. +Every prescription below is therefore an `E` row, including the ones that read +as obvious. + +A vendor page reporting how much a model writes would not change that. Such a +page describes a model and prescribes nothing, which is the distinction +`grounding/craft/compressed-deliberation.md` records for the seven `G` rows it +does carry. A contributor who finds a real source for a rule here adds the +source record before adding the row. + +## Where the line between an `E` row and an `N` row falls here + +A sentence that directs the reader, or that judges the reader's return, is an +`E` row. A sentence about this skill itself, or about what stands behind it, is +an `N` row. + +Six of the headings are `E` rows, because each one carries the guidance of the +section under it rather than labelling it. `Carry the data, and not the journey` +instructs on its own, and `A failure is a result` asserts on its own. The five +label headings are `N`, and so is the title. + +`Purpose` carries one row of each kind. Its first paragraph says what the +channel is, and its second tells the reader which messages these rules leave +alone, which directs and therefore grades `E`. + +Doubt resolves to `E` here. An `E` row claims our own authority and an `N` row +claims none, so grading a directive as narrative retires it from review, which +is the defect `AGENTS.md` names. Grading a piece of scenery as guidance costs a +reviewer one reading. + +## No measurement stands behind these rows + +A craft rule can have only one kind of evidence, which is measurement. +`bench/README.md` in this repository holds that protocol. No arm has been run +for this skill. There is no control, no treatment, and no figure, so nothing +here may be read as an effect that we observed. + +The bench runner drives one prompt, and every rule here governs a message that +one agent returns to another. So a study of this skill needs a runner that can +drive a delegation, which is the gap `source/craft/proportionate-execution.md` +already records for a session. The source record at +`source/craft/subagent-returns.md` states the same status. + +| ID | Our guidance | Our anchor | Source rule | Source text | Source location | Audited | +|---|---|---|---|---|---|---| +| E-01 | The final message is the whole delivery | The final message is the whole delivery | | | Our own guidance, written as a section title | | +| E-02 | Put every fact the caller needs into the final message, because nothing else you wrote reaches it. | The final message is the whole delivery | | | Our own guidance | | +| E-03 | Point at a file the caller can open, rather than pasting the contents that file already holds. | The final message is the whole delivery | | | Our own guidance | | +| E-04 | Paste the text whose exact wording the caller must act on, and summarise the rest. | The final message is the whole delivery | | | Our own guidance, and it bounds E-03 | | +| E-05 | Fill the shape the caller asked for | Fill the shape the caller asked for | | | Our own guidance, written as a section title | | +| E-06 | Fill the return format the spawn prompt gave, field for field. | Fill the shape the caller asked for | | | Our own guidance | | +| E-07 | Add no section the caller did not ask for. | Fill the shape the caller asked for | | | Our own guidance | | +| E-08 | Answer a three-line question in three lines, under no heading. | Fill the shape the caller asked for | | | Our own guidance | | +| E-09 | Return the data itself where the caller named no shape, and do not invent a report around it. | Fill the shape the caller asked for | | | Our own guidance, and it covers the case the section leaves open | | +| E-10 | Carry the data, and not the journey | Carry the data, and not the journey | | | Our own guidance, written as a section title | | +| E-11 | Cut the restatement of the task, because the caller wrote it. | Carry the data, and not the journey | | | Our own guidance | | +| E-12 | Cut the account of the order you worked in, and return what you found. | Carry the data, and not the journey | | | Our own guidance | | +| E-13 | Cut the closing summary, because the caller has just read the message. | Carry the data, and not the journey | | | Our own guidance | | +| E-14 | Say where each claim came from | Say where each claim came from | | | Our own guidance, written as a section title | | +| E-15 | Mark a claim you inferred, in the clause that makes it. | Say where each claim came from | | | Our own guidance | | +| E-16 | State a count beside the command or the file it came from, in the same clause. | Say where each claim came from | | | Our own guidance | | +| E-17 | Report what a check reported, and never what you expect it to report. | Say where each claim came from | | | Our own guidance | | +| E-18 | State what you did not cover in one line, and where the caller's shape has no room for it, the shape wins. | Say where each claim came from | | | Our own guidance, and it settles which of E-06 and this rule gives way | | +| E-19 | A caller re-runs a measured claim cheaply and re-derives an inference expensively. A message that blurs the two moves that cost onto the caller. | Say where each claim came from | | | Our own guidance, and it judges a return that blurs the two | | +| E-20 | A failure is a result | A failure is a result | | | Our own guidance, written as a section title | | +| E-21 | Return a blocked run as data: what you attempted, what you observed, and the smallest thing that would let it continue. | A failure is a result | | | Our own guidance | | +| E-22 | Name a step you skipped, because silence about it reads as a step you took. | A failure is a result | | | Our own guidance | | +| E-23 | Leave the apology out, and let the failure state itself. | A failure is a result | | | Our own guidance | | +| E-24 | Length answers to the caller's decision | Length answers to the caller's decision | | | Our own guidance, written as a section title | | +| E-25 | Size the message to what the caller must decide, and not to the work it took. | Length answers to the caller's decision | | | Our own guidance | | +| E-26 | Cut a line the caller would not act on. | Length answers to the caller's decision | | | Our own guidance, and it is the one mechanical test here | | +| E-27 | Work you did buys no words. A long return is not a report on effort, and a caller reading one pays for every line of it. | Length answers to the caller's decision | | | Our own guidance, and it judges a return sized by effort | | +| E-28 | Do not drop a finding to make the return shorter. | What this skill does not ask for | | | Our own guidance, and it bounds E-25 and E-26 | | +| E-29 | Do not shorten a shape the caller asked for. | What this skill does not ask for | | | Our own guidance, and it bounds E-25 and E-26 | | +| E-30 | `de-slop` treats one passage of prose and `compressed-deliberation` treats one reply, and each writes for a person. `proportionate-execution` governs a whole session. This skill treats the one message a calling agent receives. Follow all four. They do not disagree. | How this differs from the other craft skills | | | Our own guidance, and it instructs the reader to follow all four | | +| E-31 | Read every rule here as discipline that we assert. Do not read any of it as an effect that we observed. | What stands behind these rules | | | Our own guidance, and it instructs the reader how to read the skill | | +| E-32 | Read these rules for that message alone. A file you leave for another agent to open is a different channel, and the rules below do not govern it. | Purpose | | | Our own guidance, and it bounds what the trigger admits | | +| N-01 | subagent-returns | subagent-returns | | | Section title, asserts no rule | | +| N-02 | Purpose | Purpose | | | Section title, asserts no rule | | +| N-03 | A calling agent reads the message you end on, and it reads nothing else you wrote. So that message is a return value the caller acts on, rather than a report a person reads at leisure. This skill holds it to what the caller needs. | Purpose | | | States what this skill treats and who reads it, asserts no rule | | +| N-04 | What this skill does not ask for | What this skill does not ask for | | | Section title, asserts no rule | | +| N-05 | How this differs from the other craft skills | How this differs from the other craft skills | | | Section title, asserts no rule | | +| N-06 | What stands behind these rules | What stands behind these rules | | | Section title, asserts no rule | | +| N-07 | Nothing measured. A craft rule has no standard behind it, so measurement is the only evidence it can ever have, and no arm has been run for this skill. | What stands behind these rules | | | States the evidence, asserts no rule | | +| N-08 | Boundary | Boundary | | | Section title, asserts no rule | | +| N-09 | This skill has no external standard behind it. Every rule in it is our own editorial guidance, and the trace marks the rest as narrative that asserts no rule. The trace lives in the stylewright repository at `grounding/craft/subagent-returns.md`. It is not installed with this skill. | Boundary | | | Describes the trace, asserts no rule | | diff --git a/skills/craft/subagent-returns/LICENSE b/skills/craft/subagent-returns/LICENSE new file mode 100644 index 0000000..a22a2da --- /dev/null +++ b/skills/craft/subagent-returns/LICENSE @@ -0,0 +1 @@ +MIT diff --git a/skills/craft/subagent-returns/SKILL.md b/skills/craft/subagent-returns/SKILL.md new file mode 100644 index 0000000..1833b3d --- /dev/null +++ b/skills/craft/subagent-returns/SKILL.md @@ -0,0 +1,85 @@ +--- +name: subagent-returns +description: Use when a calling agent reads the final message you return. Triggers are a subagent final message, a return to a calling agent, a delegation report, and an agent-to-agent handoff. Symptoms are a restated task, narrated process, a shape the caller never asked for, and a count with no stated source. +--- + +# subagent-returns + +## Purpose + +A calling agent reads the message you end on, and it reads nothing else you +wrote. So that message is a return value the caller acts on, rather than a +report a person reads at leisure. This skill holds it to what the caller needs. + +Read these rules for that message alone. A file you leave for another agent to +open is a different channel, and the rules below do not govern it. + +## The final message is the whole delivery + +- Put every fact the caller needs into the final message, because nothing else you wrote reaches it. +- Point at a file the caller can open, rather than pasting the contents that file already holds. +- Paste the text whose exact wording the caller must act on, and summarise the rest. + +## Fill the shape the caller asked for + +- Fill the return format the spawn prompt gave, field for field. +- Add no section the caller did not ask for. +- Answer a three-line question in three lines, under no heading. +- Return the data itself where the caller named no shape, and do not invent a report around it. + +## Carry the data, and not the journey + +- Cut the restatement of the task, because the caller wrote it. +- Cut the account of the order you worked in, and return what you found. +- Cut the closing summary, because the caller has just read the message. + +## Say where each claim came from + +- Mark a claim you inferred, in the clause that makes it. +- State a count beside the command or the file it came from, in the same clause. +- Report what a check reported, and never what you expect it to report. +- State what you did not cover in one line, and where the caller's shape has no room for it, the shape wins. + +A caller re-runs a measured claim cheaply and re-derives an inference +expensively. A message that blurs the two moves that cost onto the caller. + +## A failure is a result + +- Return a blocked run as data: what you attempted, what you observed, and the smallest thing that would let it continue. +- Name a step you skipped, because silence about it reads as a step you took. +- Leave the apology out, and let the failure state itself. + +## Length answers to the caller's decision + +- Size the message to what the caller must decide, and not to the work it took. +- Cut a line the caller would not act on. + +Work you did buys no words. A long return is not a report on effort, and a +caller reading one pays for every line of it. + +## What this skill does not ask for + +- Do not drop a finding to make the return shorter. +- Do not shorten a shape the caller asked for. + +## How this differs from the other craft skills + +`de-slop` treats one passage of prose and `compressed-deliberation` treats one +reply, and each writes for a person. `proportionate-execution` governs a whole +session. This skill treats the one message a calling agent receives. Follow all +four. They do not disagree. + +## What stands behind these rules + +Nothing measured. A craft rule has no standard behind it, so measurement is the +only evidence it can ever have, and no arm has been run for this skill. + +Read every rule here as discipline that we assert. Do not read any of it as an +effect that we observed. + +## Boundary + +This skill has no external standard behind it. Every rule in it is our own +editorial guidance, and the trace marks the rest as narrative that asserts no +rule. The trace lives in the stylewright repository at +`grounding/craft/subagent-returns.md`. It is not installed with this skill. diff --git a/skills/craft/subagent-returns/agents/openai.yaml b/skills/craft/subagent-returns/agents/openai.yaml new file mode 100644 index 0000000..ab93bba --- /dev/null +++ b/skills/craft/subagent-returns/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "subagent-returns" + short_description: "Use when another agent reads your output." + default_prompt: "Use $subagent-returns to check this document." diff --git a/source/craft/subagent-returns.md b/source/craft/subagent-returns.md new file mode 100644 index 0000000..1395cfd --- /dev/null +++ b/source/craft/subagent-returns.md @@ -0,0 +1,78 @@ +# Source record for subagent-returns + +This file stays in the repository. It does not install with the skill. + +This skill has no source. The record exists anyway, because the question a +reader asks of a craft skill is what stands behind its rules, and the answer +here has to be stated rather than left to be discovered. + +- Source: none. No standard, no vendor documentation, and no published guidance + says any of this. +- Rights holder: not applicable. Nothing is reproduced. +- Transformation: not applicable. Every rule is written from scratch, and the + grounding matrix carries no `G` row. +- Reproduction check: not required, because no source wording is carried into + the skill. Anyone who later adds a quotation must record the check here first. +- Recorded 2026-08-16. + +## Where the skill came from + +An operator asked for a skill that holds a subagent to a smaller return. The +request named the failure and not the rules, so every rule here is ours. + +The rules answer one property of the channel. A calling agent sees the final +message and no part of the run behind it, so a fact left out of that message is +a fact the caller never had. Nothing in this record establishes that property +as measured. It is how the harnesses this repository targets behave, and a +reader who finds one that behaves otherwise has found the limit of the skill. + +## What evidence stands behind the rules + +None that was measured. A craft rule has no standard behind it, so measurement +is the only evidence it can ever have, and `bench/README.md` in this repository +holds that protocol. No arm has been run for this skill. There is no control, +no treatment, and no figure to cite. + +Read every rule here as discipline that we assert. Do not read any of it as an +effect that we observed, and do not let a later summary of this skill say that +it works. + +## Where a measurement would live + +`bench/` in this repository, and it needs a runner that does not exist. Every +rule here governs a message one agent returns to another, so an arm has to spawn +a subagent and keep what it returned. The runner drives one prompt today, which +is the gap `source/craft/proportionate-execution.md` records for a session. + +1. Build a runner that spawns a subagent and retains the returned message. +2. Run the no-guidance control first, per the first rule in `bench/README.md`. +3. Run the same delegation with this skill injected, and keep both arms. +4. Score what the caller had to re-derive from each return, and read the samples. + +The scorer in `bench/score.mjs` has no metric for that. A study needs one +added, and the metric has to be tested against the control before anyone +trusts it. + +## What a shorter return costs + +A rule that cuts a return can cut a finding with it. `de-slop` records the +Anthropic report of an April 2026 brevity instruction that reduced coding +quality in Claude Code, and that report is the countertest here too. So the +skill sets no length, and two rules under `What this skill does not ask for` +refuse the trade outright. + +Nobody on this branch opened that report. `A6` in +`source/craft/compressed-deliberation.md` carries the URL, and no rule in this +skill cites it. + +## When this record expires + +Any of these makes the record stale, and it must be revised before the next +release: + +- Somebody runs the measurement above. The result replaces the section that + says there is none, whichever way the result goes. +- The bench runner learns to drive a delegation. The section above then states + a gap that has closed. +- A source turns up that supports one of these rules. A `G` row then needs the + usual record, and this file is where it goes.