Skip to content

Add the issue-priority skill for the Priority issue field - #615

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

polyglotAI-bot wants to merge 2 commits into
masterfrom
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-odbc issues. People and automated triage use the same file. clickhouse-js, clickhouse-cpp and clickhouse-cs have the same skill (ClickHouse/clickhouse-js#1136, ClickHouse/clickhouse-cpp#613, ClickHouse/clickhouse-cs#743), each with reach tiers of its own.

The repo had no AGENTS.md, so this PR adds a minimal one with only the pointer to the skill. If you prefer another place, or no pointer, say so: Claude Code finds .claude/skills/ without it.

The rules:

  • Reach has two parts, the path and the platform. The narrower of the two wins.
    • Path, Core: connect, auth, the HTTP/TLS transport, SQLExecDirect/SQLPrepare/SQLExecute, input parameters, escape sequences, SQLFetch/SQLGetData/SQLBindCol and the common types, column metadata, SQLTables/SQLColumns/SQLGetTypeInfo/SQLGetInfo, diagnostics, both drivers, the MSI. Power BI DirectQuery, the source of most reports since 2024, uses all of these.
    • Path, Common: parameter arrays and data at execution, the other catalog functions, attributes and SQLCancel, the optional DSN parameters, the Windows DSN dialog, SQL that only one application other than Power BI generates, and multithreaded use.
    • Path, Narrow: RowBinaryWithNamesAndTypes, rare types, scrollable cursors, driver logging, building from sources, unsupported server versions.
    • Platform: Windows x64 and Linux x86_64 are Core; macOS and Linux aarch64 are Common; builds that the project does not release are Narrow.
  • Severity, three driver rules:
    • A workaround counts only if the user of the BI tool can apply it.
    • A crash ends the host application.
    • Wrong metadata counts as "wrong data" only when an application then shows or stores wrong values.
  • Modifiers: security with a shown path from untrusted input → Urgent; a regression in the latest release (not a BETA pre-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 clickhouse-odbc-bridge / odbc() / ODBC dictionaries (server code), for root causes in ClickHouse/power-bi-clickhouse, and for questions, CI, or release-process issues.

Decision for a maintainer

The matrix is the same as in the other repos, so any security defect in a Core path is Urgent, also when no attack path from untrusted input is shown. For example, #604 (credentials sent to another host on a redirect) rates Urgent. If you want a lower level for a defect with no shown attack path, change that cell or add a rule in section 2.

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

The rules were applied to 10 open issues, from code and issue text only. Examples:

#595 may be fixed by the libcurl transport in v1.6.0. In that case it can be closed and gets no priority.

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

No driver code changes. The repo has no changelog.

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only additions for triage; no product code, builds, or security-sensitive runtime behavior.

Overview
Adds .claude/skills/issue-priority/SKILL.md, defining how humans and automation set the org Priority field (Urgent–Low) for clickhouse-odbc issues. The skill covers when to skip priority, reach (path vs platform tiers tailored to ODBC surfaces like connect, fetch, Power BI DirectQuery), severity and driver-specific rules (BI workarounds, crashes, metadata), a reach×severity matrix, modifiers (untrusted-input security, latest-release regression, Linear customer links), confidence, and a one-line reason format.

Also adds AGENTS.md with a short note that issue triage should follow that skill. No driver or runtime changes.

Reviewed by Cursor Bugbot for commit 179659a. 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-odbc issues: reach tiers of the driver paths and
platforms, severity, the base-level matrix, modifiers, and confidence.
People and automated triage use the same rules. A new AGENTS.md points to it.

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

@security-ai-gate-reviewer

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

Copy link
Copy Markdown

AI review gate — auto-approved

179659a3a76f 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)

  • 179659a3a76f approved — green: Cursor Bugbot
  • e5cb4d7032ce approved — green: Cursor Bugbot

slabko
slabko previously approved these changes Nov 17, 2026

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

Approved, however, @ccoltx, please take my remarks into consideration.

Comment on lines +35 to +36
(`ClickHouse/power-bi-clickhouse`), for example in the SQL that the
connector generates.

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.

This one is tricky. I would probably still assign a priority to these issues to get the maintainer's attention. Many issues that initially appear to be Power BI issues are actually ODBC-related.

| --------- | ------------ |
| Core | connect (`SQLDriverConnect`, `SQLConnect`, DSN and connection-string parsing of `Url`, `Server`/`Host`, `Port`, `UID`, `PWD`, `Database`, `SSLMode`); authentication (password, `AccessToken`); the HTTP and TLS transport (`driver/http_client.cpp`, `driver/connection.cpp`, the request code in `driver/statement.cpp`); `SQLExecDirect`, `SQLPrepare`, and `SQLExecute` with the default `ODBCDriver2` format; input parameters (`SQLBindParameter`); ODBC escape sequences (`{fn …}`, `{d …}`, `{ts …}`, `{oj …}`, `driver/escaping/`); `SQLFetch`, `SQLGetData`, `SQLBindCol`, and the conversion of common types (integers, `Float32`/`Float64`, `Decimal`, `String`, `FixedString`, `Enum8`/`Enum16`, `Bool`, `UUID`, `Date`, `DateTime`, `DateTime64`, also in `Nullable` and `LowCardinality`); column metadata (`SQLNumResultCols`, `SQLDescribeCol`, `SQLColAttribute`); `SQLTables`, `SQLColumns`, `SQLGetTypeInfo`, `SQLGetInfo`; errors and diagnostics (`SQLGetDiagRec`, `SQLGetDiagField`); the ANSI and the Unicode driver; the Windows MSI installer |
| Common | parameter arrays and data at execution (`SQL_ATTR_PARAMSET_SIZE`, `SQLPutData`, `SQLParamData`); `SQLMoreResults`, `SQLRowCount`; the other catalog functions (`SQLPrimaryKeys`, `SQLStatistics`, `SQLSpecialColumns`, `SQLForeignKeys`, `SQLProcedures`, the privilege functions); statement and connection attributes, timeouts, and `SQLCancel`; the optional DSN parameters (`Compression`, `AutoSessionId`, `HugeIntAsString`, `SqlCompatibilitySettings`, `ClientName`, `VerifyConnectionEarly`, `Timeout`, and the client-certificate parameters `PrivateKeyFile`, `CertificateFile`, `CALocation`); the Windows DSN setup dialog (`driver/platform/win/setup.cpp`); SQL that only one application other than Power BI generates (Excel, Tableau through generic ODBC, SQL Server linked servers, MS Access, Qlik, SSIS, Oracle); one connection or statement used from more than one thread |
| Narrow | the `RowBinaryWithNamesAndTypes` format (experimental, `default_format` in the `Url`); rare types (`Int128` and wider, `Decimal256`, `Array`, `Map`, `Tuple`, `Nested`, `IPv4`, `IPv6`, Geo, `JSON`, `Dynamic`, `Variant`, `Time`, `Time64`); scrollable cursors and positioned operations (`SQLSetPos`, `SQLBulkOperations`, `SQLExtendedFetch`); driver logging (`DriverLog`, `DriverLogFile`); building the driver from sources; a ClickHouse server version that is no longer supported |

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.

I don't think Decimal256 is a narrow path. It should be well supported by the driver, as it may be used by some financial organizations.

| Tier | Platforms |
| ------ | --------- |
| Core | Windows x64 with the Windows driver manager (MDAC/WDAC): the MSI and most BI tools; Linux x86_64 with UnixODBC: the Linux release package, servers, scripts |
| Common | macOS (the macOS release package, Homebrew; UnixODBC or iODBC); Linux aarch64 |

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.

macOS support is very limited at the moment and is mostly relevant to people who develop their own software using the ODBC driver. Almost no other software on macOS can use the driver due to macOS application sandboxing.

Linux aarch64 is not officially supported at the moment (it might work, but it hasn't been verified).

- **A workaround must be one that the user can apply.** A BI tool generates its
own SQL, and its user cannot change it. For a defect in tool-generated SQL,
a workaround counts only if a user of that tool can apply it: a DSN
parameter, a server setting, or another connector mode.

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.

Note: In Power BI, it is not even possible to change a DSN parameter without submitting a new version of the connector to Microsoft and waiting for the lengthy rollout process to complete.


| Severity ↓ / Reach → | Core | Common | Narrow | Satellite |
| ----------------------- | ------ | ------ | ------ | --------- |
| Wrong data or security | Urgent | Urgent | High | Medium |

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.

macOS and Linux aarch64 (Common reach) issues should not be classified as Urgent bugs, given our current level of support for these platforms.

| Wrong data or security | Urgent | Urgent | High | Medium |
| Broken, no workaround | High | High | Medium | Low |
| Workaround exists | Medium | Medium | Low | Low |
| Cosmetic, docs, feature | Low | Low | Low | Low |

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.

In general, I would lower the urgency level for issues with Common reach.

Comment on lines +123 to +125
3. **Customer request in Linear.** The issue links (`linear.app`) a Linear
issue for a customer request: up one level, but never to `Urgent` (`High`
stays `High`).

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.

Aren't these escalations generally handled through a completely different process?

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.

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

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