Filing GitHub Issues for CockroachDB

File issues on cockroachdb/cockroach using the repo's issue templates and CockroachDB labeling conventions.

Workflow

Step 1: Discover Issue Templates

The repo has issue templates in .github/ISSUE_TEMPLATE/. Blank issues are disabled, so one of these templates must be used:

bug_report.md — Reproducible bugs
feature_request.md — New functionality proposals
performance-inquiry.md — Performance problems

For investigation issues (tracking research/analysis work that doesn't fit the above), use the investigation structure in the Investigation section below instead of a template.

If the issue type is obvious from context (e.g., the user described a bug), pick the matching template without asking. Only ask when ambiguous.

Read the chosen template file to get its structure and required sections.

Step 2: Gather Information

If the user has already provided context (e.g., they described a bug before invoking this skill), use that context to pre-fill sections and confirm rather than re-asking.

Otherwise, ask the user for:

Issue type — Which template fits best
Title — Concise, prefixed with the affected package (e.g., sql/schemachanger: ...)
Body content — Walk through template sections conversationally

Step 3: Discover Available Labels

Query the repo's labels to find the appropriate team and areas for the issue if they aren't already known:

# Search for labels by prefix (T-, A-).
gh label list -R cockroachdb/cockroach --search "<prefix>" --limit 100

Use the label conventions table below to guide which prefixes to search. Match labels to the issue's team and areas. Do not invent labels — only use ones that exist in the repo.

Step 4: Compose and Confirm

Assemble the full issue using the template structure. Show the user a preview of the complete issue (title, labels, and body) and get explicit confirmation before filing.

Step 5: File the Issue

gh issue create -R cockroachdb/cockroach \
  --title "<title>" \
  --label "<labels>" \
  --body "$(cat <<'EOF'
<assembled issue body>
EOF
)"

Display the issue URL after filing.

Investigation Issues

For research/analysis work, don't use a bug report template. Instead, file directly with this structure:

**Summary:**
Brief description of what needs investigation.

**Findings:**
- Finding 1
- Finding 2

**Code References:**
- [file.go:123](https://github.com/cockroachdb/cockroach/blob/master/pkg/path/file.go#L123)

**Next Steps:**
- [ ] Action item 1
- [ ] Action item 2

Use C-investigation as the category label. Do not include bug-report sections like "Steps to reproduce" or "Expected behavior" — they don't apply to investigations.

Label Conventions

Prefix	Purpose	Examples
`T-`	Team owner	`T-sql-foundations`, `T-kv`, `T-storage`, `T-obs`
`A-`	Technical area	`A-sql-optimizer`, `A-sql-execution`, `A-kv-replication`, `A-spanconfig`
`O-`	Origin/discovery	`O-roachtest`, `O-support`, `O-community`
`C-`	Category/type	`C-bug`, `C-enhancement`, `C-investigation`, `C-test-failure`

Always include the O-agent label to indicate the issue was filed via this skill. Apply additional labels from the template frontmatter plus any relevant T-, A-, O-, and C- labels. Ask the user if they want additional labels. Do not assign anyone unless the user explicitly says who to assign.

Jira Epic Association

If the issue should be associated with a Jira epic, add a line at the very bottom of the issue body:

Epic CRDB-12358

This causes the Jira issue (created automatically by automation) to be associated with that epic. Ask the user if there's a relevant epic to link.

Best Practices

Code references: Use GitHub URLs with line numbers: [file.go:123](https://github.com/cockroachdb/cockroach/blob/master/pkg/path/file.go#L123)
Stable references: Include commit SHA in URLs when line numbers may shift.
Correlation evidence: Include timestamped logs for performance issues. Paste excerpts inline.
Content: Use markdown. Be specific about versions, configs, environments. Include repro steps.
No release notes in GitHub issues (release notes are only for PRs and commits).
No Jira footer: Do not add a "Jira issue: CRDB-XXXXX" line. Jira linking is handled automatically by automation after the issue is created.
Confirm before filing: Always show the complete issue and get explicit approval before running gh issue create.

file-crdb-issue