docs(session-flow): de-slop instruction surfaces (0.32.4)

[kyle-sexton]

No linked issue

Summary

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

Fix

Rewrote plugins/session-flow/README.md and every plugins/session-flow/**/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 paired-aside and subjectless clauses the first pass split. The generated options block is ignore-fenced; its shared template is a later shard. Protocol strings that producers emit or consumers match stay inside fences and inline code (Re-arm <i> of <n> — <L> lines:, the fenced ORCHESTRATION BRIEF title, the workflow glance map). session-flow 0.32.4.

Verification

• CLAUDE_PROJECT_DIR plus a gitignored overlay that re-enables rule-em-dash: session-flow instruction surfaces go from 658 findings to 0 (48 declined inside the generated-options ignore fence and protocol/fence spans).
• bash plugins/session-flow/skills/running-retro/scripts/observer.test.sh 72 tests OK
• bash plugins/session-flow/skills/retro/scripts/parse-transcript.test.sh 12 tests OK
• bash plugins/session-flow/skills/keep-going/scripts/check-usage-limit-reset.test.sh passes
• python3 scripts/sync-plugin-options-docs.py --check up to date
• scripts/check-changelog-parity.sh --check-bump origin/main passes

Instruction-surface remainder on origin/main after this shard: 7972 rule-em-dash plus 19 other script tells (10 triad, 3 negative-parallelism, 4 chatbot, 2 filler). #2891 stays open. Shard 1 is planning (#3105).

Related

Refs #2891

[claude]

Claude finished @kyle-sexton's task in 4m 7s —— View job

---

Claude is reviewing this PR

• Gather context (PR diff, CLAUDE.md, custom instructions)
• Load /review:code-review lane criteria (skill returned no content directly; used its SKILL.md source since this is a mechanical/CI lane)
• Manually verify README.md + spot-check SKILL.md files for meaning-preservation, protocol-string integrity, YAML frontmatter validity
• Deep-read remaining SKILL.md files via subagent (in progress)
• Post summary comment

[claude]

Claude finished @kyle-sexton's task in 1m 24s —— View job

---

/review:security-review

• Gather context (PR diff, custom instructions)
• Run /review:security-review for PR docs(session-flow): de-slop instruction surfaces (0.32.4) #3106
• Post findings

Skip gate triggered: no security-relevant surface.

This PR (plugins/session-flow 0.32.4) is a pure prose de-slop pass: every changed line rewrites em dashes to periods, commas, or a restructured sentence across README.md and the fourteen SKILL.md files, plus a version bump and changelog entry. Confirmed via git diff HEAD~1 HEAD:

• No frontmatter changes (allowed-tools, permissions, disable-model-invocation, user-invocable all untouched).
• No script, command, or code-block content changed, only surrounding prose.
• No GitHub Actions workflow files touched.
• No new URLs, tokens, credentials, or executable instructions introduced; the diff only re-punctuates existing sentences (e.g. "...secrets — no files..." → "...secrets, no files...").

No authorization, injection, secret-handling, or Actions-security surface to review here. No findings to report.

Branch: cursor/2891-deslop-shard2-cfcf

[github-actions]

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

[github-actions]

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a133d17058

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @cursor[bot]'s task in 7m 2s —— View job

---

/review:code-review for PR #3106

• Gather context (PR diff, custom instructions)
• Run /review:code-review for PR docs(session-flow): de-slop instruction surfaces (0.32.4) #3106
• Post findings

Summary

This shard rewrites em dashes to periods, commas, or restructured sentences across session-flow's README.md and all fourteen SKILL.md files. The skip gate (trivial/automated change, no review surface) does not apply here: these files are parsed as live agent instructions and frontmatter descriptions drive skill routing, so a rewrite that changes their grammar is a correctness concern, not just style. The PR's own stated method ("periods, commas, or a restructured sentence") is sound, but it was applied inconsistently in one specific way: several em dashes that separated two independent clauses were replaced with a bare comma instead of a period/semicolon, producing comma splices, and two spots have outright broken sentences from the split. Posted 10 inline comments covering both categories.

The recurring pattern (comma splice): when the text before and after an em dash each has its own subject and verb, a comma alone under-punctuates it (X, Y reads as one fused sentence). A period, semicolon, or an explicit conjunction is needed instead. This shows up in handoff/SKILL.md:265, reconcile/SKILL.md:154, workflow/SKILL.md:196, find-handoff/SKILL.md:18, running-retro/SKILL.md:233, README.md:64, and in two frontmatter description fields (show-options/SKILL.md:2, orient/SKILL.md:2) — all flagged inline. A few more instances of the same pattern exist beyond what's called out inline (not exhaustively re-flagged to avoid noise, same fix applies):

