Skip to content

docs(agents): add the issue-priority skill for the Priority issue field - #1233

Merged
ccoltx merged 11 commits into
mainfrom
polyglot/issue-priority-skill
Nov 18, 2026
Merged

ccoltx merged 11 commits into
mainfrom
polyglot/issue-priority-skill

Conversation

@polyglotAI-bot

@polyglotAI-bot polyglotAI-bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds .claude/skills/issue-priority/SKILL.md: the rules for the org issue field Priority (Urgent, High, Medium, Low) on ch-go issues. People and automated triage use the same file. AGENTS.md (.claude/CLAUDE.md) points to it in a new "Issue triage" section. clickhouse-go gets the same skill in ClickHouse/clickhouse-go#2142; clickhouse-js, clickhouse-cpp, clickhouse-cs and clickhouse-odbc have it too, each with reach tiers of its own.

The rules:

  • Base level = reach tier × severity.
  • Two kinds of users. clickhouse-go uses ch-go proto (buffers, blocks, server packets, the Col* types of its scalar columns) and compress for all its users. For that code, the reach is the higher of the ch-go tier and the tier that the clickhouse-go rules give the clickhouse-go path. Example: a proto.ColDateTime64 decode defect that clickhouse-go reaches through Rows.Scan is Core. clickhouse-go has its own Array, Map, Nullable, LowCardinality and Tuple code, so a defect in ColArr, ColMap, ColNullable, ColLowCardinality or ColTuple reaches only direct ch-go users.
    • Core: ch.Dial and Client.Do with Input/Result; Ping, Close; handshake, password auth, TLS, timeouts, cancellation; *ch.Exception; block encode/decode; compress; the common column types.
    • Common: chpool; ColAuto/Results.Auto; query parameters; settings, query ID, quota key; the progress, profile and log callbacks; external data; ColRaw; IPv4/IPv6 and 128/256-bit integers.
    • Narrow: ColPoint, ColInterval, ColTime/ColTime64, ColBFloat16, ColQBit, ColNothing, ColJSONStr, ColLowCardinalityRaw; ssh; OpenTelemetry; custom dialers; inter-server queries; ProtocolVersion.
    • Satellite: cht, internal/, examples/, _golden/, README.md, .claude/.
  • Impacts: the severity section starts with the four impact classes that every ClickHouse client repository uses: Security, Data integrity, Stability, Performance. The severity rows and the matrix are the same as in the other repos.
  • Modifiers: security with a shown path from untrusted input → Urgent; a regression in the latest vX.Y.Z release → up one level; a customer request linked from Linear → up one level, never to Urgent.
  • No priority for issues that can be closed with no further action, for defects that only a Deprecated: API reaches (for example Query.OnProfileEvent, Query.OnLog), and for questions, CI, or release-process issues.
  • Fixes that clickhouse-go needs: the fix PR says that clickhouse-go needs a ch-go release and a go.mod update.

The link to the clickhouse-go rules file works after ClickHouse/clickhouse-go#2142 merges.

No ch-go issue has a Priority yet. After this merges, the triage job sets it once on the open issues that it already triaged, and on new issues. It never changes a Priority that is already set.

Please check the tiers, in particular whether the paths that only direct ch-go users reach should be one tier lower. Change the tiers or the matrix as you like; the triage job reads this file from main on every run.

Checklist

No code changes, so no tests, no CHANGELOG entry, and no docs changes.

Review changes (2026-11-18)

  • Section 1 starts with a plain definition of reach and of the four tiers.
  • Section 4 has two new modifiers: a panic in library code is at least High; an ingestion defect that stores lost, corrupted, or changed data with no error goes up one level. A query (read) defect that does not panic gets neither.

Vulnerabilities that are not public yet (added 2026-11-18)

