docs(work-items): sync triage SKILL attention-view + state machine with live labels by kyle-sexton · Pull Request #922 · melodic-software/claude-code-plugins

kyle-sexton · 2026-07-22T00:46:31Z

Summary

plugins/work-items/skills/triage/SKILL.md had two docs-match-reality gaps against shipped state:

The "Attention view (no number)" bucket list named only the status-axis raw marker (status:needs-triage), leaving a repo that files raw intake on the priority axis (priority:needs-triage, per PR fix(work-items): re-key triage scope on state, not authorship (#486) #802's already-merged dual-axis Scope wording) invisible to the no-arg attention view.
status:needs-decision is a live, actively-used label (e.g. issue Adopt the documentation-existence admission test as a portable-baseline pre-check in doc-drift and declutter tooling #505, per CHANGELOG [0.16.1]/#562), and the closing invariant already referenced it as a routing outcome that clears the raw marker — but the state machine itself never introduced it as a side exit, unlike needs-info, human-gated, and close.

Fix

Attention-view bucket 2 now reads "Raw marker — status:needs-triage / priority:needs-triage, whichever axis the repo files it under", mirroring the Scope section's exact dual-axis wording (SKILL.md line 35).
The "Side exits from any state" sentence and the state-machine ASCII diagram now name status:needs-decision ("awaiting a human or maintainer judgment call" — the label's live GitHub description) alongside the existing side exits.
Version-bumped work-items 0.21.0 → 0.21.1 (patch, matching the #562 precedent for the same doc-only shape) with a matching CHANGELOG entry.

Scope note: the raw-state table row (line 48, unlabeled or status:needs-triage) is intentionally left single-axis — broader raw-marker axis canonicalization across that table, evals, and reference docs is issue #818's job, not this one. Also intentionally out of scope: adding needs-decision to step 2's "Target state" list or step 5's outcome table — doing so would require defining when triage applies it vs. the human-gated role, which the label's live usage does not settle (it appears both with and without needs-human across open issues) and which this issue scoped as pure docs-match-reality, not a design decision.

Verification

Confirmed PR fix(work-items): re-key triage scope on state, not authorship (#486) #802's merged Scope-section wording verbatim (gh pr view 802): "carrying the raw marker (status:needs-triage / priority:needs-triage, whichever axis the repo files it under)" — the attention-view bucket now mirrors this exactly.
Confirmed status:needs-decision is a live label via gh issue list --label "status: needs-decision" (21+ open/closed issues, e.g. source-control:babysit-prs: pr_queue_snapshot self-identity resolution raises on unresolvable @me instead of degrading to --extra-self (readiness-gate parity) #881, mini-SDLC stage 5: re-anchor periodic execution slot in worker chains (child of #513) #718, conventions: standardize the golden-fixture idiom on the graded shape (#634 pattern) — fixtures carry asserted expected outcomes #664, loops/skills: /loop does not reset context per cycle — "restart at ~50%" is an unenforceable admonition, no mechanism triggers a /clear (session ran 13 cycles → ~70%) #551) and confirmed its GitHub description ("Awaiting a human or maintainer judgment call") used verbatim in the new SKILL.md text.
Confirmed issue Adopt the documentation-existence admission test as a portable-baseline pre-check in doc-drift and declutter tooling #505's prior routing to status:needs-decision via the plugin's own CHANGELOG [0.16.1] entry (#562), which already treated needs-decision as a routing outcome in the closing invariant — this PR closes the gap between that reference and the state machine's own introduction of the label.
Traced the ASCII diagram's pipe/branch alignment by hand to confirm the new status:needs-decision line reads correctly as a side exit at the same indentation level as close.

Closes #817

work-items/triage: reconcile SKILL state machine + attention view with live labels #817 (this fix)
fix(work-items): re-key triage scope on state, not authorship (#486) #802 (source of the dual-axis raw-marker wording mirrored here)
Adopt the documentation-existence admission test as a portable-baseline pre-check in doc-drift and declutter tooling #505 (live example of status:needs-decision usage; see also CHANGELOG #562)
work-items/triage: canonicalize raw-intake marker axis across SKILL, evals, reference docs #818 — separate, unopened-PR item covering raw-marker axis canonicalization across the state table, evals, and reference docs; deliberately not touched here to avoid overlap. Re-checked immediately before opening this PR: no PR exists yet for work-items/triage: canonicalize raw-intake marker axis across SKILL, evals, reference docs #818.
docs: document shell test-helper duplication and exit-code divergence as deliberate #853 — open draft PR (labeled do-not-merge, stale at plugin version 0.19.0) also touches plugins/work-items/.claude-plugin/plugin.json and CHANGELOG.md for an unrelated shell-test-helper doc change. Re-checked immediately before opening this PR: no version-bump collision — docs: document shell test-helper duplication and exit-code divergence as deliberate #853 is stale relative to current main (0.21.0) and will need to rebase regardless of this PR.

Claude-Session: https://claude.ai/code/session_01K1V3gkrfSf75isB8MiDy3o

…th live labels The attention view named only the status-axis raw marker, leaving priority-axis intake (priority:needs-triage, per #802's dual-axis Scope wording) invisible to the no-arg view. status:needs-decision was already used by the closing invariant as a routing outcome but never introduced as a side exit in the state machine itself, unlike needs-info, human-gated, and close. Closes #817 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

claude · 2026-07-22T00:46:46Z

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

PR #922 Review — docs(work-items): sync triage SKILL attention-view + state machine with live labels

Gather context and read changed files
Review SKILL.md changes (attention-view bucket + state machine)
Review CHANGELOG.md entry
Review plugin.json version bump
Check consistency across all three files
Post final review

Summary

Clean, well-scoped doc-only sync. No logic changes, no routing behavior altered. The three changes are accurate, internally consistent, and deliberately bounded. See specific notes below.

`SKILL.md` — Attention-view bucket 2

SKILL.md line 78

The new wording:

Raw marker — status:needs-triage / priority:needs-triage, whichever axis the repo files it under — explicitly tagged for evaluation

Mirrors the Scope section at line 35 verbatim, which was established by PR #802. The old single-axis bucket was a genuine gap — a repo filing on the priority axis would never appear in the no-arg attention view. No issues.

`SKILL.md` — Side-exits sentence and ASCII diagram

SKILL.md line 53, line 67

status:needs-decision was already load-bearing in the closing invariant (line 147: "status:needs-decision … each remove the raw marker") but was invisible in the state machine's own introduction of side exits. Adding it to both the sentence and the diagram closes that gap correctly. The colon-description syntax used in the diagram line (├→ status:needs-decision: awaiting a human or maintainer judgment call) is consistent with the existing close: wontfix | … entry.

One observation (not a blocker): The diagram places status:needs-decision as a branch off the raw column (├→), matching how close is placed. The text says "Side exits from any state," but the diagram models them as exits from the root. This is a pre-existing simplification (applies equally to close) and not introduced by this PR — noting it only for documentation awareness. The prose is authoritative; the diagram is schematic.

No issues.

`SKILL.md` — Raw-state table (intentionally unchanged)

SKILL.md line 48 still reads unlabeled or status:needs-triage (single-axis). The PR body correctly identifies this as issue #818's scope. The scope boundary is clean and the PR doesn't bleed into it.

`CHANGELOG.md`

CHANGELOG.md lines 6–17

The entry is accurate, well-structured (Keep a Changelog ### Fixed), covers both gaps in one entry, and explicitly flags "Doc-only; no routing logic changed." The version header matches the plugin.json bump. No issues.

`plugin.json`

plugin.json line 4

0.21.0 → 0.21.1. Patch bump is correct for a doc-only change. The plugin description is not affected by these changes and correctly stays unchanged. No issues.

Verdict

Approved. All three files are consistent with each other, the changes accurately reflect live system state, and the scope boundary (explicitly deferring raw-marker axis canonicalization to #818) is clean. No corrections needed.

claude · 2026-07-22T00:46:51Z

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

Security Review — PR #922

Review PR diff
Examine changed files
Assess security implications
Post findings

No security issues found.

This PR makes three changes, all purely documentary:

File	Change	Security surface
`plugin.json`	Patch version bump `0.21.0 → 0.21.1`	None — no dependency pins, no permissions, no URLs
`CHANGELOG.md`	Added `[0.21.1]` entry describing the doc fix	None — static prose
`skills/triage/SKILL.md`	Added `status:needs-decision` to state-machine side exits; widened bucket-2 label to dual-axis raw marker	None — Markdown documentation, no executable content

Specific checks against the mandate:

Command / SQL / path / template injection — not applicable; no code, no template interpolation, no shell invocations introduced.
Token / secret / credential handling — no secrets referenced or changed.
GitHub Actions patterns (pull_request_target, workflow_run, script injection, permission widening) — no workflow files touched.
Supply-chain / dependency pins — no new actions or packages added; existing pins unchanged.
Authorization / access-control gaps — no permission declarations, role assignments, or access-control logic modified.
Data egress — no new remote endpoints, MCP servers, or network calls introduced.

Nothing in this diff warrants a security finding.

claude · 2026-07-22T00:56:16Z

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

Security Review — PR #922

Read PR diff
Examine changed files
Assess security implications
Post findings

No security issues found.

All three changed files are purely documentary. Security surface for each:

File	Change	Security surface
`plugin.json` L4	Version bump `0.21.0 → 0.21.1`	None — no dependency pins, no permissions, no remote endpoints touched
`CHANGELOG.md` L6–17	New `[0.21.1]` entry	None — static prose
`SKILL.md` L53, L67, L78	Added `status:needs-decision` to state-machine side exits; widened bucket-2 label to dual-axis raw marker	None — Markdown documentation, no executable content

Checks against the mandate:

Command / SQL / path / template injection — not applicable; no code, no shell invocations, no new template variables (existing ${CLAUDE_PLUGIN_ROOT} references are unchanged).
Token / secret / credential handling — no secrets referenced or changed.
GitHub Actions patterns (pull_request_target, workflow_run, script injection, permission widening) — no workflow files touched.
Supply-chain / dependency pins — no new actions or packages added; existing pins unchanged.
Authorization / access-control gaps — no permission declarations, role assignments, or access-control logic modified.
Data egress — no new remote endpoints, MCP servers, or network calls introduced.

Nothing in this diff warrants a security finding.

claude · 2026-07-22T00:56:25Z

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

PR #922 Review — docs(work-items): sync triage SKILL attention-view + state machine with live labels

Summary

Clean, well-scoped doc-only sync. No logic changes, no routing behavior altered. All three files are accurate, internally consistent, and deliberately bounded. Approved.

`SKILL.md` — Side exits sentence

SKILL.md line 53

status:needs-decision is added between needs-info and needs-human in the side-exits sentence. The description — "awaiting a human or maintainer judgment call" — matches the label's live GitHub description verbatim. This closes the gap against the closing invariant at line 147 which already referenced status:needs-decision as a routing outcome that clears the raw marker. No issues.

`SKILL.md` — ASCII diagram

SKILL.md line 67

The new line ├→ status:needs-decision: awaiting a human or maintainer judgment call is correctly placed as a root-level branch, consistent with how close is positioned. The colon-description syntax matches the close: wontfix | … entry's style. The pipe/branch alignment is valid.

Pre-existing note (not introduced by this PR): the diagram models side exits as branches off the raw root, while the prose says "from any state" — the same simplification applies equally to close. The prose is authoritative; the diagram is schematic. This is not a defect for this PR to address.

`SKILL.md` — Attention-view bucket 2

SKILL.md line 78

The new wording:

Raw marker — status:needs-triage / priority:needs-triage, whichever axis the repo files it under — explicitly tagged for evaluation

Mirrors the Scope section at line 35 exactly (established by PR #802). The old single-axis bucket was a real gap: a repo filing on the priority axis would never appear in the no-arg attention view. No issues.

`SKILL.md` — Raw-state table (intentionally unchanged)

SKILL.md line 48 still reads unlabeled or status:needs-triage (single-axis). The PR correctly defers the broader raw-marker axis canonicalization to issue #818. Scope boundary is clean and the PR doesn't bleed into it.

`CHANGELOG.md`

CHANGELOG.md lines 6–17

Accurate, well-structured (Keep a Changelog ### Fixed). Covers both gaps, correctly flags "Doc-only; no routing logic changed." Version header matches the plugin.json bump. No issues.

`plugin.json`

plugin.json line 4

0.21.0 → 0.21.1. Correct patch bump for a doc-only change. Description unchanged. No issues.

Verdict

Approved. Three files, two genuine doc gaps closed, tight scope discipline. No corrections needed.

work-items CHANGELOG: both sides released 0.21.1 — main's #922 keeps it; this branch's advisor entry moves to 0.21.2 with the matching plugin.json bump.

…eet-wide (#934) ## Summary Fleet-wide escalation of the fresh-eyes checkpoint rule: at sites whose verdict is high-stakes and where correlated blind spots are the risk, prefer a cross-vendor advisor when one is installed AND its documented surface can take the judged artifact, invoked per that plugin's own docs — with the fresh-context same-vendor subagent as the stated fallback. Sites never restate the advisor's command flags (three review rounds showed per-site --wait/--base/diff-semantics examples drifting against the surface the advisor owns); `review:fanout` remains the one concrete codex integration, since it resolves its own diff base. - `docs/PLUGIN-PHILOSOPHY.md` "Fresh-eyes checkpoints" gains the independence-ladder escalation rule; sites carry only the gate+target+fallback sentence (rule stated once). - Seam-phrasing conformant (gate + fallback + ownership framing). `verification:confirm`'s canonical site is aligned to the same capability-generic shape; fanout, implement→confirm, and debug env-hook untouched. - One sentence per skill at the primary delegation-instructing site; patch bump + CHANGELOG `### Changed` entry per touched plugin. ## Touched plugins (all patch bumps) planning 0.24.4, implementation 0.7.8, review 0.14.11, codebase-health 0.7.2, claude-config 0.9.2, work-items 0.21.2 (0.21.1 taken by #922 on main; resolved in merge), re-anchor 0.5.1, docs-hygiene 0.8.4, verification 0.3.4 (canonical confirm site gains --wait, same defect as the Codex P2 finding), session-flow 0.13.1, playbooks 0.3.2 Two site-level judgment calls worth review attention: `session-flow:orchestrate`'s sentence names no command — imperative 3 is exported verbatim into a model-/tool-agnostic worker brief where a plugin command cannot resolve (gate + cross-vendor target + fallback kept, example dropped); `playbooks:fable-5` was aligned at its SSOT (`context/orchestration.md`, which already named a cross-vendor reviewer) rather than touched at its two pointer sites. re-anchor gets ONE sentence in the shared method doc (`context/re-anchor-audit-correct.md` step 3) — all eight skills read it at invocation; per-skill restatement would be the second copy the point-dont-copy discipline prohibits. The `-deep` fan-out skills (do-your-research-deep, recheck-against-upstream-deep) declare deltas replacing step 3 with throttled per-claim fan-outs the single-verdict escalation does not govern — skipped, no contradiction. ## Deliberate skips (audit rows excluded) - `recheck-against-upstream` — doc-source independence dominates model independence at that site. - `session-flow:running-retro` — own-session transcript analysis; cross-model value weak. - Deterministic-gate exemptions (`tidy`, `batch-simplify`, planning design gates) — a script's pass/fail needs no advisor. - naming RETRACTED after Codex review: the codex plugin ships only diff-review surfaces, so a cross-vendor GENERATOR preference is uninstantiable today. Deferred with trigger: a generation-capable cross-vendor adapter ships. ## Method caveat Site list from a fleet sweep (single Explore agent, self-declared completeness caveat) over all plugins for author-verifier / plan-attacker / self-grade delegation sites. Sites the sweep missed are follow-up filings, not silent scope. ## Related - melodic-software/standards#237 / standards PR #238 — the shareable-artifact-design convention doc; a follow-up PR here will point PLUGIN-PHILOSOPHY's generalized doctrine at it (not closed by this PR). - #929 — unrelated open dogfood finding on session-flow; noted only because this PR bumps session-flow to 0.13.1 (no interaction). Closes #933 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Resolve version-collision conflicts with changes that landed on main (#922/#817): - work-items/.claude-plugin/plugin.json: restack version 0.21.1 -> 0.21.3, strictly above main's landed 0.21.2 (avoids a silent version match). - work-items/CHANGELOG.md: preserve main's [0.21.2] and [0.21.1] entries; #818's own entry relabeled to [0.21.3], newest on top. - work-items/skills/triage/SKILL.md: attention-view bucket #2 kept as the dual-axis "Raw marker" wording (both sides made the identical change).

…triage docs + evals (#923) ## Summary The live raw-intake marker is applied on whichever axis a consuming repo files it under — `priority: needs-triage` (the current live label, applied by `.github/workflows/issue-triage-label.yml`) or `status: needs-triage`. `SKILL.md`'s "Scope: raw intake only" section already documents this dual-axis treatment (landed in #802), but several other spots in the same skill, its evals, and reference docs still described or asserted the marker as status-axis-only — a priority-axis label documented as status-only. ## Fix Brought every remaining occurrence in line with #802's already-merged dual-axis wording (`status:needs-triage` / `priority:needs-triage`, whichever axis the repo files it under): - `plugins/work-items/skills/triage/SKILL.md` — Triage-states table (`raw` row) and Attention-view bucket 2, both previously `status:needs-triage` only. - `plugins/work-items/reference/dogfood-filing.md` — step 4 ("Label `needs-triage`, then hand off") previously instructed filers to always `Apply status:needs-triage`; now applies the raw marker on whichever axis the repo files it under, resolved from the live label set. - `plugins/work-items/reference/label-taxonomy.md` and `plugins/work-items/reference/tracker-seam.md` — the axis-grammar tables listed `needs-triage` as a Status-axis example only; added a note that it is dual-axis with a pointer to SKILL.md's "Scope: raw intake only". - `plugins/work-items/skills/triage/evals/evals.json` — evals 4 and 5 asserted "clears `status:needs-triage`" without acknowledging the marker's dual-axis nature; reworded to "clears the raw-intake marker (here `status:needs-triage`)" so the assertion doesn't imply that's the only valid axis. - Version bump `work-items` `0.21.0` → `0.21.1` + matching `CHANGELOG.md` entry. No routing logic changed — this is a doc/eval consistency fix matching an already-ratified decision. ## Verification - `skill-quality:check` static contract gate (18 checks) over the `triage` skill: **PASS — 0 errors, 1 warning** (pre-existing "no Gotchas surface" warning, unrelated to this change). All 9 base-ref trigger phrases preserved; markdownlint clean. - `check-jsonschema` against the bundled `evals.schema.json`: `ok -- validation done`. - Manually cross-checked every edit against PR #802's diff to confirm the dual-axis phrasing (`status:needs-triage` / `priority:needs-triage`, whichever axis the repo files it under) is reused verbatim, not reinvented. - Confirmed the live label is priority-axis via `.github/workflows/issue-triage-label.yml` ("Applies the `priority: needs-triage` floor label..."). Closes #818 ## Related - #818 — this fix. The issue body already carries a ratified/defaulted decision (dual-axis treatment, maintainer-vetoable alternative was single-canonical-axis migration — not implemented here per the issue's explicit instruction), satisfying rule 4d's citation requirement. - #802 — the ratifying source for the dual-axis wording; this PR's phrasing is copied verbatim from its already-merged "Scope: raw intake only" section. - **Version-bump collision with PR #922 (issue #817):** #922 also bumps `work-items` `0.21.0` → `0.21.1` and touches `SKILL.md`'s state-machine/attention-view sections — the same lines this PR's dual-axis fix touches, since the marker lives in those sections. Both PRs are currently open against the same `0.21.0` base. Opening this PR as **draft + `do-not-merge`** until the version numbers and any overlapping `SKILL.md` lines are reconciled by whoever merges second (normal git-merge conflict resolution, per the collision-serialization protocol). - PR #853 (issue #820, unrelated) also touches `work-items/plugin.json` and `CHANGELOG.md` with a stale bump (`0.19.0` → `0.20.1`, already behind current `origin/main`) — noted for visibility, not a live collision with this change. Claude-Session: https://claude.ai/code/session_01K1V3gkrfSf75isB8MiDy3o

kyle-sexton added the automated Opened by automation. label Jul 22, 2026

This was referenced Jul 22, 2026

ops: loop-lane telemetry — running per-lane status (babysit / triage / work) #502

Open

docs(work-items): canonicalize raw-intake marker as dual-axis across triage docs + evals #923

Merged

kyle-sexton marked this pull request as ready for review July 22, 2026 00:55

kyle-sexton merged commit ed6d829 into main Jul 22, 2026
28 checks passed

kyle-sexton deleted the docs/817-triage-skill-doc-sync branch July 22, 2026 02:55

kyle-sexton added a commit that referenced this pull request Jul 22, 2026

Merge origin/main into feat/933-advisor-escalation

5e19ad8

work-items CHANGELOG: both sides released 0.21.1 — main's #922 keeps it; this branch's advisor entry moves to 0.21.2 with the matching plugin.json bump.

kyle-sexton mentioned this pull request Jul 22, 2026

feat: prefer a cross-vendor advisor at fresh-eyes checkpoint sites fleet-wide #934

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(work-items): sync triage SKILL attention-view + state machine with live labels#922

docs(work-items): sync triage SKILL attention-view + state machine with live labels#922
kyle-sexton merged 1 commit into
mainfrom
docs/817-triage-skill-doc-sync

kyle-sexton commented Jul 22, 2026

Uh oh!

claude Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

claude Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

claude Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

claude Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

kyle-sexton commented Jul 22, 2026

Summary

Fix

Verification

Related

Uh oh!

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

Uh oh!

PR #922 Review — docs(work-items): sync triage SKILL attention-view + state machine with live labels

Summary

SKILL.md — Attention-view bucket 2

SKILL.md — Side-exits sentence and ASCII diagram

SKILL.md — Raw-state table (intentionally unchanged)

CHANGELOG.md

plugin.json

Verdict

Uh oh!

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

Uh oh!

Security Review — PR #922

Uh oh!

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

Uh oh!

Security Review — PR #922

Uh oh!

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

Uh oh!

PR #922 Review — docs(work-items): sync triage SKILL attention-view + state machine with live labels

Summary

SKILL.md — Side exits sentence

SKILL.md — ASCII diagram

SKILL.md — Attention-view bucket 2

SKILL.md — Raw-state table (intentionally unchanged)

CHANGELOG.md

plugin.json

Verdict

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

claude Bot commented Jul 22, 2026 •

edited

Loading

`SKILL.md` — Attention-view bucket 2

`SKILL.md` — Side-exits sentence and ASCII diagram

`SKILL.md` — Raw-state table (intentionally unchanged)

`CHANGELOG.md`

`plugin.json`

claude Bot commented Jul 22, 2026 •

edited

Loading

claude Bot commented Jul 22, 2026 •

edited

Loading

claude Bot commented Jul 22, 2026 •

edited

Loading

`SKILL.md` — Side exits sentence

`SKILL.md` — ASCII diagram

`SKILL.md` — Attention-view bucket 2

`SKILL.md` — Raw-state table (intentionally unchanged)

`CHANGELOG.md`

`plugin.json`