git.giacomolli.uk - onechat/blob - .agents/skills/issues/SKILL.md

   1 ---
   2 name: issues
   3 description: Read and write issues with git-bug. Use for any issue work.
   4 ---
   5
   6 # Issues
   7
   8 Issues live in git-bug, inside the Git repository, not in files. The
   9 `overview` issue lists the phases and the open decisions. Run the
  10 commands in the Nix development shell.
  11
  12 ## Read
  13
  14 - List the open issues with `git bug bug status:open`.
  15 - Read an issue and all its comments with `git bug bug show ID` before
  16   you start work on it.
  17
  18 ## Write
  19
  20 - Give the title and the body with `-t` and `-m`. Do not use `-F`: it
  21   drops every line that starts with `#`, so Markdown headings are lost.
  22 - Write the title like a commit subject: 50 characters or fewer, in the
  23   imperative mood, with no final period.
  24 - Write the body in Markdown. State the result for the user, the scope,
  25   and how to check it.
  26 - Add a comment with `git bug bug comment new ID -m TEXT` for progress
  27   that matters: decisions made with the user, measurements, and checks
  28   that could not run.
  29 - When a question to the user is still open at the end of a session, add
  30   it as a comment with the options and your recommendation. Add the
  31   answer as a comment when it comes.
  32 - Give the reason with each decision, so that a later agent does not
  33   undo it.
  34 - Close an issue with `git bug bug status close ID` only when its check
  35   passes.
  36 - Label a phase `phase`, an open question `decision`, and the plan
  37   `overview`, with `git bug bug label new ID LABEL`.
  38
  39 ## Relations
  40
  41 git-bug has no links between issues. Write them as trailers in the last
  42 paragraph of the body, one per line, as in a commit message:
  43
  44 - `Parent: ID` names the issue that this issue belongs to. A child has
  45   one parent.
  46 - `Depends-on: ID, ID` names the issues that must be done first.
  47 - A parent lists the IDs of its children in its body.
  48
  49 `git interpret-trailers --parse` reads the trailers of a body.
  50
  51 Find the issues that relate to an issue with `git bug bug ID`. The
  52 search finds every issue that mentions the ID, so read the trailers of
  53 each match. Do not search for more than one word: git-bug finds issues
  54 that match any of the words, and it reads `Parent:` as a query
  55 qualifier. Nothing checks the trailers. Before you close a parent, make
  56 sure that its children are closed.
  57
  58 Push the issues with `git bug push` when the repository has a remote.
  59
  60 This example creates an issue:
  61
  62 ```sh
  63 git bug bug new --non-interactive -t 'Decide the root wake interval' \
  64   -m "$(cat body.md)"
  65 ```