docs(work-items): de-slop instruction surfaces (0.39.13) by kyle-sexton · Pull Request #3107 · melodic-software/claude-code-plugins

kyle-sexton · 2026-08-21T15:21:12Z

No linked issue

Summary

Third #2891 de-slop shard: purge em dashes from the work-items plugin instruction surfaces (next-worst cluster after planning and session-flow).

Fix

Rewrote plugins/work-items/README.md and every plugins/work-items/**/SKILL.md under /ai-slop:audit fix semantics (periods, commas, or a restructured sentence; never parentheses, en dashes, or a spaced hyphen as a stand-in). Meaning-preserving self-audit repaired multi-line paired asides the mechanical pass split. The generated options block is ignore-fenced; its shared template is a later shard. One quoted auto-invocation trigger (the spec changed — redo the tickets) keeps its em dash so skill-quality does not treat the rewrite as a dropped trigger. work-items 0.39.13. Cheatsheet refreshed for the rewritten ship summary.

Verification

session-flow/planning shards are separate PRs (docs(planning): de-slop instruction surfaces (0.34.1) #3105, docs(session-flow): de-slop instruction surfaces (0.32.4) #3106)
Detector on this cluster: 1 remaining rule-em-dash (the required trigger phrase), 49 declined (generated-options fence plus fenced/inline-code protocol spans)
CHECK_SKILL_SKIP_MARKDOWNLINT=1 bash scripts/check-changed-skills.sh origin/main: 10 skills, 0 failed
bash plugins/work-items/skills/work/scripts/preflight.test.sh: 99 checks passed
bash plugins/work-items/tests/no-hardcoded-priority-scheme.test.sh: 6 passed
python3 scripts/sync-plugin-options-docs.py --check up to date
scripts/check-changelog-parity.sh --check-bump origin/main passes

#2891 stays open. Next cluster after this is source-control.

Rewrite README and every SKILL.md under /ai-slop:audit fix semantics for the #2891 campaign. Em dashes become periods or commas, or the sentence is restructured. Generated options block is ignore-fenced. The quoted trigger 'the spec changed — redo the tickets' is kept so auto-invocation does not regress. Cheatsheet refreshed for the rewritten ship summary. Refs #2891 Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

claude · 2026-08-21T15:21:41Z

Claude finished @kyle-sexton's task in 56s —— View job

Security review

Gather context (PR diff, changed files)
Apply skip gate check
Review diff for security-relevant surface
Report findings

Result: skipped — no security-relevant surface.

This PR (docs(work-items): de-slop instruction surfaces) is a pure prose/punctuation rewrite of Markdown instruction files (README.md, SKILL.md files, changelog, and a version bump), replacing em dashes with periods, commas, or restructured sentences. I diffed all 14 changed files against origin/main:

No source code, scripts, or executable logic changed.
No .github/workflows/** or other YAML/CI configuration touched.
No permissions, tokens, credentials, or trust-boundary logic affected.
The example commands and quoted trigger phrases inside the skill docs are unchanged in substance (only punctuation), including the one intentionally-preserved em dash in the quoted auto-invocation trigger (the spec changed — redo the tickets), per the PR description.

No findings to report under /review:security-review criteria (logic flaws, access-control gaps, injection surfaces, secret handling, or Actions workflow risk).

github-actions · 2026-08-21T15:23:17Z

Last security-reviewed head: 8265c578e29d01521d75572c8c2df1ceb0c0fccf. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

Refs #2891 Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

claude · 2026-08-21T15:33:31Z

Claude finished @cursor[bot]'s task in 3m 37s —— View job

Code review complete

Gather context (PR diff, changed files)
Apply skip gate check
Review diff for correctness / maintainability
Report findings

This PR is a mechanical em-dash-removal pass over work-items plugin instruction files (README.md, CHANGELOG.md, all SKILL.md). No behavioral/code changes; scope is prose only, so the review focused on whether the rewrite preserved meaning and grammar in these agent-facing instruction files.

3 inline findings posted, all leftover artifacts of the mechanical em-dash → period/comma conversion that a careful pass should catch before merge:

decompose/SKILL.md:82 — the rewrite garbled a sentence rather than preserving it: alongside — or ahead of — build slices became alongside, or ahead of. Build slices., turning "build slices" from the object of "ahead of" into a stray imperative sentence. This is the one place the punctuation change actually altered what the instruction says, not just its rhythm.
work-loop/SKILL.md:277 — a dangling leading comma ( , is not a new escalation...) left over from splitting an em-dash-bracketed aside across a line wrap. Not valid prose, purely a rewrite artifact.
setup/SKILL.md:389 — a new sentence starts with a lowercase word (`Review CI`. **filter the results...**) after the em dash was swapped for a period. The same pattern (period followed by a lowercase word/bold-lowercase starting a "sentence") also appears uncorrected at decompose/SKILL.md:106 and :263 (list. **work the frontier**) and work/SKILL.md:260 (section. **ensure the section exists first**) — flagged as a note on that finding since GitHub only allows one anchor per comment. A repo-wide grep for \. \*\*[a-z] (or more broadly \. [a-z] at sentence starts) across the changed files would catch the rest before merge; the PR description says a "meaning-preserving self-audit" already ran against the mechanical splits, so these look like ones that slipped through it.

Everything else in the diff is the intended mechanical substitution (em dash → period/comma/restructure) with meaning and code fences untouched; the one deliberately preserved em dash (the spec changed — redo the tickets) and the ignore-fenced generated options block match what the PR description claims. No security-relevant surface (docs-only), consistent with the security lane's earlier skip on this PR.
(branch)

claude · 2026-08-21T15:37:11Z

+The human-gated label (default `needs-human`) is what keeps a slice out of autonomous pickup. `list-frontier --autonomous` excludes it (`${CLAUDE_PLUGIN_ROOT}/tools/work-item-tracker/CONTRACT.md` "Verbs (core public surface)"). Merely omitting the autonomous-eligible label does NOT: the frontier filter keys on the human-gated label, not on the absence of the other, so an unlabeled HITL slice would still be claimable by `/work-items:work`. The autonomous-eligible label (default `agent-ready`) is the positive autonomous-pickup eligibility marker; the two labels gate different filters and an HITL slice wants the human-gated label set AND the autonomous-eligible one omitted.

-**Investigation tickets — decisions, not deliverables.** When the source still carries unresolved unknowns (open design questions, unvalidated approaches, fuzzy scope), emit **investigation tickets** alongside — or ahead of — build slices. An investigation ticket resolves ONE decision and records the resolution as a closing comment; it produces no production code. Type each by the skill that resolves it:
+**Investigation tickets, decisions, not deliverables.** When the source still carries unresolved unknowns (open design questions, unvalidated approaches, fuzzy scope), emit **investigation tickets** alongside, or ahead of. Build slices. An investigation ticket resolves ONE decision and records the resolution as a closing comment; it produces no production code. Type each by the skill that resolves it:


The em-dash removal here garbled the sentence rather than preserving its meaning. Original: emit **investigation tickets** alongside — or ahead of — build slices. ("build slices" was the object of "ahead of.") Rewritten: emit **investigation tickets** alongside, or ahead of. Build slices. — this now reads as an incomplete clause ("alongside, or ahead of.") followed by a stray imperative sentence ("Build slices."), which changes what the sentence is telling the reader to do.

Suggested fix: emit **investigation tickets** alongside, or ahead of, build slices.

Fix this →

claude · 2026-08-21T15:37:16Z

-   whose marker already stands — a still-unratified `ratify-c3`, an idempotent label re-convergence
-   — is not a new escalation, so the cycle files no second comment and writes no second record.
+   whose marker already stands, a still-unratified `ratify-c3`, an idempotent label re-convergence
+  , is not a new escalation, so the cycle files no second comment and writes no second record.


Stray leading comma left over from the em-dash rewrite: the line reads , is not a new escalation, so the cycle files no second comment.... This is a mechanical artifact (dash → comma split across a line wrap), not valid prose. Should read ..., an idempotent label re-convergence, is not a new escalation, ... on one clause.

Fix this →

claude · 2026-08-21T15:37:18Z

   substring/prefix, not exact-title equality,
   so it can return a longer item (`[Maintenance] Review CI workflow pins`) when the old title was
-   `Review CI` — **filter the results to the one whose title equals `[Maintenance] {old title}`
+   `Review CI`. **filter the results to the one whose title equals `[Maintenance] {old title}`


Sentence-capitalization slip from the em-dash rewrite: `Review CI`. **filter the results...** starts a new sentence with a lowercase "filter". Same pattern recurs at decompose/SKILL.md:106 and :263 (list. **work the frontier**) and work/SKILL.md:260 (section. **ensure the section exists first**) — worth a repo-wide grep for \. \*\*[a-z] before merging, since the self-audit pass mentioned in the PR description was meant to catch exactly this class of split.

github-actions · 2026-08-21T15:37:38Z

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

Fifth #2891 de-slop shard: purge em dashes from the claude-config plugin instruction surfaces, the next-worst cluster after session-flow (#3106), planning (#3105), work-items (#3107) and source-control (#3108). Rewrote README.md and all ten SKILL.md files under /ai-slop:audit fix semantics: periods, commas, a colon before a list, or a restructured sentence. Never parentheses, en dashes, or a spaced hyphen, since each of those is the same interruption wearing a different mark. Two review rounds on the PR caught seven places where a paired em dash had become parentheses and two doubled-connective run-ons; all were restructured. Rebased onto 0.39.0. That release restructured audit-instructions/SKILL.md (moving the Phase D state-key block to context/report-keying.md) and added --persist-findings, so this shard re-applies to the new text rather than reverting it: the flag, its Phase D paragraph, and both context/ spokes are retained, with the em dashes in the new prose purged in the same style. context/ files stay out of scope, matching #2891's target set and every prior shard. Frontmatter description and argument-hint values are rewritten too. No quoted auto-invocation trigger phrase contained an em dash, so no trigger changed. Verification (this repo's .claude/ai-slop.json disables rule-em-dash corpus-wide, so the detector runs against an isolated HOME and CLAUDE_PROJECT_DIR to force the rule on): - detect.sh over the 11 shard files: 482 findings -> 0, every other rule also 0 - no en dash or spaced hyphen introduced; the four en dashes in the diff are pre-existing numeric ranges (I1-I28, I1-I5, 3-5 lanes) - check-changelog-parity.sh --check and --check-bump origin/main: pass - CHECK_SKILL_SKIP_MARKDOWNLINT=1 check-changed-skills.sh origin/main: 10 skills, 0 errors, every base-ref trigger phrase preserved - markdownlint-cli2 over the 12 changed files: 0 issues - audit-instructions/SKILL.md is 483 lines, under the 500-line cap Pre-existing and not from this diff: three audit-permission-state script suites fail identically on a clean origin/main worktree in this environment. This shard touches no script. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro

Fifth #2891 de-slop shard: purge em dashes from the claude-config plugin instruction surfaces, the next-worst cluster after session-flow (#3106), planning (#3105), work-items (#3107) and source-control (#3108). Rewrote README.md and all ten SKILL.md files under /ai-slop:audit fix semantics: periods, commas, a colon before a list, or a restructured sentence. Never parentheses, en dashes, or a spaced hyphen, since each of those is the same interruption wearing a different mark. Two review rounds on the PR caught seven places where a paired em dash had become parentheses and two doubled-connective run-ons; all were restructured. Rebased across two releases that landed on main mid-review, in both cases re-applying to the newer text rather than reverting it: - 0.39.0 (#3176) restructured audit-instructions/SKILL.md, moving the Phase D state-key block to context/report-keying.md and adding --persist-findings. The flag, its Phase D paragraph, and both context/ spokes are retained. - 0.39.1 (#3178) normalized setup/SKILL.md and audit-instructions/SKILL.md to canonical fleet SSOT wording with PLUGIN-PHILOSOPHY citations. That wording and those citations are kept verbatim; only their punctuation is de-slopped. context/ files stay out of scope, matching #2891's target set and every prior shard. Frontmatter description and argument-hint values are rewritten too. No quoted auto-invocation trigger phrase contained an em dash, so no trigger changed. Verification (this repo's .claude/ai-slop.json disables rule-em-dash corpus-wide, so the detector runs against an isolated HOME and CLAUDE_PROJECT_DIR to force the rule on): - detect.sh over the 11 shard files: 0 findings, every rule clean - no en dash or spaced hyphen introduced; the four en dashes in the diff are pre-existing numeric ranges (I1-I28, I1-I5, 3-5 lanes) - check-changelog-parity.sh --check and --check-bump origin/main: pass - CHECK_SKILL_SKIP_MARKDOWNLINT=1 check-changed-skills.sh origin/main: 10 skills, 0 errors, every base-ref trigger phrase preserved - markdownlint-cli2 over the 12 changed files: 0 issues - audit-instructions/SKILL.md is 484 lines, under the 500-line cap Pre-existing and not from this diff: three audit-permission-state script suites fail identically on a clean origin/main worktree in this environment. This shard touches no script. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro

No linked issue ## Summary Fourth #2891 de-slop shard: purge em dashes from the `source-control` plugin instruction surfaces (next-worst cluster after planning, session-flow, and work-items). ## Fix Rewrote `plugins/source-control/README.md` and every `plugins/source-control/**/SKILL.md` under `/ai-slop:audit fix` semantics (periods, commas, or a restructured sentence; never parentheses, en dashes, or a spaced hyphen as a stand-in). Meaning-preserving self-audit repaired multi-line paired asides. The generated options block is ignore-fenced. Protocol strings in fences and inline code stay as written. `source-control` 0.54.17. Cheatsheet refreshed for the rewritten summary. ## Verification - Detector: 0 `rule-em-dash` findings, 76 declined (generated-options fence plus fenced/inline-code protocol spans) - `python3 -m unittest` `test_skill_contract`: 25 tests OK - `python3 scripts/sync-plugin-options-docs.py --check` up to date - `scripts/check-changelog-parity.sh --check-bump origin/main` passes - Quoted trigger phrases vs origin/main: none lost #2891 stays open. Prior shards: #3105 planning, #3106 session-flow, #3107 work-items. ## Related Refs #2891 --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

No linked issue ## Summary Fifth #2891 de-slop shard: purge em dashes from the `claude-config` plugin instruction surfaces, the next-worst cluster after `session-flow` (#3106), `planning` (#3105), `work-items` (#3107) and `source-control` (#3108). #2891 stays open; ranked by em-dash lines over non-vendor instruction surfaces, the next unclaimed cluster after this one is `discipline` (468), then `claude-ops` (336). ## Fix Rewrote `README.md` and all ten `SKILL.md` files under `/ai-slop:audit fix` semantics: em dashes become periods, commas, a colon before a list, or a restructured sentence. Never parentheses, en dashes, or a spaced hyphen, since each of those is the same interruption wearing a different mark. A self-review against that guardrail caught seven places where a paired em dash had become parentheses in this very diff — four frontmatter `description` values (`audit`, `audit-instructions`, `audit-automation-gaps`, `audit-prompting-postures`) and three inline spots (`setup`'s required-keys list, `audit-instructions`' I8-family list and its discover-instruction-surfaces population, `audit-pass`' exclusion-set aside). All seven were restructured to commas, a colon, or a sentence break; the net parenthesis delta across the diff is -1. Frontmatter `description` and `argument-hint` values are rewritten too. No quoted auto-invocation trigger phrase contained an em dash, so no trigger changed. `claude-config` 0.38.10. Wording only: no check, phase, gate, lane, contract, or script changed. ## Verification This repo's `.claude/ai-slop.json` disables `rule-em-dash` corpus-wide (a deliberate house-style decision, #3031), so every detector run below pins `HOME` and `CLAUDE_PROJECT_DIR` to empty directories to lift that config and force the rule on — the same isolation the detector's own test suite uses. - `detect.sh` over the 11 shard files: **482 `rule-em-dash` findings to 0**, with every other rule also reporting 0. - No en dash or spaced hyphen introduced; net parenthesis delta -1. - `scripts/check-changelog-parity.sh --check` and `--check-bump origin/main`: pass. - `CHECK_SKILL_SKIP_MARKDOWNLINT=1 bash scripts/check-changed-skills.sh origin/main`: 10 skills, 0 errors. It confirms every base-ref trigger phrase is preserved on all ten. One soft warning (`unhobble` at 201 lines against a 200-line target) is pre-existing. - `markdownlint-cli2` over the 12 changed files: 0 issues. - `node scripts/generate-cheatsheet.mjs`: already in sync — no `metadata.summary` value changed, so unlike the `work-items` shard this one needs no cheat-sheet refresh. - `python3 scripts/sync-plugin-options-docs.py --check`, `typos`, `editorconfig-checker`: pass. - `origin/main` merged into the branch before this PR; no conflicts, and the two new main commits (#3115, #3116) touch no `claude-config` file. **Pre-existing failure, not from this diff.** Three `audit-permission-state` script suites fail in this environment: `permission-merge` 19/51, `automode-entry-diff` 3/63, `managed-conformance` 1/37. They fail with identical counts on a clean `origin/main` worktree, and this shard touches no script. Flagging rather than fixing, since diagnosing them is out of scope here. ## Related - Refs #2891 — the de-slop campaign this shard advances; stays open for the remaining clusters. - Refs #3105, #3106, #3107, #3108 — the sibling instruction-surface shards. - Refs #3031 — the measurement and decision that disabled `rule-em-dash` corpus-wide, which is why the verification runs force the rule back on rather than trusting a default run. **Deferred finding, deliberately not fixed here: manifest `description` fields are outside the campaign's scope definition.** Review flagged that `plugins/claude-config/.claude-plugin/plugin.json` still carries 5 em dashes in its marketplace-facing `description`. That is correct, and it is a gap in #2891's own scoping rather than in this shard: the issue defines the target set as "every `SKILL.md`, plugin READMEs, `AGENTS.md`, root `README`", which does not include `plugin.json`. The merged `work-items` shard (#3107) touched its manifest for the version bump only, so every shipped shard carries the same gap. Measured across the marketplace: **47 plugins** have em dashes in their manifest `description`, led by `discipline` (14), `claude-ops` (12) and `session-flow` (11). Fixing only `claude-config` here would leave the shard series internally inconsistent while resolving 5 of ~120 occurrences, so this belongs to a campaign-level decision on #2891 about whether manifest descriptions join the target set, not to this PR. Recorded here so it is not lost. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro --- _Generated by [Claude Code](https://claude.ai/code/session_01Tu5t8rYWv2kDzRcdmLE2ro)_ --- _Generated by [Claude Code](https://claude.ai/code)_

kyle-sexton mentioned this pull request Aug 21, 2026

docs(source-control): de-slop instruction surfaces (0.54.17) #3108

Merged

fix: strip MD009 trailing spaces on rewritten SKILL.md

513a1d2

Refs #2891 Co-authored-by: Kyle Sexton <kyle-sexton@users.noreply.github.com>

kyle-sexton enabled auto-merge (squash) August 21, 2026 15:26

kyle-sexton merged commit dff0942 into main Aug 21, 2026
50 checks passed

kyle-sexton deleted the cursor/2891-deslop-shard3-cfcf branch August 21, 2026 15:35

claude Bot reviewed Aug 21, 2026

View reviewed changes

This was referenced Aug 23, 2026

docs(claude-config): de-slop instruction surfaces (0.38.10) #3155

Merged

De-slop campaign: purge em dashes and AI tells from this repo's own corpus via /ai-slop:audit fix #2891

Open

Navigation Menu

Uh oh!

docs(work-items): de-slop instruction surfaces (0.39.13) - #3107

docs(work-items): de-slop instruction surfaces (0.39.13)#3107
kyle-sexton merged 2 commits into
mainfrom
cursor/2891-deslop-shard3-cfcf

kyle-sexton commented Aug 21, 2026

Uh oh!

claude Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 21, 2026

Uh oh!

claude Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

claude Bot Aug 21, 2026

Uh oh!

claude Bot Aug 21, 2026

Uh oh!

claude Bot Aug 21, 2026

Uh oh!

github-actions Bot commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

kyle-sexton commented Aug 21, 2026

Summary

Fix

Verification

Related

Uh oh!

claude Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Security review

Uh oh!

github-actions Bot commented Aug 21, 2026

Uh oh!

claude Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code review complete

Uh oh!

Uh oh!

claude Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

claude Bot commented Aug 21, 2026 •

edited

Loading

claude Bot commented Aug 21, 2026 •

edited

Loading