/gh-issue

name: gh-issue
description: >-
  Size-audit, write, and split BanyanDB issues that somebody else or an
  automated TDD workflow can implement. Use whenever the user asks to file or
  revise an issue, decide whether an issue is too large, make an issue
  TDD-ready, turn a design into tickets, or split an umbrella into executable
  leaves. Do not draft or file an implementation issue before classifying it as
  a mergeable leaf or a tracking parent.
allowed-tools: Bash, Read, Grep, Glob

Writing a BanyanDB Issue

BanyanDB's issues live in the **apache/skywalking** tracker, not in this repository — `apache/skywalking-banyandb` has issues disabled. Label them `database`, which is the component label for BanyanDB.

A good issue is one somebody can implement from **without asking you a question**. That is a higher bar than "clear", and it is the bar that decides whether an issue sits untouched for a year.

Size the work before polishing the issue

Issue length is not issue size. Inspect the design and the relevant production code before drafting. Count independently testable behaviour, integration seams, callers, format families, lifecycle domains, fixture work, and test suites. A short issue that says "replace the index" can be much larger than a long issue that fixes one query operation.

Always produce a short size audit during review, even if it will not appear in the filed body:

## Size audit
Classification: executable leaf | tracking parent
Boundary: <one seam, or the several seams that make this a parent>
Production activation: <the caller switched by this merge>
RED test: <the command and the observable failure on current main>
End to end: <the real operation proved by the merge>
Format/lifecycle scope: <sections or algorithms; read/write/publish/merge/GC/etc.>
Fixtures and oracle: <who supplies expected values independently of the code under test>
Focused suites: <commands>
Dependencies present on main: yes | no — <evidence>
Decision: <fits one run, or the exact split required>

Do not infer the answers only from the proposal. Use repository evidence such as interfaces, call sites, packages, fixtures, and existing tests. Treat line count as supporting evidence, never as the sole sizing rule.

Executable leaf versus tracking parent

An **executable leaf** must satisfy all of these:

• It exposes one agreed boundary and delivers one behaviour end to end.
• The same merge switches at least one named production or CLI caller to it.
• Every requirement has a RED test that fails on current `main` for a stated

reason and passes after the change.

• One focused end-to-end scenario proves the real caller, not just an isolated

codec or helper.

• Expected values and persisted bytes come from an independent oracle.
• Its prerequisites and the seam it builds on are already merged to `main`.
• A contract author can create the boundary and RED tests in one workflow turn,

and an implementer can reasonably complete the production change in the next.

A **tracking parent** describes a milestone, replacement, or multi-PR outcome. It owns completion criteria, the dependency graph, and links to children, but it is not itself an implementation contract. Mark it clearly as a tracking parent and do not put it in an automated implementation queue.

Mandatory split triggers

Classify the issue as a parent or split it before filing when any of these is true:

• It mixes lifecycle domains such as read, write, publish/recovery, merge/GC, or

replication.

• It introduces several independent public seams or several unrelated caller

cutovers.

• It replaces a whole third-party subsystem rather than one observable operation.
• No test can be named that fails on current `main` without asserting private

implementation details.

• It needs the production implementation to generate its own expected fixture

bytes; that is a circular oracle, not a test contract.

• A required boundary exists only in an open or planned PR. Keep the issue as a

parent and decompose it after the blocker merges.

• It is foundation-only: the merge adds format readers, helpers, or abstractions

that no production/CLI path uses.

Use this score as a second check when none of the hard triggers is decisive:

| add | signal | |---:|---| | +2 | each additional public boundary after the first | | +2 | each additional lifecycle domain after the first | | +1 | each additional production caller family | | +1 | each additional persisted format or algorithm family | | +1 | each additional independent fixture family | | +1 | each additional focused package test suite | | +2 | a prerequisite or seam is not yet on `main` |

Score `0–2`: normally a leaf. Score `3–4`: split unless repository evidence shows it is still one small behaviour. Score `5+`: a tracking parent. A hard trigger overrides the score.

For a TDD workflow, also cap a leaf at roughly four observable requirements, one fixture family, one activation point, and one focused end-to-end scenario. These are review budgets, not excuses to hide work by combining requirements.

RED-test feasibility catches false slices

A compatibility-preserving cutover often returns the same result before and after the change, so a new output assertion may pass against the legacy path and is not RED. State why the test fails before implementation. Absence of a new boundary can be a compile-time RED test, but acceptance must also prove that a real caller uses the boundary; do not use brittle source-text assertions as the only proof.

If a fixture is required, include its cost in the size audit. Persisted expected bytes should be generated by an independent legacy/reference writer and checked in with provenance before the native code consumes them. Do not create a fixture-only or codec-only ticket when the project requires every merge to activate production behaviour; put the smallest fixture and decoder beside the first real caller that uses them.

The body is the