weed-prose

Weed Prose

The reader you stand for

Load chalk:voice first. It defines who every chalk reader is and the register you are checking against; the artefact skill defines what its readers are doing. Do not reconstruct either from this file.

The caller names the artefact and gives you the path to the drafted body. You hold exactly what that artefact's reader can reach — no more:

• PR description — the branch diff, and the linked issue if there is one. Readers and success metrics are in chalk:pr.
• Issue body — the parent issue if there is one, and nothing else. There is no diff. Readers and success metrics are in chalk:issue.

The caller SHOULD hand you the referenced issue as a file, since it usually already holds it and a gh issue view is a network round-trip you don't need.

• Use it as given. It MUST be the issue body verbatim — that is what makes it the same thing the reader would open.
• A summarised, annotated or truncated copy MUST be rejected, and you fetch the issue yourself instead. The tell is commentary: a body that explains itself, refers to what "we" decided, or reads shorter than a description would. Told what the author thinks the issue says, you can no longer tell which sentences the draft is carrying.
• Fetch it yourself where no file is passed, or where the one passed doesn't resolve.

You MUST NOT be given, and MUST NOT ask for, the session that produced the draft. If the caller volunteers it, ignore it.

On a PR, read the diff before the draft. A sentence only looks surplus once you have seen what the reader can already see.

Two jobs, and the second is the one that gets skipped

Cut what the reader already has

Delete a sentence when it:

• Restates the diff. What changed, which files, which functions. The reader has it. (PR only — an issue has no diff.) This cut MUST NOT fire where the diff is itself prose — documentation, rules, skills, specs, comments. See "When the diff is prose" below.
• Repeats the artefact it points at. A PR's linked issue, or an issue's parent — the link does that work, and a sub-issue inherits its parent's motivation. Only where that artefact exists. A standalone PR MUST carry the problem context itself; do not strip it.
• Argues that a decision was good rather than stating what it was and what constrained it.
• Narrates the work — what was tried, in what order, what was run. The journey is not the reasoning.
• Ranks or justifies its own material, narrates the document's shape, or advertises the author's diligence.
• Matches a phrase in the inventories below.