From 1f4a5beed1a883f6b22ed8a0b805290e4e667c07 Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Sun, 12 Jul 2026 14:40:41 +0200 Subject: [PATCH 1/2] Describe issue type and label taxonomy for slicing and triage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The slice-issues skill created sub-issues with only a title and body, so slices had no type and no labels — they could not be filtered or triaged onto a project board without reading each body. architecture-impact defined Epic/UserStory but nothing carried that through to slices or to board-friendly labels. - Add skills/references/issue-labels.md: a reusable type vocabulary (epic/user-story/task/refactoring/bug), the native-type -> type-label -> title-prefix precedence, and independent label dimensions (type, area, optional grouping such as a roadmap phase), keeping workflow status in the board rather than in labels. Includes gh issue create examples with --type/--label/--parent. - slice-issues: require reading the taxonomy, set --type/--label when creating each child issue, and add a slicing rule to type and label every slice. - architecture-impact: point Epic/UserStory marking at the shared taxonomy. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/architecture-impact/SKILL.md | 7 +-- skills/references/issue-labels.md | 70 +++++++++++++++++++++++++++++ skills/slice-issues/SKILL.md | 24 ++++++++-- 3 files changed, 94 insertions(+), 7 deletions(-) create mode 100644 skills/references/issue-labels.md diff --git a/skills/architecture-impact/SKILL.md b/skills/architecture-impact/SKILL.md index a50f065..28f15af 100644 --- a/skills/architecture-impact/SKILL.md +++ b/skills/architecture-impact/SKILL.md @@ -35,9 +35,10 @@ source of truth when these rules evolve. create or update an Epic. If it is small enough for one reviewable slice, create or update a UserStory. If the size is unclear and the decision affects issue structure, ask a short clarifying question before creating the issue. -4. Mark Epics and UserStories in the remote project backlog. Use the - repository's Epic or UserStory issue type, label, or metadata when available; - otherwise prefix the issue title with `[EPIC]` or `[UserStory]`. +4. Mark Epics and UserStories in the remote project backlog following the type + and label taxonomy in `../references/issue-labels.md`. Use the repository's + Epic or UserStory issue type, label, or metadata when available; otherwise + prefix the issue title with `[EPIC]` or `[UserStory]`. 5. Start every Epic and UserStory description with the pattern `As a [Role], I want to [Action], so that [Benefit].` 6. Assign each UserStory to a matching Epic when one exists. Prefer real diff --git a/skills/references/issue-labels.md b/skills/references/issue-labels.md new file mode 100644 index 0000000..d07d039 --- /dev/null +++ b/skills/references/issue-labels.md @@ -0,0 +1,70 @@ +# Issue Type and Label Taxonomy + +Shared guidance for how backlog issues (Epics, UserStories, slices, refactorings) +are typed and labelled so they are easy to find, filter, and classify — for +example when triaging them into a project board. + +This is engine-independent guidance. It is referenced by +`skills/architecture-impact/SKILL.md` (which decides Epic vs UserStory) and +`skills/slice-issues/SKILL.md` (which creates the child slices). A consuming +project adopts the taxonomy that fits its tooling; the toolkit only fixes the +*dimensions* and the precedence, not a project's exact label names. + +## Issue type + +Every backlog issue has exactly one type. Set it with, in order of preference: + +1. A **native issue type** when the platform supports it + (`gh issue create --type `). GitHub issue types are currently an + organization-level feature; personal repositories usually cannot use them. +2. Otherwise a **`type:` label** (see below). +3. Otherwise a **title prefix** as a last resort (`[EPIC]`, `[UserStory]`, + `[REFACTORING]`), as described in `../architecture-impact/SKILL.md`. + +Recommended type vocabulary: + +| Type | Meaning | +|------|---------| +| `epic` | Coordination issue for work too large for one reviewable slice. | +| `user-story` | A reviewable slice of user or stakeholder value. | +| `task` | Technical work with no direct user-facing value (tooling, tests, docs, chores). | +| `refactoring` | Internal change that does not alter observable behaviour. | +| `bug` | Defect in existing behaviour. | + +Epics and UserStories still begin their description with +`As a [Role], I want to [Action], so that [Benefit].` (see +`../architecture-impact/SKILL.md`). Tasks and refactorings use a short goal +statement plus acceptance criteria instead. + +## Label dimensions + +Apply labels along independent dimensions so a board can filter on each: + +- **Type** — `type:epic`, `type:user-story`, `type:task`, `type:refactoring`, + `type:bug` (mirror the native issue type as a label when the board cannot + filter on the native type). Exactly one. +- **Area / domain** — `area:` (for example `area:docs`, `area:testing`, + `area:observability`). One or more; project-defined. +- **Grouping** — an optional project-defined grouping such as a roadmap phase or + a component, expressed as a label (`phase-4`) or a GitHub milestone. Optional. + +Keep **workflow status** (todo / in progress / done) in the project board, not +in labels; labels describe what an issue *is*, the board describes where it *is*. + +Prefix labels by dimension (`type:`, `area:`) so they group and colour +consistently and are unambiguous when several are applied at once. + +## Creating issues with type and labels + +```sh +# Native type when available (org repos): +gh issue create --type UserStory --label "area:testing,phase-4" \ + --parent --title "" --body-file <file> + +# Label-based type when native types are unavailable (personal repos): +gh issue create --label "type:user-story,area:testing,phase-4" \ + --parent <epic> --title "<title>" --body-file <file> +``` + +Create the `type:` and `area:` labels once per repository (for example with +`gh label create`) so they exist before issues reference them. diff --git a/skills/slice-issues/SKILL.md b/skills/slice-issues/SKILL.md index 523b6f7..1dc90c1 100644 --- a/skills/slice-issues/SKILL.md +++ b/skills/slice-issues/SKILL.md @@ -15,6 +15,12 @@ acceptance criteria, branch, PR, and verification. This skill is GitHub-specific but engine-independent. Keep runtime-specific integration details in `adapters/`. +## Required Reading + +- `../references/issue-labels.md` before creating child issues, to set each + slice's issue type and labels so the backlog and any project board can filter + them. + ## Workflow 1. Identify the parent issue number or URL. @@ -22,14 +28,19 @@ integration details in `adapters/`. 3. Check existing open issues to avoid duplicate slices. 4. Decide whether the work should be split into sub-issues or kept in one PR with clearly separated commits. -5. For each sliced task, create a child issue with GitHub's sub-issue support: +5. For each sliced task, create a child issue with GitHub's sub-issue support, + setting its type and labels per `../references/issue-labels.md`: ```sh - gh issue create --parent <parent> --title "<title>" --body "<body>" + gh issue create --parent <parent> --title "<title>" --body-file <file> \ + --type <Type> --label "<type-label>,<area>,<grouping>" ``` - Use `--body-file` instead of `--body` when the body is multi-line or - contains Markdown that would be awkward to quote safely. + A slice is normally a `user-story` (a reviewable slice of value) or a `task` + (technical work with no direct user value); use `--type` when the platform + supports native issue types, otherwise a `type:` label. Use `--body-file` + instead of `--body` when the body is multi-line or contains Markdown that + would be awkward to quote safely. 6. Comment on the parent issue with the created child issue links and the recommended implementation order. 7. Report the created child issues and any fallback used. @@ -39,6 +50,11 @@ integration details in `adapters/`. - Make each child issue independently reviewable and small enough for one focused PR. - Give each child issue a clear goal, scope, and acceptance criteria. +- Give each child issue an explicit type and labels per + `../references/issue-labels.md` (a `type:` value plus `area:` and any project + grouping such as a roadmap phase), so it can be triaged onto a project board + without re-reading the body. Do not encode workflow status in labels; that + belongs to the board. - Preserve the parent issue as the coordination point. - Prefer dependency order over arbitrary numbering. - Keep implementation work out of the slicing step unless the user explicitly From 0a52bb08e50f2e2bd720dea85c3d9c0b0839dfe8 Mon Sep 17 00:00:00 2001 From: Dieter Baier <dieter@dieterbaier.eu> Date: Sun, 12 Jul 2026 14:55:51 +0200 Subject: [PATCH 2/2] slice-issues: show native-type OR type-label, not both (PR review) The example command and slicing rule required --type and a type: label at the same time, contradicting issue-labels.md (they are alternatives). That fails on personal repos (no native types) and double-classifies on org repos. Show two explicit variants (native issue type OR type: label) and state that exactly one type representation is used. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --- skills/slice-issues/SKILL.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/skills/slice-issues/SKILL.md b/skills/slice-issues/SKILL.md index 1dc90c1..e90fb3b 100644 --- a/skills/slice-issues/SKILL.md +++ b/skills/slice-issues/SKILL.md @@ -29,18 +29,24 @@ integration details in `adapters/`. 4. Decide whether the work should be split into sub-issues or kept in one PR with clearly separated commits. 5. For each sliced task, create a child issue with GitHub's sub-issue support, - setting its type and labels per `../references/issue-labels.md`: + setting its type and labels per `../references/issue-labels.md`. Use exactly + one type representation — a native issue type **or** a `type:` label, never + both: ```sh + # Org repos with native issue types: gh issue create --parent <parent> --title "<title>" --body-file <file> \ - --type <Type> --label "<type-label>,<area>,<grouping>" + --type <Type> --label "<area>,<grouping>" + + # Personal repos (native issue types unavailable) — carry the type as a label: + gh issue create --parent <parent> --title "<title>" --body-file <file> \ + --label "<type-label>,<area>,<grouping>" ``` A slice is normally a `user-story` (a reviewable slice of value) or a `task` - (technical work with no direct user value); use `--type` when the platform - supports native issue types, otherwise a `type:` label. Use `--body-file` - instead of `--body` when the body is multi-line or contains Markdown that - would be awkward to quote safely. + (technical work with no direct user value). Use `--body-file` instead of + `--body` when the body is multi-line or contains Markdown that would be + awkward to quote safely. 6. Comment on the parent issue with the created child issue links and the recommended implementation order. 7. Report the created child issues and any fallback used. @@ -51,8 +57,9 @@ integration details in `adapters/`. focused PR. - Give each child issue a clear goal, scope, and acceptance criteria. - Give each child issue an explicit type and labels per - `../references/issue-labels.md` (a `type:` value plus `area:` and any project - grouping such as a roadmap phase), so it can be triaged onto a project board + `../references/issue-labels.md` — exactly one type representation (a native + issue type or a `type:` label) plus `area:` and any project grouping such as a + roadmap phase — so it can be triaged onto a project board without re-reading the body. Do not encode workflow status in labels; that belongs to the board. - Preserve the parent issue as the coordination point.