Skip to content

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

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

ccoltx merged 10 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 clickhouse-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-js, clickhouse-cpp, clickhouse-cs and clickhouse-odbc have the same skill (ClickHouse/clickhouse-js#1136, ClickHouse/clickhouse-cpp#613, ClickHouse/clickhouse-cs#743, ClickHouse/clickhouse-odbc#615), each with reach tiers of its own. ClickHouse/ch-go#1233 adds it to ch-go.

The rules:

  • Base level = reach tier × severity. The reach is the tier of the most-used public path that reaches the defect. The native interface and database/sql share the connection and column code, so a column defect has the tier of its type through both.
    • Core: clickhouse.Open (Query, QueryRow, Select, Exec, PrepareBatch, Ping) and the database/sql driver over the native protocol; dial, pool, timeouts, cancellation; password auth and TLS; Options and DSN parsing; errors; query parameters and binding; struct mapping; the common column types (integers up to 64 bits, floats, Bool, String, FixedString, dates and DateTime64, Decimal, UUID, Enum, Nullable, LowCardinality, Array, Map, Tuple).
    • Common: the HTTP protocol; compression; Batch.Column; failover (ConnOpenStrategy); the context options (WithSettings, WithQueryID, progress, logs, profile events); async insert through settings; Logger; JSON, IPv4/IPv6, 128/256-bit integers, Nested, SimpleAggregateFunction.
    • Narrow: Geo, Variant, Dynamic, Time/Time64, BFloat16, QBit, Interval; external data; QueryFormat/InsertFormat (experimental); JWT; OpenTelemetry; custom dialers; the HTTP proxy; rarely used context options.
    • Satellite: examples/, benchmark/, the test helpers, docs/, README.md, TYPES.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 Conn.AsyncInsert, WithAsync), and for questions, CI, or release-process issues.
  • Root cause in ch-go: the priority comes from the clickhouse-go path. The section says that the fix needs a ch-go release and a go.mod update.

No clickhouse-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: which paths you consider Core and Common is the main input. 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 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 skills and CLAUDE.md; no runtime or library behavior is modified.

Overview
Adds two new agent skills under .claude/skills/ so humans and automated triage share the same rules for clickhouse-go GitHub issues.

Issue classification (new issue-classification/SKILL.md) defines standard impact classes (Security, Data integrity, Stability, Performance) and area classes, evidence-based classification rules, how to label confirmed-but-unpublished vulnerabilities (private report only), and the one-line Classification format.

Issue priority (new issue-priority/SKILL.md) is the source of truth for the org Priority field (Urgent–Low): when to leave priority unset, handling of non-public vulnerabilities on public issues, clickhouse-go-specific reach tiers (Core/Common/Narrow/Satellite mapped to public APIs and column types), severity × reach matrix, modifiers (untrusted-input security path, library panic, silent ingestion data loss, release regression, Linear customer links), confidence, and ch-go root-cause notes. Severity now references the classification skill instead of duplicating impact definitions.

.claude/CLAUDE.md gains an Issue triage section linking both skills and stating that undisclosed vulnerabilities must use GitHub private security reporting, not public issues or PRs.

Reviewed by Cursor Bugbot for commit b91f765. 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 4e89653. 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

b91f7655b595 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)

  • b91f7655b595 approved — green: Cursor Bugbot
  • ceca59708255 approved — green: Cursor Bugbot
  • f6e32746c354 approved — green: Cursor Bugbot
  • 3916111fc1f3 approved — green: Cursor Bugbot
  • 5bbb357ec8fd approved — green: Cursor Bugbot

Comment thread .claude/CLAUDE.md Resolved
Comment thread .claude/skills/issue-priority/SKILL.md Resolved
Comment thread .claude/skills/issue-priority/SKILL.md Resolved
Comment thread .claude/skills/issue-priority/SKILL.md Resolved
…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>

@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 629bee1. 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>
…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 5bbb357. 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 3916111. 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>

@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 f6e3274. Details in the approver's comment on this pull request.

… 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 ceca597. 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 b91f765. Details in the approver's comment on this pull request.

@ccoltx
ccoltx merged commit 78db61a into main Nov 18, 2026
16 checks passed
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.

3 participants