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 ---

6 # Issues

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.

12 ## Read

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.

18 ## Write

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`.

39 ## Relations

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:

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.

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

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.

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

60 This example creates an issue:

62 ```sh

63 git bug bug new --non-interactive -t 'Decide the root wake interval' \

64 -m "$(cat body.md)"

65 ```