New section after "When to set no priority" (team decision): a security issue must not stay public with a description of how to reproduce it. When a reproduction or code inspection confirms a vulnerability that is not public yet (a leak of credentials or data, a value that changes a query, a skipped or weakened TLS or identity check, memory corruption, or input from the application's users that stops the client):

  • it goes into a private GitHub vulnerability report for this repository (private vulnerability reporting is on), never into a public issue, comment, or pull request; the text of a public issue about it is copied into the report first;
  • the public issue gets no Priority: it is closed with a comment that gives no details, and a repository administrator is asked to delete it, because closing does not hide its text;
  • the rules still rate it, and the level and its reason go into the private report as the proposed severity.

The impact Security now also names memory corruption, and says that a hang or a crash that only a hostile server or network causes is Stability (the clickhouse-cpp severity row already said so). Already public vulnerabilities (a published CVE or GHSA) and authentication methods keep a Priority on the issue. Modifier 1 points to the new section. AGENTS.md gets one sentence in its issue-triage part: a vulnerability that is not public yet goes into a private security report, never into an issue or a pull request. Same text in all client repositories. No priority level changes.

Classification skill (added 2026-11-18)

New file .claude/skills/issue-classification/SKILL.md, so that any agent can classify an issue in this repository: the impacts (Security, Data integrity, Stability, Performance), the areas, their boundaries, the test for a vulnerability that is not public yet, and how to write the classification line. Every ClickHouse client repository gets the same text; the section "This repository" at the end holds local changes. Please keep those small, so that the classes mean the same in every client.

The issue-priority skill no longer copies the impact definitions: it points to the classification skill and keeps the reach tiers, the severity rows, the matrix, the modifiers, and the handling of a vulnerability. AGENTS.md points to both skills.

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only changes to agent triage guidance; no runtime or library behavior changes.

Overview
Introduces agent-facing issue triage documentation so people and automation share one rule set for ch-go GitHub issues.

CLAUDE.md gains an Issue triage section that points agents to the new skills and requires unpublicized vulnerabilities to go through private GitHub security reporting, not public issues or PRs.

issue-classification/SKILL.md (new) defines shared impact classes (Security, Data integrity, Stability, Performance), area classes, evidence rules, handling for confirmed-but-unpublished vulnerabilities, and the one-line Classification format.

issue-priority/SKILL.md (new) is the source of truth for the org Priority field (Urgent–Low): when to skip priority, unpublished-vulnerability workflow, ch-go reach tiers (including paths exercised via clickhouse-go), severity matrix, modifiers (untrusted-input security, library panic, ingestion data loss, regression, Linear customer links), confidence, and fix coordination with clickhouse-go. Severity now references the classification skill instead of duplicating impact definitions.

Reviewed by Cursor Bugbot for commit 3570a57. Bugbot is set up for automated code reviews on this repo. Configure here.

Add .claude/skills/issue-priority/SKILL.md: the rules for the org issue
field Priority (Urgent, High, Medium, Low). People and automated triage
use the same file. AGENTS.md points to it in a new Issue triage section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AGENTS.md is a symlink to .claude/CLAUDE.md, so a relative link resolves
differently in the two files. A repo-root path works in both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on d1ec948. Details in the approver's comment on this pull request.

@security-ai-gate-reviewer

security-ai-gate-reviewer Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

AI review gate — auto-approved

3570a572b63d is approved by security-ai-gate-reviewer[bot], an automated identity, not a human. The approval stands on the required AI review: Cursor Bugbot concluded green on this commit and the AI review gate is SUCCESS (its own comment has the verdict), and the change touches no path that requires a human reviewer. It is bound to this commit: a new push dismisses it and the approver re-evaluates.

History (latest 5 heads, newest first)

  • 3570a572b63d approved — green: Cursor Bugbot
  • da00be656c7a approved — green: Cursor Bugbot
  • e00a5421287f approved — green: Cursor Bugbot
  • 9af26c9932f9 approved — green: Cursor Bugbot
  • 319e835ea130 approved — green: Cursor Bugbot

…iority

Review feedback (kavirajk): say in plain words what reach means, rate a
panic at least High, and rate an ingestion defect that stores wrong data
one level up, so that a query defect ranks below both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@polyglotAI-bot

Copy link
Copy Markdown
Collaborator Author

7470314 applies the review feedback from ClickHouse/clickhouse-go#2142 here too, so that the two Go rule files stay the same:

  • Section 1 starts with a definition of reach (how many applications can hit the defect) and of the four tiers.
  • Section 4 has two new modifiers: a panic in library code is at least High; an ingestion defect (Client.Do with Query.Input) that sends lost, corrupted, or changed data with no error goes up one level. A read defect that does not panic gets neither rule.

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on 7470314. Details in the approver's comment on this pull request.

… priority

A security issue must not stay public with a description of how to
reproduce it. A confirmed vulnerability that is not public yet goes to a
private GitHub vulnerability report; the public issue gets no Priority,
and the rating goes into the report as the proposed severity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on dca1d9e. Details in the approver's comment on this pull request.

…y row

Review feedback (Copilot on clickhouse-js#1155, Bugbot on
clickhouse-cpp#613):
- the private-report rule also applies when code inspection confirms the
  vulnerability;
- copy the issue text into the private report, and ask an administrator
  to delete the issue: closing does not hide its text;
- the impact Security names memory corruption, and input from the
  application's users that stops the client; a hang or a crash that only a
  hostile server or network causes is Stability.
AGENTS.md: a vulnerability that is not public yet goes into a private
security report, never into an issue or a pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on 319e835. Details in the approver's comment on this pull request.

Review feedback (Bugbot on clickhouse-js#1155): the private-report rule
accepts a vulnerability that code inspection confirms, but section 2 gave
an impact only when the issue or a reproduction showed it. Section 2 now
also accepts code inspection, as section 5 already does (confidence
MEDIUM).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…server

Security review (ConnectorSec on clickhouse-odbc#615): the exclusion "a
hang or a crash that only a hostile server or network causes" also
covered memory corruption, which a crafted server response causes and
which anyone on the network path can send over plain HTTP. The exclusion
now covers hangs and crashes with no memory corruption only, and a crash
on server data must have memory corruption ruled out by code inspection
before it is rated by its failure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on 9af26c9. Details in the approver's comment on this pull request.

Each ClickHouse client repository gets the same classification skill
(.claude/skills/issue-classification/SKILL.md): the impacts (Security,
Data integrity, Stability, Performance), the areas, the boundaries, the
test for a vulnerability that is not public yet, and how to write the
classification. Any agent can then classify an issue in the repository.
A section "This repository" at the end holds local changes.

The issue-priority skill no longer copies the impact definitions: it
points to the classification skill and keeps the reach tiers, severity
rows, matrix, modifiers, and the handling of a vulnerability. AGENTS.md
points to both skills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ccoltx pushed a commit to ClickHouse/clickhouse-js that referenced this pull request Nov 18, 2026
…ority skill (#1155)

## Summary

Adds a section "Vulnerabilities that are not public yet" to
`.claude/skills/issue-priority/SKILL.md`. A security issue must not stay
public with a description of how to reproduce it (team decision,
2026-11-18). When a reproduction or code inspection confirms a
vulnerability that is not public yet (a leak of credentials or data, a
value that changes a query, a skipped or weakened TLS or identity check,
memory corruption, or input from the application's users that stops the
client):

- it goes into a private GitHub vulnerability report for this repository
(private vulnerability reporting is on), never into a public issue,
comment, or pull request; the text of a public issue about it is copied
into the report first;
- the public issue gets no Priority: it is closed with a comment that
gives no details, and a repository administrator is asked to delete it,
because closing does not hide its text;
- the rules of this skill still rate the vulnerability, and the level
and its reason go into the private report as the proposed severity.

The impact Security now also names memory corruption, and says that a
hang or a crash that only a hostile server or network causes is
Stability. `AGENTS.md` gets one sentence after the issue-priority
pointer: a vulnerability that is not public yet goes into a private
security report, never into an issue or a pull request.

A vulnerability that is already public (a published CVE or GHSA, for
example in a dependency) and an authentication method that does not work
or is missing get a Priority as before. Modifier 1 now points to the new
section in place of "a private channel".

The same text goes into the other client repositories:
ClickHouse/clickhouse-cpp#613, ClickHouse/clickhouse-cs#743,
ClickHouse/clickhouse-odbc#615, ClickHouse/clickhouse-go#2142,
ClickHouse/ch-go#1233. No priority level changes.

No library code changes, so there is no changelog entry. `prettier
--check` passes on the file.

## Classification skill (added 2026-11-18)

New file `.claude/skills/issue-classification/SKILL.md`, so that any
agent can classify an issue in this repository: the impacts (Security,
Data integrity, Stability, Performance), the areas, their boundaries,
the test for a vulnerability that is not public yet, and how to write
the classification line. Every ClickHouse client repository gets the
same text; the section "This repository" at the end holds local changes.
Please keep those small, so that the classes mean the same in every
client.

The issue-priority skill no longer copies the impact definitions: it
points to the classification skill and keeps the reach tiers, the
severity rows, the matrix, the modifiers, and the handling of a
vulnerability. `AGENTS.md` points to both skills.


🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation and agent-triage guidance only; no runtime or library
behavior changes.
> 
> **Overview**
> Introduces a shared **issue-classification** agent skill that defines
impact classes (Security, Data integrity, Stability, Performance), area
classes, evidence rules, and how to write the `Classification`
line—including **memory corruption** under Security and explicit
handling of **confirmed but not-yet-public** vulnerabilities (private
GitHub report only, never in public issues/PRs).
> 
> **Issue-priority** no longer embeds the full impact table; severity
now defers to the classification skill. It adds a **Vulnerabilities that
are not public yet** section (close/delete public issues with no
details, rate severity in the private report) and updates the
untrusted-input modifier to point at that flow.
> 
> **`AGENTS.md`** now directs triage to the classification skill and
repeats that unpublicized vulnerabilities must use private vulnerability
reporting.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8440102. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Polyglot AI <293096396+polyglotAI-bot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

@cursor cursor 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.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 44b9f08. Configure here.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

AI review gate — AI review passed

Clean review from: Cursor Bugbot.

… are vulnerabilities

Review feedback (Bugbot on clickhouse-cpp#613):
- a request to make an operation faster has the impact Performance but
  is a feature request ("Cosmetic, docs, feature"); only a Performance
  defect uses "Workaround exists";
- authentication means how the client takes credentials; a secret that
  leaks is a vulnerability, not authentication;
- a dependency with a published CVE or GHSA uses "Wrong data or
  security" when the client calls the vulnerable code, else it is a
  dependency update; an unpublished dependency vulnerability goes to the
  private report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on e00a542. Details in the approver's comment on this pull request.

… in private

Review feedback (Bugbot on clickhouse-odbc#615): the impact Security and
the priority mapping named only a published CVE or GHSA, so an
unpublished dependency vulnerability had no Security mapping; and the
report to the dependency's maintainers did not say that it must be
private. Both now cover a published or unpublished vulnerability, and the
upstream report goes through the dependency's security policy, never a
public issue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on da00be6. Details in the approver's comment on this pull request.

Review feedback (Bugbot on clickhouse-odbc#615): the classification kept
every unpublished dependency vulnerability private, but the severity rule
rated one in code that the client does not call as a public dependency
update. Now an unpublished one stays private also then; the low level
is only the proposed severity of the private report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@security-ai-gate-reviewer security-ai-gate-reviewer 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.

Auto-approved by the AI review gate on 3570a57. Details in the approver's comment on this pull request.

@ccoltx
ccoltx merged commit 245bf5c into main Nov 18, 2026
28 checks passed
@ccoltx
ccoltx deleted the polyglot/issue-priority-skill branch November 18, 2026 19:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants