Format issue bodies and comments with mdformat

[onechat] / .agents / skills / issues / SKILL.md

---
name: issues
description: Read and write issues with git-bug. Use for any issue work.
---

# Issues

Issues live in git-bug, inside the Git repository, not in files. The
`overview` issue lists the phases and the open decisions. Run the
commands in the Nix development shell.

## Read

- List the open issues with `git bug bug status:open`.
- Read an issue and all its comments with `git bug bug show ID` before
  you start work on it.

## Write

- Give the title and the body with `-t` and `-m`. Do not use `-F`: it
  drops every line that starts with `#`, so Markdown headings are lost.
- Write the title like a commit subject: 50 characters or fewer, in the
  imperative mood, with no final period.
- Write the body in Markdown. State the result for the user, the scope,
  and how to check it.
- Format each body and comment with `mdformat -` in the repository, so
  that it uses `.mdformat.toml`. mdformat joins trailer lines into one
  line, so format the text first and add the trailers after it.
- Add a comment with `git bug bug comment new ID -m TEXT` for progress
  that matters: decisions made with the user, measurements, and checks
  that could not run.
- When a question to the user is still open at the end of a session, add
  it as a comment with the options and your recommendation. Add the
  answer as a comment when it comes.
- Give the reason with each decision, so that a later agent does not
  undo it.
- Close an issue with `git bug bug status close ID` only when its check
  passes.
- Label a phase `phase`, an open question `decision`, and the plan
  `overview`, with `git bug bug label new ID LABEL`.

## Relations

git-bug has no links between issues. Write them as trailers in the last
paragraph of the body, one per line, as in a commit message:

- `Parent: ID` names the issue that this issue belongs to. A child has
  one parent.
- `Depends-on: ID, ID` names the issues that must be done first.
- A parent lists the IDs of its children in its body.

`git interpret-trailers --parse` reads the trailers of a body.

Find the issues that relate to an issue with `git bug bug ID`. The
search finds every issue that mentions the ID, so read the trailers of
each match. Do not search for more than one word: git-bug finds issues
that match any of the words, and it reads `Parent:` as a query
qualifier. Nothing checks the trailers. Before you close a parent, make
sure that its children are closed.

Push the issues with `git bug push` when the repository has a remote.

This example creates an issue:

```sh
body=$(mdformat - < body.md)
git bug bug new --non-interactive -t 'Decide the root wake interval' \
  -m "$body

Parent: 180a674"
```