This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 341f9f69da4 Update analyze issue skill (#38731)
341f9f69da4 is described below
commit 341f9f69da4f7e823dce6d2e1c0467b085827661
Author: Liang Zhang <[email protected]>
AuthorDate: Wed May 27 19:29:45 2026 +0800
Update analyze issue skill (#38731)
* Update analyze issue skill
* Update analyze issue skill
---
.codex/skills/analyze-issue/SKILL.md | 291 ++++++++++++++++++-------
.codex/skills/analyze-issue/agents/openai.yaml | 4 +-
2 files changed, 214 insertions(+), 81 deletions(-)
diff --git a/.codex/skills/analyze-issue/SKILL.md
b/.codex/skills/analyze-issue/SKILL.md
index e5f58c94379..b10090e02cf 100644
--- a/.codex/skills/analyze-issue/SKILL.md
+++ b/.codex/skills/analyze-issue/SKILL.md
@@ -2,9 +2,9 @@
name: analyze-issue
description: >-
Used to analyze Apache ShardingSphere community issues. Emphasizes
root-cause-first
- and evidence-first analysis with issue-type classification before
conclusions, and
- outputs traceable results plus label recommendations in a fixed four- or
five-section
- structure.
+ and evidence-first classification before conclusions, and by default produces
+ copy-ready GitHub issue replies in the voice of an Apache ShardingSphere
+ community maintainer followed by reference analysis for traceability.
---
# Analyze Issue
@@ -14,6 +14,36 @@ description: >-
Provide a consistent, traceable, and reviewable issue analysis workflow.
Prioritize identifying the real root cause and aligning with official
ShardingSphere conventions.
+## Default Output Contract
+
+Default to a two-part, copy-ready GitHub issue comment:
+1. **Maintainer Reply:** A concise Apache ShardingSphere maintainer reply
written directly to the issue author.
+2. **Reference Analysis:** A detailed evidence-based analysis appended after
the reply for reviewers, maintainers, and follow-up contributors.
+
+The default maintainer reply must:
+- Start by addressing the issue author when the author is known, for example
`Hi @user, thanks for the question.`
+- State the supportability decision in the first paragraph: supported, not
supported, bug, enhancement, invalid usage, duplicate, or needs more
information.
+- Explain the reason from the ShardingSphere project point of view using
official docs, repository code, or issue evidence.
+- Give the next action: correct usage, label/close recommendation, required
missing facts, or PR/design expectations.
+- Read like a community member helping in the issue thread, not an external
analyst summarizing the issue.
+
+After the maintainer reply, add a short bridge sentence before the reference
analysis:
+`The reply above is based on the analysis below; the detailed reasoning is
kept here for reference and follow-up contributors.`
+
+The default reference analysis must:
+- Preserve the detailed four-/five-section structure in `Reference Analysis
Output Structure`.
+- Include evidence IDs, `Issue Type`, `Recommended Labels`, and `Next Action`.
+- Make the maintainer reply traceable without making the opening reply feel
like a report.
+
+## Community Role
+
+For every GitHub-facing response, act as an Apache ShardingSphere community
maintainer or committer-facing reviewer.
+Use direct community language such as `we`, `current ShardingSphere`, `this
configuration is not supported`, and `please configure`.
+Be polite and helpful, but make supportability judgments clearly when evidence
is sufficient.
+
+Do not self-identify as an AI, bot, analyzer, or neutral third party.
+Avoid default third-person phrasing such as `the reporter wants`, `the user
asks`, or `this issue reports` in GitHub-facing maintainer replies.
+
## Document Hygiene
Keep section titles production-ready:
@@ -36,6 +66,17 @@ Use only the following sources:
Do not use blogs, third-party tutorials, or forum posts as evidence.
+## Output Mode Selection
+
+Choose output mode before drafting:
+- **Maintainer Reply + Reference Analysis (default):** Use for requests to
reply to an issue, draft an issue comment, answer a community question,
+ classify an issue, or when the user gives only an issue URL.
+- **Maintainer Reply Only (explicit only):** Use only when the user asks for a
concise reply/comment only, no detailed analysis, or no appendix.
+- **Reference Analysis Only (explicit only):** Use only when the user asks for
detailed analysis only, evidence IDs only, triage report only,
+ root-cause report only, or the fixed four-/five-section structure only.
+
+Internal evidence gathering is always required. In the default output, keep
evidence IDs and report sections in the appended Reference Analysis, not in the
opening maintainer reply.
+
## Fast Triage Gate
Run this 3-question triage first and record a provisional type:
@@ -49,6 +90,17 @@ Triage decision:
- Reproducible mismatch between expected and actual behavior -> Bug
- Intended new capability or behavior evolution -> Enhancement
+## Reasonability Gate
+
+Run this gate before asking for more reproduction details:
+1. Is the request about configuration, usage, rule semantics, SQL support
boundaries, or expected feature behavior?
+2. Do official docs or repository code already define the behavior boundary
clearly enough?
+3. Would the requested behavior require a new semantic contract rather than
fixing a mismatch?
+
+If the answer supports invalid usage or unsupported behavior, classify as
`Misunderstanding / Invalid Usage` or `Question` and answer directly.
+Do not default to `Needs More Info` only because the issue lacks a full SQL,
database version, or stack trace when the current evidence is already enough to
judge supportability.
+Use `Needs More Info` only when missing facts block the supportability
decision or root-cause classification.
+
## Intake Workflow
1. Identify the issue number from user input.
@@ -69,7 +121,7 @@ curl -sS -H "Accept: application/vnd.github+json" \
## Minimum Evidence Package
-Before root-cause conclusion, verify:
+Before a Bug root-cause conclusion, or when facts are genuinely insufficient
to classify supportability, verify:
- ShardingSphere version and deployment mode (JDBC / Proxy)
- Database type and version
- Minimal reproducible SQL
@@ -77,16 +129,18 @@ Before root-cause conclusion, verify:
- Expected result vs actual result
- Error stack trace and key log snippet
-If any required item is missing, classify as `Needs More Info` and stop short
of definitive root-cause claims.
+If any required item is missing and it blocks classification, classify as
`Needs More Info` and stop short of definitive root-cause claims.
+If docs and code already show the request is unsupported or invalid usage, do
not ask for this package just to complete a checklist.
## Topology Check
-Always record topology before root-cause analysis:
+Always record topology internally before root-cause analysis:
- Access mode: JDBC / Proxy
- Governance mode: Standalone / Cluster
- Registry/config center: ZooKeeper / Etcd / Consul / N/A
-If topology is unknown, lower confidence and request missing info first.
+If topology is unknown, lower confidence only when topology affects
classification.
+Mention topology in the default maintainer reply only when it changes the
supportability decision.
## Analysis Method (Classify First)
@@ -94,30 +148,32 @@ If topology is unknown, lower confidence and request
missing info first.
2. Confirm expected behavior from official docs.
3. Confirm actual behavior from repository code and tests.
4. Classify issue type first:
- - Question
- - Misunderstanding / Invalid Usage
- - Bug
- - Enhancement
+ - Question
+ - Misunderstanding / Invalid Usage
+ - Bug
+ - Enhancement
5. If behavior changes are needed, explain scope and compatibility impact.
Always complete root-cause analysis before recommendations.
## Evidence Method
-For every issue:
+For every issue, keep an internal evidence ledger:
1. Distinguish Observation (directly observed) from Inference (reasoned).
2. Mark inferences explicitly.
3. Every conclusion must bind to at least one traceable source (see Source
Policy).
4. If evidence conflicts, state the conflict explicitly and avoid forced
certainty.
5. Use stable evidence IDs for key statements:
- - `OBS-<n>` for directly observed facts.
- - `INF-<n>` for inferences.
-6. Every `INF` must reference one or more `OBS`.
-7. Every conclusion in `Problem Conclusion` must reference at least one
evidence ID.
+ - `OBS-<n>` for directly observed facts.
+ - `INF-<n>` for inferences.
+6. Every `INF` must reference one or more `OBS` internally.
+7. In the appended Reference Analysis, every conclusion in `Problem
Conclusion` must reference at least one evidence ID.
8. Include source URL/path near each `OBS`.
9. For each key conclusion, output Confidence: High / Medium / Low.
10. If confidence is Low, do not give a hard conclusion; switch to
missing-info request flow.
+In the maintainer reply portion, do not expose the evidence ledger unless it
improves clarity or the user explicitly asks for evidence IDs.
+
## Conflict Resolution Rule
When evidence conflicts, apply this order:
@@ -128,7 +184,7 @@ When evidence conflicts, apply this order:
If docs and code conflict:
- Infer Bug when code violates documented behavior.
- Infer Documentation Gap when code is intentional but docs are
outdated/unclear.
-Always mark this as Inference and cite both sources.
+ Always mark this as Inference and cite both sources.
## Type and Label Recommendation
@@ -149,47 +205,102 @@ If module ownership is unclear, use only type/status
labels first.
For Bug/Enhancement, provide severity and impact scope:
- Severity:
- - `S0`: critical outage or severe data risk
- - `S1`: major functionality blocked
- - `S2`: partial impact with workaround
- - `S3`: minor impact or low-frequency edge case
+ - `S0`: critical outage or severe data risk
+ - `S1`: major functionality blocked
+ - `S2`: partial impact with workaround
+ - `S3`: minor impact or low-frequency edge case
- Impact scope:
- - single SQL / single module / single database / cross-module /
cross-database
+ - single SQL / single module / single database / cross-module /
cross-database
## Response Strategy by Type
-Type-specific rules:
+Default to maintainer replies shaped by the issue type:
+
1. Question
-- Answer directly and provide verifiable evidence.
-- Use the four-section structure (see Mandatory Output Structure).
+- Answer directly in community voice.
+- Briefly cite the relevant docs/code behavior when needed.
+- Invite community members to share related experience, confirmations,
alternative usage examples, or documentation improvements when appropriate.
+- Avoid making questions look like only maintainers may respond.
+- Recommend `type: question` and a close/follow-up action when appropriate.
2. Misunderstanding / Invalid Usage
-- Clearly identify the misunderstanding or misuse.
-- Explain why (documentation constraints, code behavior, or configuration
facts).
-- Use the four-section structure (see Mandatory Output Structure).
-
-3. Bug / Enhancement
-- Provide code-level design suggestions (module boundaries, key classes, test
scope, compatibility).
-- Invite community contributors to submit PRs (including code and tests).
+- State clearly that the usage/configuration is not supported by current
ShardingSphere.
+- Explain the violated rule, semantic boundary, or unsupported assumption.
+- Provide the correct usage when available.
+- Recommend `type: question` and `status: invalid`.
+- Do not ask for more reproduction details when docs/code already prove the
usage is unsupported.
+
+3. Bug
+- Acknowledge the likely bug and summarize the verified mismatch.
+- Name affected module(s), key class(es), compatibility scope, and required
test scope.
+- Invite a PR with code and tests if appropriate.
+- Recommend `type: bug` plus module/database labels.
- Do not provide temporary workarounds.
-- Use the five-section structure (see Mandatory Output Structure).
-- Add a mandatory regression scope subsection covering:
- - Affected modules
- - Compatibility impact (API/config/behavior)
- - Required test scope (unit/integration/e2e boundaries)
- - Backward-compatibility notes and rollback hint
-- Add a mandatory compatibility checklist:
- - Behavior compatibility
- - Configuration compatibility
- - API/SPI compatibility
- - SQL compatibility (dialect/version scope)
-- If incompatibility exists, document migration note and rollback hint.
-
-## Mandatory Output Structure
-
-### GitHub Issue Markdown Requirements
-
-- Format every issue analysis as GitHub-flavored Markdown that can be pasted
directly into a GitHub issue comment.
+
+4. Enhancement
+- Acknowledge the requested behavior as new or changed capability.
+- Explain design questions, compatibility impact, and expected tests before
accepting implementation.
+- Invite community contribution when suitable.
+- Recommend `type: enhancement` and optionally `status: volunteer wanted`.
+
+5. Needs More Info
+- Ask only for facts that block classification or root-cause judgment.
+- Use one concise consolidated list and set a 7-14 day follow-up window.
+- Recommend `status: need more info`.
+
+For the default appended Reference Analysis, and for explicit Reference
Analysis Only mode, use the detailed four-/five-section structures below.
+
+## Maintainer Reply Templates
+
+Use these as compact shape guides, not rigid text:
+
+Question:
+```markdown
+Hi @user, thanks for the question.
+<Direct answer from current ShardingSphere behavior.>
+<Brief reason from docs/code.>
+Community members are also welcome to share related experience, examples, or
documentation improvements.
+I suggest labeling this as `type: question` and closing it once the answer is
clear.
+```
+
+Misunderstanding / Invalid Usage:
+```markdown
+Hi @user, thanks for the question.
+This configuration is not supported by the current <feature> rule model.
+<Explain the two or three project-level reasons, using `we` / `current
ShardingSphere` language.>
+Please <correct usage>. I suggest closing this as invalid usage / question.
+```
+
+Bug:
+```markdown
+Hi @user, thanks for reporting this.
+This looks like a bug in <module/path> because <documented expected behavior>
does not match <current code behavior>.
+The fix should cover <key classes/paths> and include <test scope>.
Contributors are welcome to submit a PR with code and tests.
+```
+
+Enhancement:
+```markdown
+Hi @user, thanks for the suggestion.
+This is not supported today and should be handled as an enhancement rather
than a bug.
+Before implementation, we need to define <semantic contract>, <compatibility
impact>, and <test scope>. I suggest labeling this as `type: enhancement`.
+```
+
+Needs More Info:
+```markdown
+Hi @user, thanks for reporting this.
+We need a bit more information before we can classify this issue:
+- <blocking fact 1>
+- <blocking fact 2>
+Please provide these details within <7-14 days>. If there is no update, we may
close this as inactive / invalid due to insufficient information.
+```
+
+## Reference Analysis Output Structure
+
+Use this section for the default appended Reference Analysis and for explicit
Reference Analysis Only mode.
+
+### Reference Analysis Markdown Requirements
+
+- Format the reference analysis as GitHub-flavored Markdown that can be pasted
directly into a GitHub issue comment after the maintainer reply and bridge
sentence.
- The GitHub-facing issue analysis body must not be wrapped in a code fence,
blockquote, XML/HTML container, or plain-text transcript.
- Use the same natural language as the user request for explanatory prose
unless the user explicitly asks for another language.
- Keep the mandatory Markdown structure unchanged regardless of output
language.
@@ -202,22 +313,23 @@ Type-specific rules:
- Prefer bullets over tables. Use tables only for compact status summaries
that remain readable in GitHub's issue comment pane.
- Keep command evidence in inline code or short fenced blocks; avoid long raw
JSON, full logs, or unrendered terminal transcripts.
- Before final output, perform a formatting self-check on the inner
GitHub-facing issue analysis body:
- - The inner GitHub-facing issue analysis body is not wrapped in a code
fence, blockquote, XML/HTML container, or transcript.
- - The inner GitHub-facing issue analysis body contains the required `###`
headings for the selected issue-type template.
- - The inner GitHub-facing issue analysis body contains `Problem Conclusion`
with the required conclusion fields.
- - File references are repo-relative paths with line numbers, not local
absolute paths.
- - Stable section titles, evidence IDs, labels, severity values, and
conclusion field labels remain in English/code form.
+ - The inner GitHub-facing issue analysis body is not wrapped in a code
fence, blockquote, XML/HTML container, or transcript.
+ - The default body starts with a maintainer reply, includes the bridge
sentence, and then contains the required `###` headings for the selected
issue-type template.
+ - The reference analysis contains `Problem Conclusion` with the required
conclusion fields.
+ - File references are repo-relative paths with line numbers, not local
absolute paths.
+ - Stable section titles, evidence IDs, labels, severity values, and
conclusion field labels remain in English/code form.
### Codex Chat Delivery
-- When returning the issue analysis in Codex chat for the user to copy, wrap
the GitHub-facing issue analysis body in a fenced `markdown` code block.
+- When returning the default output in Codex chat, wrap the complete two-part
GitHub issue comment in a fenced `markdown` code block.
+- When returning Maintainer Reply Only or Reference Analysis Only, wrap only
the requested GitHub-facing body in a fenced `markdown` code block.
- The fenced code block is only a chat delivery wrapper; it is not part of the
GitHub-facing issue analysis body.
- Tell the user to copy only the content inside the fenced block.
- Keep any copy instruction outside the fenced block.
- When posting directly to GitHub through an API or tool, submit only the
inner GitHub-facing issue analysis body and do not include the outer fence.
-- Apply the formatting self-check to the inner GitHub-facing issue analysis
body, not to the chat delivery wrapper.
+- Apply formatting self-checks to the inner GitHub-facing body, not to the
chat delivery wrapper.
-Use this GitHub Markdown skeleton for Question and Misunderstanding / Invalid
Usage:
+In Reference Analysis mode, use this GitHub Markdown skeleton for Question and
Misunderstanding / Invalid Usage:
```markdown
### Problem Understanding
@@ -248,7 +360,7 @@ Use this GitHub Markdown skeleton for Question and
Misunderstanding / Invalid Us
- **Next Action:** ...
```
-Use this GitHub Markdown skeleton for Bug and Enhancement:
+In Reference Analysis mode, use this GitHub Markdown skeleton for Bug and
Enhancement:
```markdown
### Problem Understanding
@@ -289,18 +401,8 @@ Use this GitHub Markdown skeleton for Bug and Enhancement:
- **Regression Scope:** ...
```
-Four-section structure (Question, Misunderstanding / Invalid Usage):
-1. Problem Understanding
-2. Root Cause
-3. Problem Analysis
-4. Problem Conclusion
-
-Five-section structure (Bug, Enhancement):
-1. Problem Understanding
-2. Root Cause
-3. Problem Analysis
-4. Code-Level Design Suggestions
-5. Problem Conclusion
+- Reference four-section structure for Question and Misunderstanding / Invalid
Usage: Problem Understanding, Root Cause, Problem Analysis, Problem Conclusion.
+- Reference five-section structure for Bug and Enhancement: Problem
Understanding, Root Cause, Problem Analysis, Code-Level Design Suggestions,
Problem Conclusion.
At the end of `Problem Conclusion`, append:
- `Evidence Confidence: High/Medium/Low`
@@ -315,6 +417,24 @@ For Bug/Enhancement, also append:
- `Compatibility: Behavior/Config/API-SPI/SQL`
- `Regression Scope: ...`
+## Community Voice Guardrails
+
+In the maintainer reply portion:
+- Do not start with `Problem Understanding`, `Root Cause`, `Problem Analysis`,
or `Problem Conclusion`.
+- Do not expose `OBS-*` / `INF-*` evidence IDs unless the user explicitly asks
for evidence IDs in the reply.
+- Do not write from a detached observer perspective such as `the reporter
wants` or `the issue asks`.
+- Do not over-request reproduction details after the Reasonability Gate has
enough evidence to classify unsupported or invalid usage.
+- Do not recommend a PR for invalid usage unless reframed as a clearly
justified enhancement.
+- For questions, invite broader community participation when it can help the
issue author or improve documentation.
+
+Before final output, run this self-check:
+- **Role Check:** The reply reads like a ShardingSphere maintainer answering
in the issue thread.
+- **Audience Check:** The reply addresses the issue author directly when the
author is known.
+- **Decision Check:** The first paragraph states the
supportability/classification decision.
+- **Reason Check:** The explanation is grounded in official docs, repository
code/tests, or issue content.
+- **Traceability Check:** Default output includes the bridge sentence and
appended Reference Analysis.
+- **Action Check:** The reply gives a clear next action, label recommendation,
close recommendation, or PR expectation.
+
## Missing Information Handling
If evidence is insufficient, do not guess. Explicitly list missing details and
request them, for example:
@@ -333,8 +453,9 @@ When classified as `Needs More Info`:
## Documentation and Code Citation Rules
-- Documentation references must include concrete URLs.
-- Code behavior references must include concrete repository paths or class
names.
+- Documentation references in Reference Analysis mode must include concrete
URLs.
+- Code behavior references in Reference Analysis mode must include concrete
repository paths or class names.
+- In the maintainer reply portion, cite only the concise docs/code references
needed to make the community answer trustworthy.
- All references must comply with Source Policy.
If Java examples are included, use fenced `java` code blocks.
@@ -348,15 +469,25 @@ Extended types are valid final classifications when
evidence supports them:
- Out of Scope / Won't Fix
- Security (use responsible security disclosure workflow)
-Each must still follow Mandatory Output Structure and include labels and next
action.
+Each must still include a clear maintainer reply by default, with labels and
next action.
+Default output must also append Reference Analysis. If the user explicitly
requests only one output mode, return only that requested mode.
## Lightweight Lint Recommendation
-Add a local checker (script or CI step) for analysis output quality:
-- Verify required sections exist.
-- Verify required conclusion fields exist.
-- Verify evidence IDs are present and referenced.
-- Verify label format and type-label consistency.
+For default output, verify:
+- The reply addresses the issue author or community directly.
+- The first paragraph contains the decision.
+- The maintainer reply does not contain detailed report headings.
+- The bridge sentence appears before Reference Analysis.
+- The Reference Analysis contains required detailed sections and conclusion
fields.
+- The reply includes a next action and label/close recommendation when
appropriate.
+- For questions, the reply invites community participation when appropriate.
+
+For Reference Analysis output, a local checker (script or CI step) may verify:
+- Required detailed sections exist.
+- Required conclusion fields exist.
+- Evidence IDs are present and referenced.
+- Label format and type-label consistency are valid.
If lint fails, mark analysis as incomplete.
@@ -364,4 +495,6 @@ If lint fails, mark analysis as incomplete.
- Do not recommend behavior that conflicts with official ShardingSphere
conventions.
- Do not provide certainty when evidence is insufficient.
+- Do not output a neutral machine-style report when the user asked for a reply
to an issue author.
+- Do not omit the default Reference Analysis unless the user explicitly asks
for maintainer reply only.
- Source and workaround restrictions are governed by Source Policy and
Response Strategy by Type.
diff --git a/.codex/skills/analyze-issue/agents/openai.yaml
b/.codex/skills/analyze-issue/agents/openai.yaml
index ef1ceaec268..905bff26d16 100644
--- a/.codex/skills/analyze-issue/agents/openai.yaml
+++ b/.codex/skills/analyze-issue/agents/openai.yaml
@@ -17,5 +17,5 @@
interface:
display_name: "Analyze Issue"
- short_description: "Root-cause triage for ShardingSphere issue reports"
- default_prompt: "Use $analyze-issue to analyze this ShardingSphere issue
with a root-cause-first conclusion (analysis only, no code changes)."
+ short_description: "Maintainer replies with traceable issue analysis"
+ default_prompt: "Use $analyze-issue to draft a maintainer reply plus
reference analysis for this ShardingSphere issue (analysis only, no code
changes)."
