docs(agents): define category labels and the blocked label #237

Merged

gabogg merged 3 commits from docs/triage-category-labels into master 2026-10-03 11:15:01 +00:00

Conversation 3 Commits 3 Files changed 4 +63 -17

gabogg commented 2026-10-03 08:05:01 +00:00

Owner

Copy link

Summary

The triage skill expects every issue to carry exactly one category role (bug or enhancement) next to its triage role, but the tracker had neither label. This PR closes that gap in docs/agents/triage-labels.md:

• Category section. Maps the skill's bug and enhancement roles to tracker labels of the same name. Refactors, chores and docs count as enhancement. Pull requests stay uncategorised: their conventional-commit type already states the kind of change, and they inherit the category of the issue they close. Uncategorised issues get a category at their next triage, not in a bulk relabel.
• Research section, reworded per the maintainer's decision on this PR. research is a modifier used alongside one category and one triage role, not a category of its own. It marks an issue that needs real investigation, over the internet or local resources, before it can be triaged down. That can be a bug whose cause or extent is unknown (bug + research), or an envisioned enhancement whose design depends on facts nobody has gathered yet (enhancement + research). A bug that is already understood, or an enhancement that only needs a design conversation, drops research.
• Blocked section. Documents the existing blocked label, already used on #73, #163 and #164 next to a Blocked by: line but described nowhere. It sits alongside the triage role, and work selection skips it.

