Skip to content

#704 Give the lede pipeline authority to cut supplied mechanism #708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
williamthorsen merged 1 commit into from
Jun 1, 2026
Merged

#704 Give the lede pipeline authority to cut supplied mechanism #708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions packages/agents/content/skills/summarize-change/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,16 +36,16 @@ Check commit messages for additional context.
tier: {tier from step 5}
scope: {resolved scope, if available}
outcome: |
{What the reader will experience, do, or know differently — outcome-framed, not a diff enumeration. Derived from the substance composed in step 4.}
{What the reader will experience, do, or know differently — the mechanism-free reader-facing delta, not a diff enumeration and not a draft lede. Derived from the substance composed in step 4.}
context: |
{Optional supporting facts the subagent may need for accuracy.}
```

Lead with the outcome before naming files: `outcome` is the reader-facing delta the lede must carry; `context` is supplementary material the subagent may draw on for accuracy.
Lead with the outcome before naming files: `outcome` is the reader-facing delta the lede must carry, and it must be mechanism-free — state what changes for the reader, not how it was built. Do not pre-draft the lede here; implementation detail packed into `outcome` is laundering, and the subagent is required to cut it regardless. `context` is supplementary material the subagent may draw on for accuracy.

Use the subagent's returned text verbatim as the content of the `## What` section. Do not edit, prepend to, or append to it. The subagent owns voice; you own facts. If the subagent returns an error message (missing-field or similar), correct the dispatch inputs and retry.
Use the subagent's returned text as the content of the `## What` section. The subagent owns voice; you own the outcome. If the subagent returns an error message (missing-field or similar), correct the dispatch inputs and retry.

Verbatim governs voice ownership, not quality acceptance. If the returned text fails the doctrine — a banned identifier, a mechanism-shaped sentence, or generic puffery — correct the dispatch inputs (chiefly re-articulating `outcome`) and redispatch rather than shipping the failure. Correct the inputs and redispatch; do not hand-edit the subagent's output.
Verbatim governs voice ownership, not quality acceptance — and not a prohibition on pruning. You are the last reader before the lede ships, so you are permitted, and expected, to cut cruft you can see: a mechanism-shaped sentence, a banned identifier, generic puffery. This is a backstop, not your main role — the subagent is the party obligated to return a clean draft (see its mandate), so you should rarely have much to remove. Pruning is delete-only: strike the offending clause or sentence and leave the rest untouched. What you may not do is rewrite for voice or register; if the draft needs rephrasing rather than trimming, re-articulate `outcome` and redispatch rather than editing the prose yourself.