• find-handoff/SKILL.md:420
• keep-going/SKILL.md:48
• orchestrate/SKILL.md:156
• orient/SKILL.md:106

Two outright breaks from the split itself (also flagged inline):

• workflow/SKILL.md:36 — a sentence-ending period was inserted while still inside an unclosed (...), leaving a parenthetical that spans a sentence boundary.
• show-options/SKILL.md:158 — an appositive fragment ("97.8% of the catalog") got promoted to its own capitalized "sentence" with no verb, and of is now wrongly capitalized.

Checked and not a finding: plugin.json's description field still has 10 em-dash escapes. That's consistent with the shard-1 precedent (planning's plugin.json also still has one after #3105), so plugin manifest descriptions appear to be intentionally out of scope for this de-slop pass, not a miss.

No security-relevant surface (confirmed by the existing security-review lane comment on this PR). No script/code-block or frontmatter field (only prose) changes found beyond the version bump and changelog entry.

Branch: cursor/2891-deslop-shard2-cfcf

[claude]

Claude finished @cursor[bot]'s task in 2m 59s —— View job

---

Claude is reviewing this PR

• Gather context (PR diff, CLAUDE.md, custom instructions)
• Load /review:code-review lane criteria (skip gate, high-signal bar, adversarial validation)
• Verify prior findings (codex + earlier claude pass) still apply against current HEAD 04715a2
• Scan remaining diff for additional comma-splice / protocol-string correctness bugs (subagent in progress)
• Post any new inline findings
• Post summary comment

[kyle-sexton]

No description provided.

[kyle-sexton]

Taking over from expired work-item-lease held by session MELO-LAP-001-triage-202608230449 (1h TTL, no renewal or further activity observed since acquisition; current time 2026-08-23T07:12Z is well past expiry). Proceeding under lane babysit-loop, instance melo-lap-001-merge-20260823T045045Z.

[kyle-sexton]

This was generated by AI during triage.

Triage outcome: rework (verified diff, mechanical-stub brief)

Verified. Checked out the PR into an isolated worktree and independently confirmed the diff does what it claims:

• plugins/session-flow/skills/running-retro/scripts/observer.test.sh — 72 tests OK
• plugins/session-flow/skills/keep-going/scripts/check-usage-limit-reset.test.sh — 12 tests OK
• python3 scripts/sync-plugin-options-docs.py --check — up to date
• parse-transcript.test.sh — skipped locally (pytest not installed in the triage sandbox), not re-verified
• All CI gates on the PR are green

But not a clean adopt. The existing automated /review:code-review pass on this PR already identified real defects that remain unresolved at current HEAD (04715a267): the em-dash removal introduced comma splices where the dash separated two independent clauses, plus two outright broken sentences. Independently re-confirmed both flagged breaks by direct file read:

• workflow SKILL.md — the parenthetical aside now contains a sentence-ending period before its own closing paren, leaving an unclosed-looking parenthetical spanning a sentence boundary.
• show-options SKILL.md — an appositive fragment ("97.8% Of the catalog") was promoted to its own capitalized non-sentence with wrongly-capitalized "Of".

Frontmatter description fields drive skill routing and SKILL.md prose is parsed as live agent instruction, so this is a correctness gap against the PR's own "meaning-preserving" requirement, not just style.

Sites + fix pattern (mechanical, no design decision):

• Fix pattern 1 (comma splice): everywhere the em-dash-to-comma rewrite fused two independent clauses (each side has its own subject + verb) into X, Y, replace the comma with a period, semicolon, or explicit conjunction. Affected skills per the existing review comment on this PR: handoff, reconcile, workflow, find-handoff, running-retro, README, plus the show-options and orient frontmatter description fields, and (called out but not inline-flagged) find-handoff, keep-going, orchestrate, orient again elsewhere.
• Fix pattern 2 (broken sentence from the split): restore correct sentence boundaries / capitalization at the two spots above without reintroducing an em dash.

Full site list with exact locations is already posted inline on this PR by the automated code-review lane; use that as the authoritative site index rather than re-deriving it.

Note: this triage pass observed a work-item-lease coordination anomaly — the triage lease acquired for this session (MELO-LAP-001-triage-202608230449) expired before this evaluation completed, and a separate babysit-loop merge-lane instance posted a takeover comment in the interim. That lane's claim targets merge coordination and doesn't conflict with this triage labeling; flagging for visibility only.

[kyle-sexton]

Taking over from expired lane-claim held by instance melo-lap-001-merge-20260823T045045Z (lane babysit-loop; that claim has expired). Proceeding under this claim:

[claude]

Claude finished @kyle-sexton's task in 10m 17s —— View job

---

/review:code-review for PR #3106 (re-run at HEAD f4e7bcc)

• Gather context (PR diff, custom instructions, prior review threads)
• Invoke /review:code-review skill for this PR
• Re-verify all previously flagged findings against current HEAD
• Scan the full diff for additional comma-splice / protocol-string correctness bugs
• Post inline findings
• Post summary comment

Summary

The 15 previously-flagged threads are genuinely fixed. I independently re-diffed f4e7bcc against the prior HEAD and read every one of the 15 sites (comma splices in handoff, reconcile, workflow, find-handoff, running-retro, keep-going, orchestrate, orient, README; the two broken sentences in workflow/show-options; the Re-arm <i> of <n> — <L> lines: header restore). All match the reviewer-suggested fixes and read correctly, no new regressions in those hunks.

But the fix commit patched only the specific lines reviewers had hand-flagged, not the underlying pattern. The same mechanical bug — a paired em dash joining two independent clauses collapsed to a bare comma instead of a period/semicolon — recurs extensively elsewhere in this PR's own diff, often as the sibling bullet right next to one that was fixed (e.g. orient/SKILL.md:106 was fixed with a semicolon, :107 two lines later has the identical construction and was not; running-retro/SKILL.md:246 uses the correct period style, :250 right below it doesn't). This means "Addresses all 15 unresolved PR review threads" resolved the threads, not the pattern class, and the PR's own "meaning-preserving" claim doesn't yet hold PR-wide.