Tracker changes already applied (labels aren't versioned):

• created bug (#d73a4a) and enhancement (#a2eeef);
• reworded research's description to match the modifier rule;
• categorised the five open research issues as enhancement (#199, #208, #217, #235, #236), and corrected the Category: line in the briefs on #199, #208 and #217.

Architectural impact

Agent docs and tracker labels only. No code, schema or interface changes.

Verification

• scripts/check_docs.py: 42 Markdown files and 80 HTTP operations checked, links OK.
• Pre-commit (including the full pytest suite) passed on ff913df and e0aefad.
• The five research issues each carry one category, research, and one triage role.

Checklist

• Category mapping documented; bug and enhancement labels created
• research documented as a modifier alongside a category (maintainer decision)
• blocked label documented
• Open research issues categorised
• Categorise other open issues as they come up for triage

🤖 Generated with Claude Code

## Summary The triage skill expects every issue to carry exactly one **category** role (`bug` or `enhancement`) next to its triage role, but the tracker had neither label. This PR closes that gap in `docs/agents/triage-labels.md`: - **Category section.** Maps the skill's `bug` and `enhancement` roles to tracker labels of the same name. Refactors, chores and docs count as `enhancement`. Pull requests stay uncategorised: their conventional-commit type already states the kind of change, and they inherit the category of the issue they close. Uncategorised issues get a category at their next triage, not in a bulk relabel. - **Research section, reworded per the maintainer's decision on this PR.** `research` is a **modifier used alongside** one category and one triage role, not a category of its own. It marks an issue that needs real investigation, over the internet or local resources, before it can be triaged down. That can be a bug whose cause or extent is unknown (`bug` + `research`), or an envisioned enhancement whose design depends on facts nobody has gathered yet (`enhancement` + `research`). A bug that is already understood, or an enhancement that only needs a design conversation, drops `research`. - **Blocked section.** Documents the existing `blocked` label, already used on #73, #163 and #164 next to a `Blocked by:` line but described nowhere. It sits alongside the triage role, and work selection skips it. **Tracker changes already applied** (labels aren't versioned): - created `bug` (#d73a4a) and `enhancement` (#a2eeef); - reworded `research`'s description to match the modifier rule; - categorised the five open research issues as `enhancement` (#199, #208, #217, #235, #236), and corrected the `Category:` line in the briefs on #199, #208 and #217. ## Architectural impact Agent docs and tracker labels only. No code, schema or interface changes. ## Verification - `scripts/check_docs.py`: 42 Markdown files and 80 HTTP operations checked, links OK. - Pre-commit (including the full pytest suite) passed on ff913df and e0aefad. - The five research issues each carry one category, `research`, and one triage role. ## Checklist - [x] Category mapping documented; `bug` and `enhancement` labels created - [x] `research` documented as a modifier alongside a category (maintainer decision) - [x] `blocked` label documented - [x] Open research issues categorised - [ ] Categorise other open issues as they come up for triage 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gabogg added the

ready-for-agent

label 2026-10-03 08:05:01 +00:00

gabogg added 1 commit 2026-10-03 08:05:01 +00:00

docs(agents): define category labels and the blocked label ... ff913dfa1e

The triage skill expects exactly one category role per issue, but the
tracker had no bug or enhancement labels, so triage briefs fell back to
ad-hoc categories. Map the skill's bug and enhancement roles to new
tracker labels and make research the repo's third category, replacing
the other two on investigation issues. Pull requests stay uncategorised:
their conventional-commit type already says what kind of change they are.

Also document the existing blocked label, which was in use alongside a
"Blocked by:" line but described nowhere.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gabogg referenced this pull request from a commit 2026-10-03 08:26:06 +00:00

docs(agents): use research alongside a category, not instead of one

gabogg added 1 commit 2026-10-03 08:26:06 +00:00

docs(agents): use research alongside a category, not instead of one ... e0aefadbfc

Maintainer decision on #237: research marks an issue that needs real
investigation before it can be triaged down, which can happen to a bug
whose cause is unknown as much as to an envisioned enhancement. It is a
modifier next to one category and one triage role, not a third category.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

gabogg reviewed 2026-10-03 09:09:34 +00:00

gabogg left a comment

Copy link

Code review, pass 1 (origin/master...e0aefad, spec: maintainer label decisions of 2026-10-03)

Result: no P1 or P2, and 11 P3s. This is pass 1, so fix every finding and request a second pass.

• Spec conformance is confirmed:
  • bug/enhancement are the category, exactly one per issue.
  • research is a modifier used alongside one category and one triage role.
  • blocked goes with a "Blocked by:" line.
  • The tracker labels match the doc in name and intent.
  • The open research issues (#199, #208, #217, #235, #236) all carry enhancement + research + one triage role.
• Checks: check_docs.py passes (42 files, 80 operations), and the commits are conventional. The PR is docs only, so it stays a draft (git-and-workflow.md:26). There is no conflict with #178.

Spec

P3

1. AGENTS.md:99 is stale. It still says "Canonical 5-role triage vocabulary". Mention the category, research, blocked and priority labels too (raised on both axes).
2. The intro is stale. triage-labels.md:3 still says "five canonical triage roles". The boilerplate at :17 ("Edit the right-hand column…") now sits above the Category table. Widen the intro and move the boilerplate.
3. The rule on PR categories needs the maintainer's sign-off (:30–32, "Pull requests carry no category label"). The spec covers only issues. The triage skill treats a PR as "an issue with attached code, using the same roles", and OUT-OF-SCOPE.md:86 records rejected enhancement PRs. → The maintainer has to decide; see the PR thread. Until then, make it explicit that PRs inherit the category of the issue they close (for example, an enhancement PR).
4. The no-bulk-relabel rule is new policy (:35–36, "add one at its next triage rather than relabelling old issues in bulk"). It's reasonable, but it isn't in the spec. → maintainer sign-off.
5. The research section's list of triage roles reads as complete (:65–66). It lists only needs-triage and ready-for-agent, but #235 is ready-for-human. Write "one triage role (for example …)".
6. "Blocked by: #<n> line at the top" can't be literal (:76). The AI-triage disclaimer always comes first, and #235 uses a ## Blocked by heading. Write "near the top", and fix #235's body to match.
7. Two labels named "research" can be confused. wayfinder:research (issue-tracker.md:35) is a different label from the new research modifier. Add a one-line note to tell them apart (raised on both axes).
8. Optional: docs/agents/milestones.md:3 says milestones are "independent of triage roles and priority". It could also name category and blocked.

Standards

P3

9. British spellings: :27, :35 and :68 use "behaviour" and "categorised". The rest of the docs use US spelling (about 10 files say "behavior"), so use "behavior" and "categorized".
10. The Blocked section (:73–81) only talks about issues. Say whether blocked also applies to PRs. Line 15 says PRs take the triage and priority labels.
11. Overlap with finding 3: state the PR-category inheritance explicitly, so it doesn't contradict "enhancement PRs" in OUT-OF-SCOPE.md:86.

## Code review, pass 1 (`origin/master...e0aefad`, spec: maintainer label decisions of 2026-10-03) Result: **no P1 or P2, and 11 P3s.** This is pass 1, so fix every finding and request a **second pass**. - **Spec conformance is confirmed:** - `bug`/`enhancement` are the category, exactly one per issue. - `research` is a modifier used alongside one category and one triage role. - `blocked` goes with a "Blocked by:" line. - The tracker labels match the doc in name and intent. - The open research issues (#199, #208, #217, #235, #236) all carry `enhancement` + `research` + one triage role. - **Checks:** `check_docs.py` passes (42 files, 80 operations), and the commits are conventional. The PR is docs only, so it stays a draft (git-and-workflow.md:26). There is no conflict with #178. ## Spec ### P3 1. **AGENTS.md:99 is stale.** It still says "Canonical 5-role triage vocabulary". Mention the category, research, blocked and priority labels too (raised on both axes). 2. **The intro is stale.** `triage-labels.md:3` still says "five canonical triage roles". The boilerplate at :17 ("Edit the right-hand column…") now sits above the Category table. Widen the intro and move the boilerplate. 3. **The rule on PR categories needs the maintainer's sign-off** (:30–32, "Pull requests carry no category label"). The spec covers only issues. The triage skill treats a PR as "an issue with attached code, using the same roles", and OUT-OF-SCOPE.md:86 records rejected *enhancement PRs*. → **The maintainer has to decide; see the PR thread.** Until then, make it explicit that PRs inherit the category of the issue they close (for example, an enhancement PR). 4. **The no-bulk-relabel rule is new policy** (:35–36, "add one at its next triage rather than relabelling old issues in bulk"). It's reasonable, but it isn't in the spec. → maintainer sign-off. 5. **The research section's list of triage roles reads as complete** (:65–66). It lists only `needs-triage` and `ready-for-agent`, but #235 is `ready-for-human`. Write "one triage role (for example …)". 6. **"`Blocked by: #<n>` line at the top" can't be literal** (:76). The AI-triage disclaimer always comes first, and #235 uses a `## Blocked by` heading. Write "near the top", and fix #235's body to match. 7. **Two labels named "research" can be confused.** `wayfinder:research` (`issue-tracker.md:35`) is a different label from the new `research` modifier. Add a one-line note to tell them apart (raised on both axes). 8. **Optional:** `docs/agents/milestones.md:3` says milestones are "independent of triage roles and priority". It could also name category and `blocked`. ## Standards ### P3 9. **British spellings:** :27, :35 and :68 use "behaviour" and "categorised". The rest of the docs use US spelling (about 10 files say "behavior"), so use "behavior" and "categorized". 10. **The Blocked section** (:73–81) only talks about issues. Say whether `blocked` also applies to PRs. Line 15 says PRs take the triage and priority labels. 11. **Overlap with finding 3:** state the PR-category inheritance explicitly, so it doesn't contradict "enhancement PRs" in OUT-OF-SCOPE.md:86.

gabogg commented 2026-10-03 09:17:45 +00:00

Author

Owner

Copy link

Maintainer decisions (2026-10-03), from review pass 1 items 3 and 4:

• Pull requests carry no category label. They inherit the category of the issue they close. Keep the rule and make the inheritance explicit, for example by naming an enhancement PR.
• No bulk relabel. Uncategorized issues get a category at their next triage. Keep the rule as written.

**Maintainer decisions (2026-10-03), from review pass 1 items 3 and 4:** - Pull requests carry no category label. They inherit the category of the issue they close. Keep the rule and make the inheritance explicit, for example by naming an enhancement PR. - No bulk relabel. Uncategorized issues get a category at their next triage. Keep the rule as written.

gabogg added 1 commit 2026-10-03 10:24:51 +00:00

docs(agents): address review pass 1 findings on category and blocked labels 88af057b3f

gabogg commented 2026-10-03 10:25:20 +00:00

Author

Owner

Copy link

Pass 1 fixes (88af057)

All 11 P3 findings from review r37 have been addressed on the PR branch (docs/triage-category-labels):

1. AGENTS.md:99 widened: Updated the triage labels description in AGENTS.md to include category labels (bug, enhancement), the research modifier, blocked, and priority labels.
2. Intro widened & boilerplate moved: Widened the intro in docs/agents/triage-labels.md to cover canonical triage and category roles along with modifier, priority, and blocker tracking. Moved the "Edit the right-hand column..." boilerplate up directly below the triage roles table.
3. & 11. PR category inheritance: Made PR category inheritance explicit in docs/agents/triage-labels.md ("A pull request inherits the category of the issue it closes (for example, an enhancement PR)."), matching the maintainer's decision and consistent with OUT-OF-SCOPE.md.
4. No-bulk-relabel rule: Retained the no-bulk-relabel rule per the maintainer's decision ("Uncategorized issues get a category at their next triage. Keep the rule as written.").
5. Research triage role list as example: Updated the triage role list under ## Research to be non-exhaustive using "for example" (- **one triage role** (for example, needs-triagewhile the questions are being shaped, orready-for-agent once they are settled enough to investigate).).
6. "Near the top" and #235 updated: Updated triage-labels.md (and issue-tracker.md) to specify a Blocked by: #<n> line "near the top". Updated issue #235's body via tea issues edit 235 to include a Blocked by: #218 line near the top.
7. Distinguishing research modifier from wayfinder:research: Added a one-line note in triage-labels.md under ## Research clarifying that research is distinct from wayfinder:research (which marks a scoped child ticket under a wayfinding map). Clarified this distinction in issue-tracker.md:35 as well.
8. Milestones independence: Updated docs/agents/milestones.md:3 to state that milestones are independent of triage roles, category, blocked, and priority.
9. US spelling: Converted British spellings to US spellings (behaviour -> behavior, categorised -> categorized, relabelling -> relabeling, labelled -> labeled).
10. blocked applicability to PRs: Stated explicitly in triage-labels.md (both in line 15 and in the ## Blocked section) that blocked applies to pull requests waiting on prerequisite PRs or issues.

Verification:

• python3 scripts/check_docs.py: passed (42 Markdown files, 80 operations).
• ruff check .: passed.
• Pre-commit hook (trailing whitespace, end of files, ruff format, full pytest suite): passed on 88af057.

The PR stays a draft (docs only). Please run review pass 2 on 88af057.

## Pass 1 fixes (88af057) All 11 P3 findings from review r37 have been addressed on the PR branch (`docs/triage-category-labels`): 1. **AGENTS.md:99 widened**: Updated the triage labels description in `AGENTS.md` to include category labels (`bug`, `enhancement`), the `research` modifier, `blocked`, and priority labels. 2. **Intro widened & boilerplate moved**: Widened the intro in `docs/agents/triage-labels.md` to cover canonical triage and category roles along with modifier, priority, and blocker tracking. Moved the "Edit the right-hand column..." boilerplate up directly below the triage roles table. 3. & 11. **PR category inheritance**: Made PR category inheritance explicit in `docs/agents/triage-labels.md` ("A pull request inherits the category of the issue it closes (for example, an enhancement PR)."), matching the maintainer's decision and consistent with `OUT-OF-SCOPE.md`. 4. **No-bulk-relabel rule**: Retained the no-bulk-relabel rule per the maintainer's decision ("Uncategorized issues get a category at their next triage. Keep the rule as written."). 5. **Research triage role list as example**: Updated the triage role list under `## Research` to be non-exhaustive using "for example" (`- **one triage role** (for example, `needs-triage` while the questions are being shaped, or `ready-for-agent` once they are settled enough to investigate).`). 6. **"Near the top" and #235 updated**: Updated `triage-labels.md` (and `issue-tracker.md`) to specify a `Blocked by: #<n>` line "near the top". Updated issue #235's body via `tea issues edit 235` to include a `Blocked by: #218` line near the top. 7. **Distinguishing `research` modifier from `wayfinder:research`**: Added a one-line note in `triage-labels.md` under `## Research` clarifying that `research` is distinct from `wayfinder:research` (which marks a scoped child ticket under a wayfinding map). Clarified this distinction in `issue-tracker.md:35` as well. 8. **Milestones independence**: Updated `docs/agents/milestones.md:3` to state that milestones are independent of triage roles, category, `blocked`, and priority. 9. **US spelling**: Converted British spellings to US spellings (`behaviour` -> `behavior`, `categorised` -> `categorized`, `relabelling` -> `relabeling`, `labelled` -> `labeled`). 10. **`blocked` applicability to PRs**: Stated explicitly in `triage-labels.md` (both in line 15 and in the `## Blocked` section) that `blocked` applies to pull requests waiting on prerequisite PRs or issues. Verification: - `python3 scripts/check_docs.py`: passed (42 Markdown files, 80 operations). - `ruff check .`: passed. - Pre-commit hook (trailing whitespace, end of files, ruff format, full pytest suite): passed on `88af057`. The PR stays a draft (docs only). Please run review pass 2 on `88af057`.

gabogg referenced this pull request 2026-10-03 10:45:43 +00:00

docs(agents): clarify PR category inheritance wording in triage-labels.md #263

gabogg reviewed 2026-10-03 10:46:26 +00:00

gabogg left a comment

Copy link

Code review, pass 2 (origin/master...88af057, spec: maintainer label decisions of 2026-10-03)

Result: no P1, no P2 and 3 P3s. Mergeable. The wording P3 is filed as #263.

• All 11 r37 items are fixed:
  • AGENTS.md and the intro are widened.
  • PR category inheritance and the no-bulk-relabel rule follow the maintainer's decisions.
  • The research role list is now an example, and "Blocked by" says "near the top".
  • The wayfinder:research label is told apart from research.
  • Spelling is US, and blocked covers PRs.
• #235 now has a Blocked by: #218 line after the AI disclaimer.
• Checks: check_docs.py passes. Forgejo's "not mergeable" flag is stale: git merge-tree origin/master 88af057 merges cleanly.

Spec

• P3: triage-labels.md:32 "(for example, an enhancement PR)" reads like an example of a PR rather than of inheritance. → #263

Standards

• P3: the boilerplate at :15 would read better at the end of the intro. → #263 (optional)
• P3: 88af057 has no Co-Authored-By trailer, and ff913df's body says "uncategorised". This is commit history only, so accepted.

## Code review, pass 2 (`origin/master...88af057`, spec: maintainer label decisions of 2026-10-03) Result: **no P1, no P2 and 3 P3s. Mergeable.** The wording P3 is filed as #263. - **All 11 r37 items are fixed:** - AGENTS.md and the intro are widened. - PR category inheritance and the no-bulk-relabel rule follow the maintainer's decisions. - The research role list is now an example, and "Blocked by" says "near the top". - The `wayfinder:research` label is told apart from `research`. - Spelling is US, and `blocked` covers PRs. - **#235** now has a `Blocked by: #218` line after the AI disclaimer. - **Checks:** `check_docs.py` passes. Forgejo's "not mergeable" flag is stale: `git merge-tree origin/master 88af057` merges cleanly. ## Spec - P3: `triage-labels.md:32` "(for example, an enhancement PR)" reads like an example of a PR rather than of inheritance. → **#263** ## Standards - P3: the boilerplate at :15 would read better at the end of the intro. → **#263** (optional) - P3: `88af057` has no `Co-Authored-By` trailer, and `ff913df`'s body says "uncategorised". This is commit history only, so accepted.

gabogg changed title from WIP: docs(agents): define category labels and the blocked label to docs(agents): define category labels and the blocked label 2026-10-03 11:14:58 +00:00

gabogg merged commit 9a72ff4ec5 into master 2026-10-03 11:15:01 +00:00

gabogg deleted branch docs/triage-category-labels 2026-10-03 11:15:02 +00:00

gabogg referenced this pull request from a commit 2026-10-03 11:15:04 +00:00

docs(agents): define category labels and the blocked label (#237)

gabogg referenced this pull request 2026-10-03 11:34:08 +00:00

fix(schedule): localize calibration labels and preserve unnamed exceptions #222

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

blocked

Waits on the issues listed in its "Blocked by:" line before implementation

  

bug

Category: something is broken; behaviour differs from the spec or docs

  

enhancement

Category: new feature or improvement, including refactors, chores and docs

  

high-priority

Address before ordinary-priority work; independent of triage readiness and blockers

  

low-priority

Address after ordinary-priority work; independent of triage readiness and blockers

  

needs-info

Waiting on reporter for more information

  

needs-triage

Maintainer needs to evaluate this issue

  

ready-for-agent

Fully specified, ready for an AFK agent

  

ready-for-human

Requires human implementation

  

referenced

Previously closed issue reopened or referenced by an open issue; visible history marker

  

research

Needs investigation (internet or local resources) before it can be triaged down; used alongside a category and a triage role

  

wontfix

Will not be actioned

No labels

blocked

bug

enhancement

high-priority

low-priority

needs-info

needs-triage

ready-for-agent

ready-for-human

referenced

research

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gabogg/hikcentral!237

No description provided.