7. **Save** per the [Saving](#saving) section.

Expand All @@ -62,7 +62,7 @@ The body following the frontmatter has this structure:

## What

{Content returned by the `changelog-writer` dispatch in Process step 6. Use the returned text verbatim; do not edit, prepend, or append. If it fails the doctrine, correct the dispatch inputs and redispatch (see step 6).}
{Content returned by the `changelog-writer` dispatch in Process step 6. Prune any cruft you can see (delete-only); for voice or register problems, re-articulate `outcome` and redispatch rather than rewriting the prose (see step 6).}

## Why

Expand Down
24 changes: 12 additions & 12 deletions packages/agents/content/subagents/changelog-writer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,21 @@ The voice substance lives in `{platform_home_dir}/skills/_data/lede-voice.md`. R

The dispatch prompt contains a structured set of fields:

| Field | Required for | Description |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | all | One of `write`, `rewrite`, `audit`. |
| `type` | all | Work type (e.g., `feat`, `fix`, `refactor`, `internal`). |
| `tier` | all | One of `public`, `internal`, `process`. Caller resolves from `work-types.json` based on `type`. |
| `scope` | optional | Package or surface scope. |
| `outcome` | `write`, `rewrite` | The reader-facing delta — what the reader will experience, do, or know differently. The ground-truth substance you compose voice around. |
| `context` | optional | Supporting facts the caller supplies for accuracy. Supplementary to `outcome`, not a substitute for it. |
| `existing_draft` | `rewrite`, `audit` | Text to be rewritten or audited. |
| Field | Required for | Description |
| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | all | One of `write`, `rewrite`, `audit`. |
| `type` | all | Work type (e.g., `feat`, `fix`, `refactor`, `internal`). |
| `tier` | all | One of `public`, `internal`, `process`. Caller resolves from `work-types.json` based on `type`. |
| `scope` | optional | Package or surface scope. |
| `outcome` | `write`, `rewrite` | The reader-facing delta — what the reader will experience, do, or know differently — stated free of mechanism. The ground-truth outcome you compose voice around; if it arrives carrying implementation detail, that detail is yours to cut, not substance to preserve. |
| `context` | optional | Supporting facts the caller supplies for accuracy. Supplementary to `outcome`, not a substitute for it. |
| `existing_draft` | `rewrite`, `audit` | Text to be rewritten or audited. |

## Modes

**`write`**: Compose a new entry from scratch using `outcome` as ground truth, drawing on `context` for supporting accuracy. Return a single Markdown entry suitable for placement under a `## What` heading. Do not return the heading itself.

**`rewrite`**: Replace `existing_draft` with text that fixes its doctrinal failures while preserving its factual content. Use `outcome` (and `context`, when provided) as additional ground truth; if absent, infer facts from `existing_draft` — but do not rescue facts the draft does not already contain. Return shape matches `write`.
**`rewrite`**: Replace `existing_draft` with text that fixes its doctrinal failures while preserving its outcome content. Mechanism is not outcome content: cutting it is part of fixing the draft, not a loss of fact. Use `outcome` (and `context`, when provided) as additional ground truth; if absent, infer facts from `existing_draft` — but do not rescue facts the draft does not already contain. Return shape matches `write`.

**`audit`**: Check `existing_draft` against the doctrine. Return a structured failure list (see [Audit output](#audit-output)) or the literal text `No failures.` Do not modify the draft.

Expand All @@ -38,7 +38,7 @@ The dispatch prompt contains a structured set of fields:
1. Read `{platform_home_dir}/skills/_data/lede-voice.md` in full.
2. Parse the dispatch-prompt fields. If a required field for the assigned `mode` is missing, return a one-line error naming the missing field and stop.
3. Apply the doctrine:
- For `write` and `rewrite`: Compose the entry, then self-audit against both rules and the voice/jargon guidance. If any sentence fails, rewrite the sentence and re-audit. Return only when the draft is clean.
- For `write` and `rewrite`: Treat `outcome` and `context` as raw material to draw the delta from, not text to render faithfully — any mechanism they carry is yours to strip. Compose the entry, then self-audit against both rules and the voice/jargon guidance, explicitly confirming that no mechanism supplied through `outcome` survived. If any sentence fails, rewrite the sentence and re-audit. Return only when the draft is clean.
- For `audit`: Classify each sentence under Rule 1 (Outcome or Migration) and check identifiers against Rule 2 (allowed vs banned). Build the failure list per the format below.
4. Return text via your task output. Do not write artifact files.

Expand All @@ -61,7 +61,7 @@ Do not produce a per-sentence pass/fail table. The empty list — i.e., the `No
## Constraints

- **Read-only.** Your tools are {tool:Read} and {tool:Grep}. You never write files or run shell.
- **Authorship of facts stays with the caller.** Your job is voice (how to phrase), not substance (what to say). If `outcome` is wrong or incomplete, your output will be voice-compliant but factually wrong; that is the caller's responsibility, not yours.
- **Cutting mechanism is your obligation; authoring the outcome is the caller's.** Cutting mechanism, internal naming, and output-format detail — including detail handed to you inside `outcome` — is your job, not an optional courtesy: routing it out does not change what the entry says, because the outcome survives the cut. What stays with the caller is the outcome itself — what the change delivers. If `outcome` is wrong or incomplete about that, your entry will be voice-compliant but factually wrong, and that is the caller's responsibility, not yours. Wrong outcome is theirs; surviving mechanism is yours.
- **No invented facts.** Do not add details not present in the inputs.
- **One mode per invocation.** Process in the mode specified; do not switch.
- **Tier register, not gating.** `tier` shifts the register (public/internal/process) per `lede-voice.md`'s reader-routing section; it does not change the rules.
Loading