Every xOne issue uses the same 13 headings in the same order. Each issue states the deliverable, the reason, the exact brief for whoever implements it, and the checks that close it. On 2026-11-15, all 383 xOneRS issues with the gap-audit label have the 13 headings, in order.

This post explains each section with the rule from the repository and an excerpt from a real issue. For how the gaps are found, see how xOne tracks feature gaps.

Where is the issue format defined?

The format is in docs/process/issue-format.md in xOneTS, xOnePy and xOneC. These three repositories are private. xOneRS has no copy of the file on main, and its issues use the same headings.

The file says: "The headings are exact. The order is fixed. Do not skip a heading." It also sets a language rule: use at most 20 words in a sentence, use the active voice, and do not use "should". An issue may end with a hidden marker line. Keep it verbatim, and add none if the issue has none.

## What          ## Why           ## 80% of the way to   ## ASD-STE100
## Diagrams      ## Images        ## Prompt              ## Workflow
## Loop          ## Graph         ## Layout              ## Flow
## Summary

What do What, Why, 80% of the way to and ASD-STE100 say?

They state the work, the reason, the target and the operating rules. Examples are from xOneRS#218, a gap issue for a required-block peer check.

  • What. "The deliverable, then its acceptance rows as a list." #218 opens with: "geth-XDC refuses peers that do not have a given hash at a given height (--eth.requiredblocks <n>=<hash>,...)". It ends with checkbox rows, for example: "A peer with a different hash at a required height is disconnected within 15 s (test)."
  • Why. "The reason and the failure that the work prevents." #218 gives its evidence: "5 of the 14 selected competitors have this capability", with a source file for each.
  • 80% of the way to. "The milestone or gate that the issue serves, and what remains after it." In #218 the heading holds five numbered steps with file paths. In xOneRS#820 it lists the end state.
  • ASD-STE100. "Three to six numbered operating instructions that an engineer follows." #218 has four, such as: "The node MUST disconnect a peer that has a different hash at a required height."

What do Prompt, Workflow and Loop say?

They tell the implementer what to do, in which order, and how to check it. The doc defines the Prompt as the full brief: the scope, the inputs and every acceptance row, plus the coding rules, the commit identity and the trailers. The implementer stops after a local commit and reports the hash and the gate output.

  • Prompt. #218 starts: "Implement GAP-0047: Required-block peer check with built-in network anchors". It names the files and gates, and ends with "Hand back in 25 lines or fewer: files changed, tests added, acceptance results." In xOnePy#107 the brief ends: "Re-install the Apothem follower only with the owner's go-ahead."
  • Workflow. "The numbered one-item, one-branch, one-PR steps." #218 lists nine steps, from "Maintainer: confirms priority P1" to "Maintainer: merges".
  • Loop. The doc defines a seven-step develop-verify loop. It starts at "Pick the next spec item" and ends at "Run the gate. Return to step 3 if the gate is red." xOnePy#107 states its own checks: build wheels with tools/build.py, and expect a full stamp. Build with plain uv build, and expect 00000000.

What do Diagrams, Images, Graph, Layout, Flow and Summary say?

They show the shape of the work: three Mermaid diagrams, a file tree, a rule for evidence and a short close.

  • Diagrams. "One Mermaid flowchart of the component or process that the issue touches." #218 uses a sequence diagram of the handshake check.
  • Images. "None. unless the original issue had an image." xOneRS#894 writes "none" and keeps the file and sha256sum -c output as text evidence.
  • Graph. "A Mermaid graph of dependencies: what the item needs and what needs it."
  • Layout. "The files, packages or crates that the work touches, as a tree." #218 lists six paths.
  • Flow. "A Mermaid sequence diagram of the runtime data or control flow of the delivered component." #218 draws a flowchart of the peer check, with the 15 s time-out.
  • Summary. "Two to four sentences." #820 says: "The rollback runbook and ADR-010 name datadir/safety; the node uses datadir/xone/safety."

How closely do real issues follow the template?

The headings match. The content varies. Examples from the issues above:

  • #820's ASD-STE100 section is one paragraph, not a numbered list.
  • #218 uses "80% of the way to" for implementation steps. The doc defines it as a gate or milestone.
  • #894 records a published release binary that does not meet the release gate. It was closed later on 2026-11-15 by a republish helper (PR #1120).
  • xOnePy#107 is open. Its Flow section is one line of arrows, not a Mermaid diagram.

The doc is the rule. A reviewer can compare any issue with its skeleton.

How does an issue get closed?

One PR closes one issue. The xOneRS CONTRIBUTING.md says: "Say Refs #n in a pull request that leaves rows of the issue open. Say Closes #n in the pull request that makes the last row hold."

PR #339 says Closes #218. It merged on 2026-11-14 at 08:31:17 UTC, and #218 closed in the same minute. The PR has a "Choices to review" section. It records a case where the issue text said a missing hash disconnects a peer, while geth-XDC keeps a peer that has not reached the height. The PR follows geth-XDC.

On 2026-11-15, the gap-audit label has 383 issues: 146 open and 237 closed. We counted them with gh issue list -R XDCIndia/xOneRS --label gap-audit --state all --limit 1000 --json state,body. A closed issue does not always mean a shipped feature: see the gap audit post. For the correctness gates that some issues name, see the roadmap gates post and the roadmap.

Frequently asked questions

What are the 13 sections of an xOne issue?

The code block under the first question lists them. The doc says the headings are exact and the order is fixed.

Does every xOneRS gap issue have all 13 sections?

On 2026-11-15, all 383 issues with the gap-audit label have exactly these 13 ## headings, in order.

What is the Prompt section for?

It is the exact brief for whoever implements the issue. It holds the scope, the inputs, every acceptance row and the rules for the work.

Where is the written rule?

In docs/process/issue-format.md in xOneTS, xOnePy and xOneC, which are private repositories. xOneRS has no copy on main.

Sources