Posted 14 inline comments (with drop-in suggestion fixes) covering the clearest, most representative instances across every affected file:

• find-handoff/SKILL.md: lines 333, 335-341, 416, 418
• continue-in-background/SKILL.md: lines 70, 209-211
• handoff/SKILL.md: lines 51, 69
• orient/SKILL.md: lines 107, 113
• workflow/SKILL.md: lines 174-179
• retro/SKILL.md: line 37
• running-retro/SKILL.md: line 250
• reanchor/SKILL.md: lines 29-30 (a distinct sub-case: the em dash here was deleted outright with no replacement punctuation, not converted to a comma, leaving a genuinely garbled clause)

Additional confirmed instances of the same splice pattern, not individually inline-flagged to avoid further noise (same fix: comma → period/semicolon), given as permalinks against f4e7bcc:

• find-handoff/SKILL.md:242 — "contributes no root, the candidate stays UNRESOLVED..."
• find-handoff/SKILL.md:321 — "...(prompt-only mode), the path is the thing being recovered..."
• find-handoff/SKILL.md:61 — "...candidate, a block is already qualified by the three signals above..."
• find-handoff/SKILL.md:172 — "OPEN, this rung cannot correlate a candidate..."
• find-handoff/SKILL.md:317-318 — "...(multiple sessions land within seconds of each other), the markers do."
• workflow/SKILL.md:113 — "skip this, the default is simply to continue."
• workflow/SKILL.md:115 — "...it does not act**, the recommendation goes to the human..."
• workflow/SKILL.md:139 — "A foggy, too-big-to-plan effort, the destination is clear but the route is not..."

Given how many of these turned up in a targeted grep rather than an exhaustive line-by-line read of all 17 files, this list is very likely not complete — treat it as a lower bound, not a full inventory.

Recommendation

Given the volume and that the pattern keeps resurfacing next to already-fixed siblings, a targeted re-grep of this PR's full diff for , (the|a|an|this|that|it|they)\s+\S+\s+(is|are|does|has|...) against every changed file (not just the threads already named in review comments) would catch the remainder in one pass, rather than another round of one-off patches.

Not re-litigated: plugin.json's manifest description still carries em dashes — already established as out-of-scope for this shard per shard-1 precedent. No security-relevant surface (per the existing /review:security-review pass on this PR).
· Branch: cursor/2891-deslop-shard2-cfcf

[claude]

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

---

/review:security-review for PR #3106 (re-run at HEAD f4e7bcc)

• Gather context (PR diff, custom instructions)
• Run /review:security-review for PR docs(session-flow): de-slop instruction surfaces (0.32.4) #3106
• Post findings

Skip gate triggered: no security-relevant surface.

Re-ran the review against current HEAD f4e7bcc. Since the last security-review pass (at 7a1dad0), the only new commit is f4e7bcc ("repair comma splices and header delimiter from de-slop pass"), which addresses the correctness findings from the /review:code-review lane. Confirmed via git diff 7a1dad0..f4e7bcc:

• 10 files changed, all inside plugins/session-flow (README.md and nine SKILL.md files), 16 lines each way.
• Every hunk is a punctuation/wording fix: bare commas joining independent clauses replaced with semicolons or a period, one restored E.g. → e.g. mid-sentence, and the re-arm header literal in find-handoff/SKILL.md:308 restored from Re-arm <i> of <n>. <L> lines: to the correct Re-arm <i> of <n> — <L> lines: (matching what reference/save-point.md actually emits).
• Two of the changed lines are inside frontmatter description fields (orient/SKILL.md, show-options/SKILL.md), but only punctuation changed, no new tool grants, no allowed-tools/disable-model-invocation/user-invocable changes.
• No script, code-block, or command content changed; no GitHub Actions workflow files touched; no new URLs, tokens, or credentials introduced.

This remains a pure documentation/prose PR with no injection, authorization, secret-handling, or Actions-security surface. No security findings to report.

Note: the earlier /review:code-review findings (comma splices, two broken sentences, the re-arm delimiter) were prose-correctness issues, not security issues, and appear to be exactly what this commit fixed, out of scope for this lane either way.

Branch: cursor/2891-deslop-shard2-cfcf

[kyle-sexton]

Follow-up b6748899 repairs the remaining comma splices the review threads named (find-handoff Rootless/Rooted and Does-not bullets, continue-in-background, handoff Purpose/STOP paragraph, orient, workflow rigor/artifacts, retro, running-retro, reanchor claimed-state colon). Quoted Re-arm <i> of <n> — <L> lines: protocol headers stay byte-identical. Resolving the now-outdated threads so the review-thread ruleset can unblock.

[claude]

Claude finished @kyle-sexton's task in 1m 7s —— View job

---

/review:security-review for PR #3106 (re-run at HEAD 851765e)

• Gather context (PR diff, custom instructions)
• Run /review:security-review for PR docs(session-flow): de-slop instruction surfaces (0.32.4) #3106
• Post findings

Skip gate triggered: no security-relevant surface.

Re-ran the review against current HEAD 851765e. Compared against the last-reviewed head f4e7bcc (per the prior security-review lane comment on this PR), scoped to the PR's own changed files (git diff f4e7bcca76b4edb15541ce685292d6b3cd8642d4..HEAD -- plugins/session-flow/):

• Only one intervening commit touches the PR's tracked files (b674889, "repair comma splices and header delimiter from de-slop pass"), and it is exactly what its message says: bare commas fused between independent clauses replaced with periods/semicolons across continue-in-background, find-handoff, handoff, orient, reanchor, reconcile, retro, running-retro, and workflow SKILL.md files.
• Confirmed the changed-file set is still the same 17 files as every prior pass (plugin.json version bump, CHANGELOG.md, README.md, and the fourteen SKILL.md files), all in plugins/session-flow, via git diff origin/main...HEAD --stat.
• No frontmatter field changes (allowed-tools, disable-model-invocation, user-invocable all untouched, only prose inside description values), no script/code-block/command content changed, no GitHub Actions workflow files touched, no new URLs/tokens/credentials, no permission or trust-boundary changes anywhere in this delta.

This remains a pure documentation/prose PR. No security findings to report.

Note: the /review:code-review lane's comma-splice / broken-sentence / protocol-string findings on this PR are prose-correctness issues, not security issues, and are out of scope for this lane either way; per the PR thread, those have been progressively fixed across f4e7bcc and the follow-up b674889.

Branch: cursor/2891-deslop-shard2-cfcf

[kyle-sexton]

Instance MELO-LAP-001-merge-202608231413-w3106 stopping: head SHA changed mid-task from 7a1dad03a65015e3259b60dd48dfcaea6bce3ea4 (pinned at start) to f4e7bcca76b4edb15541ce685292d6b3cd8642d4 (my own fix-and-push, all 15 originally-flagged threads addressed, CI green, replies posted citing the commit) to 851765e9db2c932bfe4c8085eda2e4042a5587c5, pushed directly by the PR author (kyle-sexton) as "docs(session-flow): de-slop instruction surfaces (0.32.6)" while I was mid-fix on 14 further comma splices an automated review pass had found on top of my commit.

Per the multi-instance safety rule, I stopped: discarded my local uncommitted second-batch fixes (never pushed) and did not merge. Per the live GraphQL state at time of writing, all 29 review threads (15 original + 14 follow-up) are now resolved on the author's 851765e9 commit, and CI is green apart from one still-pending plugin-gate check. Merge readiness looks close but I am releasing this lane rather than racing the author's own push.