Skip to content

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

Open
polyglotAI-bot wants to merge 2 commits into
mainfrom
polyglot/issue-priority-skill
Open

polyglotAI-bot wants to merge 2 commits into
mainfrom
polyglot/issue-priority-skill

Conversation

@polyglotAI-bot

@polyglotAI-bot polyglotAI-bot commented Nov 17, 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-cs issues. People and automated triage use the same file. AGENTS.md points to it in a new "Issue triage" section. clickhouse-js has the same skill (ClickHouse/clickhouse-js#1136), with reach tiers of its own.

The rules:

  • Base level = reach tier × severity. The reach comes from the most-used public path and condition that reaches the defect. A rare type, a non-default setting, or an unusual server setup makes a defect Narrow, also through ClickHouseClient or ADO.NET.
    • Core: the HTTP client with default settings (ClickHouseClient, the ADO.NET API that Dapper, EF Core and linq2db use), connection-string parsing, transport, auth/TLS, errors, parameters, and the common types.
    • Common: raw streams, the JSON type with typed paths, sessions and roles, QueryOptions/InsertOptions, ZSTD, OpenTelemetry and logging, the DI extensions.
    • Narrow: the TCP client (experimental, CHTCP0001), rare types, fixed-offset time zones, rarely used settings, GetSchema/GetSchemaTable, a specific server setup (readonly user, proxy, cluster).
    • Satellite: code outside the package, or a defect that needs two Narrow conditions together.
  • Modifiers: security with a shown path from untrusted input → Urgent; a regression in the latest X.Y.Z release (not -rcN) → 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 an [Obsolete] API reaches (for example ClickHouseBulkCopy), for servers below the support floor, and for questions, CI, dependency, or release-process issues.
  • Both clients: when the HTTP and TCP copies of shared logic both have a defect, the issue gets the HTTP reach, and the reason says that the fix needs both copies.

Impact classes (added 2026-11-17)

The severity section now starts with four impact classes: Security, Data integrity, Stability, and Performance. They are the same in every ClickHouse client repository, so that issues are classified with the same words in each client.

  • Each severity row names the impact that puts an issue in the row.
  • The reason line records the impacts.
  • No priority level changes: each row keeps its conditions.

Calibration against the 5 values that are already set

alex-clickhouse set all 5. These rules give the same value for 3 of them: #438, #439 and #440 are Low. The other 2 are one level higher:

Issue Set These rules Why
#370 Fixed/UTC±HH:MM:SS zone dropped, wall clock shifted Medium High Narrow × silent wrong data
#530 Dynamic/Variant JSON hint + ReadStringsAsByteArrays Low Medium Satellite × silent wrong data

The matrix is the same as in clickhouse-js: silent wrong data on a narrow path gives High. If you prefer your earlier ratings, change two cells in section 3: Narrow × "Wrong data or security" → Medium, and Satellite → Low.

Change the tiers or the matrix as you like. The triage job reads this file from main on every run, and it never changes a Priority that is already set.

No package code changes, so no changelog fragment.

🤖 Generated with Claude Code


Note

Low Risk
Documentation and agent guidance only; no runtime or package behavior changes.

Overview
Adds .claude/skills/issue-priority/SKILL.md as the canonical rules for the org-only Priority issue field on clickhouse-cs. The skill defines when to skip priority, reach tiers (Core → Satellite) tied to public APIs and conditions, impact/severity, the base reach×severity matrix, modifiers (untrusted-input security, release regressions, Linear customer links), confidence, one-line reason format, and how to rate defects that exist in both HTTP and TCP clients.

AGENTS.md gains an Issue triage section that points maintainers and automation at that skill for setting, checking, or explaining priority.

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

The skill gives the rules for the org issue field Priority (Urgent, High,
Medium, Low) on clickhouse-cs issues: reach tiers of the HTTP and TCP
clients, severity, the base-level matrix, modifiers, and confidence. People
and automated triage use the same rules. AGENTS.md points to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 11:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Conflicting scope classifications and overlapping workaround rules can produce inconsistent priorities for session-only failures and missing conversions.

2 open issues
What changed in this PR

Adds a shared policy for people and automated tools to set the organization’s Priority issue field. The policy covers both HTTP and TCP client issues; no package code or runtime behavior changes.

Changes:

  • Defines reach tiers, severity levels, a priority matrix, modifiers, and exclusions.
  • Specifies confidence, reason formatting, and handling of defects shared by both clients.
  • Links the policy from the repository’s issue-triage guidance.
File Description
AGENTS.md Adds an Issue triage section linking to the priority skill.
.claude/​skills/​issue-priority/​SKILL.md Defines the rules for assigning and explaining issue priority.

Review effort: Balanced

Comment on lines +46 to +47
shows only with a rare type, a non-default setting, or an unusual server setup
is Narrow, also when it goes through `ClickHouseClient` or the ADO.NET API.
Comment thread .claude/skills/issue-priority/SKILL.md Outdated
| ----------------------- | -------- |
| Wrong data or security | the client returns or stores wrong or incomplete data with no error, or reports success for a query or insert that failed; or a security defect |
| Broken, no workaround | the feature fails (an exception, a hang, a crash, a stack overflow, a leak that ends in a crash or in exhausted connections), and the caller has no reasonable workaround; also a wrong or incomplete error with no workaround: the failure is reported, but its type, code, or message is wrong or lost |
| Workaround exists | the feature fails, but the caller can avoid the failure with a small change in their own code, for example a cast in SQL, another overload, or another setting (name the workaround in the reason); also a result that is correct but slow or uses too much memory |

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

@security-ai-gate-reviewer

Copy link
Copy Markdown

AI review gate — auto-approved

35f7b7d1050a 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)

  • 35f7b7d1050a approved — green: Cursor Bugbot

The severity section now starts with four impact classes: Security, Data
integrity, Stability, and Performance. They are the same in every ClickHouse
client repository. Each severity row names the impact that puts an issue in
the row, and the reason line records the impacts. No priority level changes:
each row keeps its conditions.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@polyglotAI-bot

Copy link
Copy Markdown
Collaborator Author

I pushed one more commit after the approval: the severity section now names four impact classes (Security, Data integrity, Stability, Performance). The classes are the same in every ClickHouse client repository.

  • Each severity row names the impact that puts an issue in the row, and the reason line records the impacts.
  • No priority level changes: each row keeps its conditions.

The description has a new section "Impact classes" with the same summary.

@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 86419a4. Configure here.


| Severity | Use when |
| ----------------------- | -------- |
| Wrong data or security | impact **Data integrity**: the client returns or stores wrong or incomplete data with no error, or reports success for a query or insert that failed; or impact **Security**: a security defect (a request for an authentication method is a feature request) |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Auth impact conflicts with feature requests

Medium Severity

The Security impact treats a missing authentication method as a security defect, while the Wrong data or security row treats a request for an authentication method as a feature request. Auth is a Core path, so the required impact-first reading yields Urgent instead of Low, and triage never revises a Priority that is already set.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 86419a4. Configure here.

@github-actions

Copy link
Copy Markdown

AI review gate — Cursor Bugbot found issues

  • Cursor Bugbot found issues that are not resolved (check concluded 'neutral').

Unresolved findings (1):

What to do:

  • Fix the findings and push. The reviewer re-reviews the new commit and the gate re-runs by itself.
  • Finding wrong, or reviewer stuck? Ask a human with write access who is not the PR author to approve this exact commit, then re-run the gate. Their approval stands in for the AI review (a new push needs a new approval).

Re-run the gate with “Re-run jobs” after an approval or a finished review. A push re-runs it automatically.

This branch has not been deployed

No deployments
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