Skip to content

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

Merged
kyle-sexton merged 5 commits into
mainfrom
docs/818-triage-marker-axis-canonicalize
Jul 23, 2026
Merged

docs(work-items): canonicalize raw-intake marker as dual-axis across triage docs + evals#923
kyle-sexton merged 5 commits into
mainfrom
docs/818-triage-marker-axis-canonicalize

Conversation

@kyle-sexton

Copy link
Copy Markdown
Contributor

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.00.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 fix(work-items): re-key triage scope on state, not authorship (#486) #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

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

…triage docs + evals

SKILL.md's "Scope: raw intake only" section already defines the raw
marker as dual-axis (status:needs-triage / priority:needs-triage,
whichever axis the repo files it under, per #802), but the
Triage-states table, Attention-view buckets, dogfood-filing.md's
filing step, and the label-taxonomy/tracker-seam axis-grammar tables
still described or asserted it as status-axis-only, contradicting the
live label (priority-axis, applied by .github/workflows/issue-triage-label.yml).
Two triage evals asserted the same single-axis behavior.

Brings every occurrence in line with the ratified dual-axis wording
(#818, decision defaulted per #802).

Closes #818
@kyle-sexton kyle-sexton added automated Opened by automation. do-not-merge Hard merge gate: do not merge while applied. labels Jul 22, 2026
@claude

claude Bot commented Jul 22, 2026

Copy link
Copy Markdown

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


Security Review — PR #923

  • Gather PR diff and changed files
  • Review each changed file for security issues
  • Report findings

No security issues found.

All 7 changed files are pure documentation or test fixtures:

File Change type Security surface
plugin.json Patch version bump 0.21.00.21.1 None
CHANGELOG.md Release note entry None
reference/dogfood-filing.md Prose update (dual-axis label wording) None
reference/label-taxonomy.md Table cell text update None
reference/tracker-seam.md Table cell text update + one new ${CLAUDE_PLUGIN_ROOT} link None (see note)
skills/triage/SKILL.md Table/heading text updates None
skills/triage/evals/evals.json Eval prompt/expectation text updates None

${CLAUDE_PLUGIN_ROOT} in tracker-seam.md line 120 — The new link follows the exact same pattern already used in 15+ other cells in that file (lines 112, 114, 122–124, 149, 217, etc.). It is a plugin-bundled documentation template variable, not a shell expansion or remote fetch. No new risk introduced.

evals.json — The changed fields (prompt, expectations) are plain-text test fixtures describing triage scenarios for model evaluation. They contain no executable code and no new external references. The only change is adding (this repo files the raw marker on the status axis) to two prompts to give axis context, and rephrasing clears \status:needs-triage`clears the raw-intake marker (here `status:needs-triage`)` in the expectations — purely semantic clarity.

No workflow files touched, no permission changes, no new dependencies, no new external resource references, no secrets or credentials.

@claude

claude Bot commented Jul 22, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 2m 14s —— View job


PR Review — docs(work-items): canonicalize raw-intake marker as dual-axis

  • Gather context (PR body, changed files list)
  • Read diff and changed files
  • Review SKILL.md changes
  • Review evals.json changes
  • Review reference doc changes (dogfood-filing, label-taxonomy, tracker-seam)
  • Review plugin.json + CHANGELOG.md
  • Post final review findings

Summary

This is a documentation-only consistency fix. Every changed file correctly propagates the dual-axis wording that SKILL.md's "Scope: raw intake only" section already carried since #802. No logic changes, no new features. The changes are internally consistent and cross-file cohesive.

Verdict: ✅ Approved for content — do-not-merge flag appropriate pending #922 collision.


File-by-file notes

plugin.json — version bump 0.21.00.21.1
Patch bump is the right semver tier for a doc-only consistency fix. Acknowledged collision with #922 (which also bumps to 0.21.1 from the same base) — the do-not-merge label is the correct protocol.

CHANGELOG.md
Entry is accurate and well-structured — names every affected file, cites the ratifying source (#802), and states the invariant clearly. Consistent with the existing changelog style.

SKILL.md — two hunks
Both the Triage-states raw row (L48) and Attention-view bucket 2 (L77) now use verbatim phrasing from the "Scope: raw intake only" section — no reinvention. Bucket 2's heading changed from **`status:needs-triage`** to **The raw marker** (with the concrete forms in parentheses), which is a clear improvement: the heading now names the concept rather than a specific axis.

evals.json — evals 4 and 5
The approach is sound: each eval's prompt now pins a specific axis (this repo files the raw marker on the status axis), so the expected_output prose (which still says "removes status:needs-triage") remains accurate within the scenario. The expectations arrays use "here status:needs-triage" as the concrete form — the word "here" correctly signals it's the axis this particular eval uses, not an implied universal. This is a clean pattern for axis-parameterized evals.

One observation (not a blocker): the expected_output for evals 4 and 5 were intentionally left unchanged because the prompts now scope them to the status axis — but if someone reads only the expectations array (which is now axis-agnostic) alongside the unchanged expected_output (which is axis-specific), the asymmetry could be briefly confusing. A brief parenthetical in each expected_output analogous to the prompt's (this repo files the raw marker on the status axis) would make the design choice self-documenting, but this is a minor style nit, not a correctness issue.

dogfood-filing.md — step 4 (L55–L59)
The update correctly replaces the hardcoded Apply status:needs-triage instruction with the dual-axis form resolved from the live label set. The reference to label-taxonomy.md as the resolution source is appropriate.

label-taxonomy.md (L20)
needs-triage was previously listed as a Status-axis example alongside needs-info, needs-decision, and ready — factually wrong given its dual-axis nature. Removing it from the example list and calling it out separately with a cross-reference is correct. The Status cell is now long but consistent with the existing verbosity style of that table.

tracker-seam.md (L120)
Same pattern as label-taxonomy.md, applied to the condensed version of the axis table. Uses ${CLAUDE_PLUGIN_ROOT} in the link, which is correct plugin-form-safe practice.


No blocking issues

  • No hardcoded paths or project-specific values introduced
  • No logic changes — pure documentation consistency
  • Version bump is correctly scoped (patch)
  • All edits are confined to files the PR declares; no drift into unrelated sections

The do-not-merge label and version-collision note in the PR body are the right handling. Once #922 lands (or is resolved), whoever merges second can reconcile the overlapping SKILL.md lines and pick the winning version number in normal conflict resolution.

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

claude Bot commented Jul 22, 2026

Copy link
Copy Markdown

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


Security Review — PR #923

  • Gather PR diff and changed files
  • Review each changed file for security issues
  • Report findings

No security issues found.

All 7 changed files are pure documentation or test fixtures:

File Change type Security surface
plugin.json Patch version bump 0.21.00.21.1 None
CHANGELOG.md Release note entry None
reference/dogfood-filing.md Prose update (dual-axis label wording) None
reference/label-taxonomy.md Table cell text update None
reference/tracker-seam.md Table cell text update + one new ${CLAUDE_PLUGIN_ROOT} link None (see note)
skills/triage/SKILL.md Table/heading text updates None
skills/triage/evals/evals.json Eval prompt/expectation text updates None

${CLAUDE_PLUGIN_ROOT} in tracker-seam.md line 120 — The new link follows the exact same pattern already used in 15+ other cells in that file (lines 112, 114, 122–124, 149, 217, etc.). It is a plugin-bundled documentation template variable, not a shell expansion or remote fetch. No new risk introduced.

evals.json — The changed fields (prompt, expectations) are plain-text test fixtures describing triage scenarios for model evaluation. They contain no executable code and no new external references. The only change is adding (this repo files the raw marker on the status axis) to two prompts to give axis context, and rephrasing clears \status:needs-triage`clears the raw-intake marker (here `status:needs-triage`)` in the expectations — purely semantic clarity.

No workflow files touched, no permission changes, no new dependencies, no new external resource references, no secrets or credentials.

@claude

claude Bot commented Jul 22, 2026

Copy link
Copy Markdown

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


PR Review — docs(work-items): canonicalize raw-intake marker as dual-axis

  • Gather context
  • Read PR diff
  • Review changed files
  • Post findings

Verdict: ✅ Approved for content — do-not-merge flag is the correct handling for the version collision.

This is a documentation-only consistency fix. All 7 changed files correctly propagate the dual-axis wording (status:needs-triage / priority:needs-triage, whichever axis the repo files it under`) from the already-merged "Scope: raw intake only" section (SKILL.md L35, landed in #802). No logic or routing changes.


File-by-file findings

plugin.json — version bump 0.21.00.21.1
Correct semver tier for a doc-only fix. The collision with #922 (same bump from the same base) is handled appropriately by the do-not-merge label.

CHANGELOG.md
Entry is well-formed, names every affected file, cites the ratifying source (#802), and states the invariant. Style is consistent with existing entries.

SKILL.md — L48, L77
Both hunks use verbatim phrasing from SKILL.md L35 ("Scope: raw intake only") — no reinvention. The Attention-view bucket 2 heading change from **`status:needs-triage`****The raw marker** (with concrete forms in parentheses) is an improvement: the heading now names the concept rather than a specific axis variant.

evals.json — evals 4 and 5
The pattern is sound: prompts now pin the axis (this repo files the raw marker on the status axis), so the expected_output prose — which still says removes status:needs-triage — stays accurate within the scenario. The expectations use "here status:needs-triage" to signal it's the axis this eval uses, not a universal.

One minor nit (non-blocking): the expected_output fields for both evals were not updated to carry the same "here" qualifier as the expectations arrays. Because the prompt now scopes the axis explicitly the expected_output remains correct, but a reader who reads only expected_output without the prompt could momentarily think it asserts status-axis universally — the same ambiguity this PR was written to fix. A small parenthetical like removes status:needs-triage (the status-axis form of the raw marker for this eval) would close it, but this is cosmetic.

Consider adding axis context to expected_output in evals 4 and 5 →

dogfood-filing.md — L55–L59
Correctly replaces the hardcoded Apply status:needs-triage instruction with dual-axis form resolved from the live label set. The reference to label-taxonomy.md as the resolution authority is appropriate.

label-taxonomy.md — L20
Removing needs-triage from the status-axis example list and calling it out as dual-axis with a cross-reference is factually correct and keeps the cell consistent with the updated tracker-seam.md description.

tracker-seam.md — L120
Condensed version of the same label-taxonomy.md clarification. Uses ${CLAUDE_PLUGIN_ROOT} in the link — consistent with the existing pattern used on L112, L114, L122–L124, etc. Correct plugin-form-safe practice.


Pre-existing gap (out of scope, noted for visibility)

SKILL.md L40 (unchanged by this PR) still says the raw marker (\status:needs-triage`, or being unlabeled)` inside the "Never re-triage already-triaged output" rule — only mentions the status axis. This is the same status-axis-only framing this PR was written to fix elsewhere. Worth a follow-up, but it is not introduced by this change.


No blocking issues

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 35defd03db

ℹ️ 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".

Comment thread plugins/work-items/reference/dogfood-filing.md
…, not a second label

On the Priority axis the raw marker must be the item's sole priority value:
pass it as `--priority needs-triage` at `track add` creation so the single-label
priority group replaces the `priority:p3-low` filing default, instead of adding a
second `priority:` label that the GitHub adapter flags as a conflict and that
priority-tier selection cannot resolve. Status axis is unchanged (separate flag,
`priority:p3-low` floor retained).

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6019b4aaa1

ℹ️ 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".

Comment thread plugins/work-items/skills/triage/SKILL.md
@kyle-sexton

Copy link
Copy Markdown
Contributor Author

Automated babysit-lane classification (safe tier — reply only; not resolving threads/merging).

# Finding Classification Evidence
1 chatgpt-codex-connector P1 — "Replace the default priority when applying the priority raw marker" Fixed commit 6019b4aaa16e — files a priority-axis raw marker as track-add priority instead of a second label, per the review finding

Note: this PR's mergeStateStatus is currently DIRTY/CONFLICTING against main — flagging as a blocker for the human merge pass; safe tier does not resolve merge conflicts.

The "Never re-triage already-triaged output" rule enumerated only the
status-axis form of the raw marker, the lone status-axis-only holdout in
a section whose other predicates (states table, attention view) already
canonicalize it dual-axis. Align it with the whichever-axis form and
qualify the default-priority-label example to the status axis, where the
marker and a default priority: label can coexist — on the priority axis
the marker is priority:needs-triage and replaces that default.
@kyle-sexton

Copy link
Copy Markdown
Contributor Author

🔒 merge-drive lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, worker tier). Will fix clear branch-owned CI/bot findings, defer non-DEFER-FORBIDDEN items with reply+resolve, push, then re-check the merge gate.

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).
@claude

claude Bot commented Jul 22, 2026

Copy link
Copy Markdown

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


PR Review — docs(work-items): canonicalize raw-intake marker as dual-axis

  • Gather PR diff and context
  • Review changed files (including amendment commits 6019b4a and 5ad6273)
  • Report findings

Verdict: ✅ Approved for content — all prior findings resolved. do-not-merge flag remains appropriate for the #922 version collision.

This is a documentation-only consistency fix across 7 files. The two amendment commits (6019b4a, 5ad6273) cleanly resolve the P1 and P2 findings from the Codex review. No new issues found.


Amendment commits verified

6019b4a — Priority-axis raw marker filed as track add priority (P1 fix)

dogfood-filing.md L55–L68 now correctly splits application by axis:

  • Priority axis: passes --priority needs-triage on the step-3 track add call, replacing the priority:p3-low default — no two-label conflict.
  • Status axis: applies the marker as a separate post-creation label; priority:p3-low floor stays.

The explanation explicitly names the invariant being protected ("two priority: labels is a conflict the GitHub adapter flags and later priority-tier selection cannot resolve"). Correct.

5ad6273 — SKILL.md L40 scope predicate dual-axised (P2 fix)

SKILL.md L40 now reads the raw marker ('status:needs-triage' / 'priority:needs-triage', whichever axis the repo files it under) or being unlabeled — matching L35/L48/L78. The default-priority:-label example is qualified to the status axis (filed on the status axis with a default 'priority:' label), which is the only valid combination (on the Priority axis the marker is priority:needs-triage and coexistence with priority:p3-low is prohibited). Logic is tight.


Full change set — no new issues

File Change Assessment
plugin.json 0.21.00.21.1 Correct semver tier for doc-only fix
CHANGELOG.md 0.21.1 entry Accurate; names all affected files; cites #802 and the P1 fix
SKILL.md L40, L48, L78 All dual-axised All 4 occurrences in scope now consistent with L35 anchor
evals.json evals 4 & 5 Prompts pin axis; expectations use "here status:needs-triage" Pattern is sound — scenarios are scoped to status axis, assertions accurate within scope
dogfood-filing.md step 4 Dual-axis, axis-split application instructions P1 resolved; cross-reference to track add "Build labels list" is the right authority
label-taxonomy.md L20 needs-triage removed from Status examples; dual-axis callout added Correct
tracker-seam.md L120 Same correction; ${CLAUDE_PLUGIN_ROOT} link follows existing pattern Correct

Pre-existing nit (not blocking, not introduced here)

Evals 4 and 5 expected_output fields still say removes status:needs-triage without the "here" qualifier that the expectations arrays now carry. Since the prompt pins the axis explicitly, the expected_output is correct for the scenario — the asymmetry is cosmetic. This was noted in earlier reviews; no action needed here.


Blockers (unchanged)

No new blockers introduced by the amendment commits.

@claude

claude Bot commented Jul 22, 2026

Copy link
Copy Markdown

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


Security Review — PR #923

  • Gather PR diff and changed files
  • Review each changed file for security issues
  • Report findings

No security issues found.

All 7 changed files are pure documentation or test fixtures. Security surface by file:

File Change type Security surface
plugin.json Patch version bump 0.21.00.21.3 None
CHANGELOG.md Release note entry None
reference/dogfood-filing.md Prose update — dual-axis label wording + priority-axis --priority needs-triage arg instruction None (see note 1)
reference/label-taxonomy.md Table cell text update — needs-triage noted as dual-axis None
reference/tracker-seam.md Table cell text update + ${CLAUDE_PLUGIN_ROOT} cross-reference link None (see note 2)
skills/triage/SKILL.md Table/heading text updates + L40 scope predicate dual-axed None
skills/triage/evals/evals.json Eval prompt/expectation text updates None

Note 1 — dogfood-filing.md L61–64, --priority needs-triage instruction. Step 4 now instructs the model to pass --priority needs-triage as a CLI argument on the Priority axis. The value needs-triage is a hardcoded, known-safe label name — not derived from user input — so no command injection surface is introduced. The instruction is documentation for an AI model to follow, not a shell script.

Note 2 — ${CLAUDE_PLUGIN_ROOT} in tracker-seam.md L120. The new cross-reference link uses the same plugin-bundled template variable pattern already present on L112, L114, L122–L124 of that file. This is a documentation link resolved at plugin load time, not a shell expansion or remote fetch. No new risk introduced.

No workflow files touched, no permission changes, no new external dependencies or resource references, no credentials or secrets, no pull_request_target / workflow_run patterns, no action or dependency pin changes.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bf10e9ca8b

ℹ️ 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".

Comment thread plugins/work-items/reference/dogfood-filing.md
@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Jul 23, 2026
Resolve CHANGELOG version collision: main landed 0.21.3 (#975), so this
branch's #818 raw-intake dual-axis canonicalization restacks to 0.21.4.
Bump plugins/work-items/.claude-plugin/plugin.json to 0.21.4 to match.
@claude

claude Bot commented Jul 23, 2026

Copy link
Copy Markdown

Claude encountered an error after 0s —— View job


I'll analyze this and get back to you.

@claude

claude Bot commented Jul 23, 2026

Copy link
Copy Markdown

Claude encountered an error after 0s —— View job


I'll analyze this and get back to you.

@github-actions

Copy link
Copy Markdown

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

Re-running the job, or pushing a new commit, will retry the review.

@github-actions

Copy link
Copy Markdown

Warning

Automated security review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

Re-running the job, or pushing a new commit, will retry the review.

@kyle-sexton
kyle-sexton merged commit 17faf2a into main Jul 23, 2026
25 checks passed
@kyle-sexton
kyle-sexton deleted the docs/818-triage-marker-axis-canonicalize branch July 23, 2026 07:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automated Opened by automation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

work-items/triage: canonicalize raw-intake marker axis across SKILL, evals, reference docs

1 participant