analyze-issue

Analyze Issue

Objective

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:

• Do not keep editorial markers such as "Add New Section" or "Add Before ...".
• Section names must describe stable workflow behavior, not editing intent.

Execution Boundary

Default mode is analysis-only:

• Do not modify repository files or submit code changes.
• Do not provide patch-ready implementation content unless the user explicitly asks for implementation.
• If implementation is requested, finish issue analysis first and explicitly state that execution has switched from analysis mode to implementation mode.

Source Policy

Use only the following sources:

• Apache ShardingSphere official documentation.
• Apache ShardingSphere official repository code and tests.
• Target GitHub issue content (body, comments, and linked PRs in the same repository).
• Same-repository GitHub issues/PRs needed to verify a duplicate or prior fix relationship.

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:

1. Can the behavior be reproduced with version + mode + SQL + config + log evidence?
2. Is the expected behavior explicitly documented in official ShardingSphere docs?
3. Do repository code/tests confirm a mismatch with the documented expectation?

Triage decision:

• Mostly Q&A -> Question
• Misconfigured or unsupported usage -> Misunderstanding / Invalid Usage
• Reproducible mismatch between expected and actual behavior -> Bug
• Intended new capability or behavior evolution -> Enhancement
• Same root cause already fixed or tracked by an earlier issue/PR -> Duplicate

Duplicate / Prior Fix Check

Before finalizing Bug or Enhancement, check whether the same root cause has already been fixed or tracked in the Apache ShardingSphere repository:

1. Search by the issue's error message, exception class, key SQL token, affected class/method, and module labels.
2. Use same-repository evidence only: target issue links/comments, GitHub issues/PRs in apache/shardingsphere, git log --grep, git log -S, and relevant file history.
3. If the current upstream target branch, normally apache/master, or the release branch matching the reporter's version already contains an explicit fix, identify the fixing PR or original tracked issue whenever possible.
4. Record the fixing PR number, merge state, merge commit, linked issue, target milestone/version, and changed module/class evidence when available.
5. If a fixing PR or original issue is found and covers the same root cause, classify the new issue as Duplicate instead of a fresh Bug or Enhancement.
6. If the current upstream target branch appears fixed but no fixing PR/issue can be identified after a reasonable search, say already fixed on the current upstream target branch and keep the primary type as Bug or Enhancement as appropriate.

Before classifying an issue as Duplicate, check the evidence against at least one relevant counterexample or negative scenario:

1. Same error message but different affected class, SQL token, configuration, or call path -> do not classify as Duplicate.
2. Same symptom but the fixing PR is not merged into the upstream target branch -> do not say already fixed; classify as Bug, Enhancement, or Needs More Info as appropriate.
3. Same root cause fixed on the upstream target branch but not available in the reporter's release version -> state the fixed branch/version clearly and ask the reporter to verify with a version that includes the fix.
4. Same linked issue/PR exists but does not cover the same trigger condition and root-cause chain -> do not close as duplicate.

For Duplicate, the maintainer reply should link the original PR/issue, recommend type: duplicate, and close as duplicate unless the reporter can still reproduce on a version that includes the fix.

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.
2. Use the canonical URL: https://github.com/apache/shardingsphere/issues/${issueNO}.
3. Try normal browsing first.
4. If normal access fails, use curl fallback:

curl -L -sS "https://github.com/apache/shardingsphere/issues/${issueNO}"

5. If structured data is needed, use the GitHub API:

curl -sS -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/apache/shardingsphere/issues/${issueNO}"

Minimum Evidence Package

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
• Related YAML / DistSQL config
• Expected result vs actual result
• Error stack trace and key log snippet

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 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 only when topology affects classification. Mention topology in the default maintainer reply only when it changes the supportability decision.

Analysis Method (Classify First)

1. Confirm the reported behavior from issue body and comments.
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
   • Duplicate
   • Enhancement
5. If behavior changes are needed, explain scope and compatibility impact.

Always complete root-cause analysis before recommendations.

Evidence Method

For every issue, keep an internal evidence ledger:

1. Distinguish Observation (directly observed) from Inference (reasoned).
2. Mar

---

Content truncated.