Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From hatch3r
Refines existing board items: re-prioritizes, reclassifies, re-scopes, archives stale items, decomposes oversized issues, merges duplicates, and refreshes dependencies.
npx claudepluginhub hatch3r/hatch3rHow this skill is triggered — by the user, by Claude, or both
Slash command
/hatch3r:hatch3r-board-groomThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default...
Regenerates a live GitHub board overview dashboard from current state. Scans open issues, computes health metrics, and updates the meta:board-overview issue. Part of the hatch3r delivery pipeline.
Grooms backlog items by fact-checking claims against sources, running RT-ICA analysis per item, spawning groomer agents, and writing updates via MCP tools. Use before planning or execution.
Syncs session work into GitHub issues and queries issue status across repos. Two modes: write (end-of-session sync with parent epic + W-label) and read (status lookup).
Share bugs, ideas, or general feedback.
Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per agents/shared/user-question-protocol.md — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
hatch3r's board commands operate as the implementation orchestration layer above GitHub Agentic Workflows. While GitHub's agentic workflows handle continuous automation (triage, testing, documentation), hatch3r's board commands orchestrate the full delivery pipeline:
GitHub Agentic Workflows and hatch3r are complementary: use agentic workflows for continuous background automation, use hatch3r board commands for structured delivery orchestration.
Read the hatch3r-board-shared skill at the start of the run. It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
Follow the Token-Saving Directives in hatch3r-board-shared.
Execute these steps in order. Do not skip any step. Ask the user at every checkpoint marked with ASK.
.hatch3r/hatch.json and cache the full config (top-level owner/repo, platform, and board section).platform from .hatch3r/hatch.json. Default to github if missing.hatch3r-board-shared: use top-level owner/repo first, fall back to board.owner/board.repo if top-level values are empty..hatch3r/hatch.json. Run board-init first."board.projectNumber -- if null, board sync will be skipped later.Perform ONE comprehensive scan and cache everything for subsequent steps.
Platform-specific: Fetch all open items
If platform is github:
gh issue list -R {owner}/{repo} --state open --limit 500 --json number,title,labels,state,createdAt,updatedAt,body. Paginate if necessary. Fall back to list_issues MCP if gh CLI fails.If platform is azure-devops:
az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT [System.Id], [System.Title], [System.State], [System.Tags], [System.CreatedDate], [System.ChangedDate], [System.Description] FROM WorkItems WHERE [System.State] <> 'Closed' AND [System.State] <> 'Removed'". Fall back to list_work_items MCP.If platform is gitlab:
Fetch ALL open issues: glab issue list -R {namespace}/{project} --state opened --per-page 100. Paginate if necessary.
For each issue/work item, extract labels/tags from the response.
Check for sub-issues/child work items:
issue_read with method: get_sub_issues.az boards work-item relation list --id N to find parent-child relations.glab api projects/{project_id}/issues/{N}/links for related issues.
Cache parent-child relationships.Parse ## Dependencies sections from issue bodies for dependency references. Recognize both hard (Blocked by #N, Depends on #N) and soft (Recommended after #N) dependency types. Track the type for each edge in the dependency graph -- only hard dependencies block pickup.
Exclude any issue labeled meta:board-overview from all analysis and listings.
Classify every open issue (excluding meta:board-overview):
Analyze cached data to produce actionable refinement suggestions. This step combines diagnostic detection (same as board-refresh) with grooming-specific analysis.
Count issues per status label:
| Status | Source |
|---|---|
| Backlog / Triage | Issues with status:triage |
| Ready | Issues with status:ready |
| In Progress | Issues with status:in-progress |
| In Review | Issues with status:in-review |
| Externally Blocked | Issues with status:blocked |
For each open issue, check for required labels. Flag issues missing any of:
type:* (at least one type label)priority:* (at least one priority label)executor:* (at least one executor label)Optional but noted: missing area:*, missing risk:*.
Flag open issues that are potentially stale:
status:triage with no update in 14+ days (based on updatedAt).status:in-progress with no update in 7+ days (may be abandoned).status:ready with no update in 30+ days (may be deprioritized or obsolete).## Dependencies sections.## Dependencies that should be cleaned up (the Blocked by #N is satisfied but the text remains).has-dependencies label but no ## Dependencies section, or an empty section.## Implementation Order levels against the DAG derived from its sub-issues' ## Dependencies sections. Flag epics where the two diverge.Analyze the distribution of priority labels across the board:
priority:p0 or priority:p1 (priority inflation).priority:p3 + risk:high).Scan existing standalone issues for epic grouping. Apply the Epic Grouping Policy from hatch3r-board-shared:
area:* labels.type:* label (e.g., all type:refactor items).area:api + area:middleware = "backend").Compute standalone ratio: standalone_count / (epic_count + standalone_count). Flag if ratio exceeds 10%.
Flag issues that may be oversized:
area:* labels.Compare existing open issues pairwise for semantic overlap:
area:* + similar title keywords.## Scope sections for boundary collisions.For each epic, compare the sub-issue references in the epic body (checklist items, > Parent: references) against the native sub-issue list from issue_read with method: get_sub_issues (GitHub) or equivalent platform call. Flag sub-issues that appear in the body but are not natively linked.
If board.projectNumber is configured, compare label-based status (status:* labels) against board column status via gh project item-list {board.projectNumber} --owner {board.owner} --format json (GitHub) or equivalent platform call. Flag issues where the label status and board column status diverge.
For each open issue with status:in-review:
Closes #N for this issue: gh pr list -R {owner}/{repo} --state open --json number,body — parse for Closes #{N}.az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status active — check work item relations.Closes #N for this issue: glab mr list -R {namespace}/{project} --state opened — parse descriptions for Closes #{N}.Also check for closed issues with status:in-review (or any non-status:done status label) — these are issues that were auto-closed on PR merge but whose labels and board status were not updated to "Done" (see Post-Merge Terminal State in hatch3r-board-shared).
Flag two categories:
status:in-review but no associated open PR/MR — likely caused by PR closure without merge.status:in-review — should be status:done with board status "Done".Present findings grouped by category:
Board Groom — Refinement Summary:
Board Health:
Total open issues: N (X epics, Y sub-issues, Z standalone)
Standalone ratio: Z/{X+Z} ({percentage}%) — target <=10%
Missing metadata: M issues (details below)
Stale issues: S issues
Stale dependency refs: D issues
Priority imbalance: {description or "None"}
Epic ordering discrepancies: E epics
Unlinked sub-issues: U issues (non-native links)
Board sync drift: V issues (label/board status mismatch)
Orphaned in-review: O issues (open with no PR/MR), S issues (closed but not status:done)
Grooming Opportunities:
Re-prioritize candidates: R issues (priority/risk misalignment, priority inflation)
Archive candidates: A issues (stale, likely obsolete)
Decomposition candidates: C issues (oversized)
Grouping candidates: G standalone issues → potential epics
Duplicate/overlap candidates: O issue pairs
Dependency cleanup: K issues (stale refs, orphaned labels)
Link fix candidates: L issues (advisory or comment-only links)
Available actions: [reprioritize | reclassify | re-scope | demote | archive | decompose | merge | regroup | dep-refresh | health-fix | link-fix | all]
ASK: "Here is the board refinement summary. Which grooming actions do you want to perform? Select one or more: reprioritize / reclassify / re-scope / demote / archive / decompose / merge / regroup / dep-refresh / health-fix / link-fix / all. You can also specify issue numbers to target specific items (e.g., 'reprioritize #5, #12')."
Execute only the actions the user selected. Each action is a self-contained sub-step with its own ASK checkpoint. If the user selected "all", execute every action in the order listed below.
Change priority:* labels on existing issues based on current context.
Re-prioritize Candidates:
| # | Title | Current | Suggested | Rationale |
|---|-------|---------|-----------|-----------|
| #N | {title} | P3 | P1 | risk:high but lowest priority; security-adjacent |
| #M | {title} | P0 | P2 | no longer critical after #K shipped |
ASK: "Confirm or adjust priority changes. Enter issue numbers with new priorities (e.g., '#5 → P1, #12 → P3'), or 'confirm all' / 'skip'."
gh issue edit N --remove-label "priority:pN" --add-label "priority:pM" (fall back to issue_write MCP).az boards work-item update --id N --fields "System.Tags=..." (update tag string).glab issue update N --unlabel "priority::pN" --label "priority::pM".Update type:*, executor:*, risk:*, or area:* labels on existing issues.
executor:agent but issue body reveals human decisions needed → suggest executor:hybrid).type:feature but reads as a refactor).ASK: "Confirm or adjust reclassifications. Enter changes per issue (e.g., '#5 executor:hybrid, #12 risk:low'), or 'confirm all' / 'skip'."
gh issue edit N --remove-label "..." --add-label "..." (fall back to issue_write MCP).az boards work-item update --id N --fields "System.Tags=...".glab issue update N --unlabel "..." --label "...".Update acceptance criteria, ## Scope sections, and issue body content for existing issues. This uses the same triage questioning framework as board-fill Step 2.5 but applied to existing issues.
ASK: "Which issues need re-scoping? For each, I'll ask targeted questions to refine scope and acceptance criteria."
For each confirmed issue, run triage questioning across the six dimensions (Scope/Definition, Value/Why, Unknowns/Spikes, External Blockers, Size/Decomposition, User/Stakeholder). Ask only about dimensions that appear unclear or outdated. Batch issues by theme.
Update the issue/work item body with refined acceptance criteria and scope. Preserve all other body sections.
gh issue edit N --body "..." (fall back to issue_write MCP).az boards work-item update --id N --description "...".glab issue update N --description "...".Send status:ready issues back to status:triage when they need rework. This is the one grooming action that deliberately relaxes the "never downgrade status" guardrail from board-fill.
board-fill Step 5.6 criteria would now fail (e.g., acceptance criteria are stale, scope has shifted, unresolved unknowns emerged).Demotion Candidates:
| # | Title | Current Status | Reason |
|---|-------|----------------|--------|
| #N | {title} | status:ready | AC reference API that was redesigned in #K |
| #M | {title} | status:ready | scope expanded beyond original estimate |
ASK: "Confirm demotion for these issues. They will return to status:triage and need re-filling via board-fill before pickup. Confirm / adjust / skip."
gh issue edit N --remove-label "status:ready" --add-label "status:triage". Sync Projects V2 status.az boards work-item update --id N --state "New" and update tags.glab issue update N --unlabel "status::ready" --label "status::triage".Close issues that are no longer relevant or have been superseded.
Archive Candidates:
| # | Title | Status | Last Updated | Staleness |
|---|-------|--------|--------------|-----------|
| #N | {title} | triage | 45 days ago | No activity since creation |
| #M | {title} | in-progress | 21 days ago | Possibly abandoned |
ASK: "Which issues should be archived (closed)? I'll add a 'Closed as stale during board grooming' comment before closing. Enter issue numbers, 'all', or 'skip'. Issues marked in-progress will require explicit confirmation."
Closed during board grooming — {reason}. Reopen if still relevant.gh issue close N (fall back to issue_write MCP with state: CLOSED).az boards work-item update --id N --state "Closed".glab issue close N -R {namespace}/{project}.Break down oversized issues into smaller sub-issues.
Present decomposition candidates from Step 3g plus any user-specified issues.
For each candidate, analyze the issue body and propose specific sub-issues with one-line descriptions. Follow the same decomposition logic as board-fill Step 5c:
Present decomposition proposals:
Decomposition — #N: {title}
Proposed sub-issues:
1. {sub-issue title} — {one-line scope}
2. {sub-issue title} — {one-line scope}
3. {sub-issue title} — {one-line scope}
The original issue becomes the parent epic.
ASK: "Confirm decomposition for each issue, or adjust sub-issue breakdown. Confirm / modify / skip per issue."
## Implementation Order and adding sub-issue links.gh issue create / az boards work-item create / glab issue create). Fall back to MCP if CLI fails.hatch3r-board-shared (three-tier fallback chain).## Dependencies sections. Add has-dependencies label to sub-issues with dependency references (per rule 7 of Board Sync Enforcement).hatch3r-board-shared.Combine overlapping issues discovered after initial dedup.
ASK: "For each pair: (a) merge into one (specify which survives), (b) keep both, (c) convert one to sub-issue of the other. Enter decisions per pair."
Merged into #N during board grooming.gh issue close N.az boards work-item update --id N --state "Closed".glab issue close N -R {namespace}/{project}.## Dependencies, update those references to point to the surviving issue.Re-analyze and clean up dependency data based on current board state.
Blocked by #N lines from ## Dependencies (the blocker is done, the reference is noise). Replace with None if no other dependencies remain.
1b. Normalize dependency format: Replace Depends on #N with Blocked by #N in ## Dependencies sections. This enforces the canonical format per the Dependency Data Model in hatch3r-board-shared.has-dependencies label but empty or missing ## Dependencies, either add the section or remove the label. Also add has-dependencies to issues that have dependency references but are missing the label (bidirectional enforcement per rule 7 of Board Sync Enforcement).## Implementation Order sections (flagged in Step 3d), regenerate the section from sub-issues' ## Dependencies DAG.Present all proposed changes:
Dependency Refresh:
Stale references to remove:
#N — remove "Blocked by #K" (K is closed)
#M — remove "Blocked by #J" (J is closed) → section becomes "None"
Orphaned labels to fix:
#P — has "has-dependencies" but no ## Dependencies section → remove label
New dependencies discovered:
#Q should be "Blocked by #R" (Q consumes API that R creates)
Epic ordering to regenerate:
Epic #S — sub-issue deps diverge from ## Implementation Order
Newly unblocked:
#T — was waiting on #K (now closed) → available for pickup
ASK: "Confirm dependency changes. Adjust / confirm all / skip."
gh issue edit N --body "...", add/remove labels via gh issue edit N --add-label / --remove-label.az boards work-item update --id N --description "...", update tags.glab issue update N --description "...", update labels.
Regenerate ## Implementation Order for affected epics.Re-run the Sub-Issue Linking Procedure from hatch3r-board-shared for sub-issues identified in Step 3j as non-natively linked.
Link Fix Candidates:
| # | Title | Parent Epic | Current Link Status |
|---|-------|-------------|---------------------|
| #N | {title} | #{epic} | advisory |
| #M | {title} | #{epic} | comment-only |
ASK: "Confirm re-linking for these sub-issues. The procedure will attempt native linking via MCP. Confirm / skip."
Group standalone issues into existing or new epics. This action executes the grouping opportunities detected in Step 3f, following the Epic Grouping Policy from hatch3r-board-shared.
Regroup Proposals:
Absorb into existing epics:
#{N} "{title}" → Epic #{E} "{epic title}" (shared area:api)
#{M} "{title}" → Epic #{F} "{epic title}" (semantic overlap)
Form new epics:
New epic: "Code Quality & Refactoring"
#{P} "{title}" (type:refactor)
#{Q} "{title}" (type:refactor)
Singleton promotions:
#{R} "{title}" → New 1-item epic: "Performance Optimization" (no existing epic match, but themed for future absorption)
Catch-all:
#{S} "{title}" → "General Improvements" epic (no thematic match)
Standalone ratio: before={before}%, after={projected}% (target <=10%)
ASK: "Confirm regrouping proposals. For each: accept / reject / move to different epic. Items you reject will remain standalone. Confirm / adjust / skip."
For confirmed regroupings:
Absorb into existing epic:
hatch3r-board-shared.## Implementation Order.Form new epic:
## Implementation Order.status:triage (or status:ready if all sub-issues are ready).hatch3r-board-shared.Singleton promotion:
Catch-all:
After execution, recalculate and report the standalone ratio.
Fix structural gaps detected in Step 3b (missing metadata), board sync drift detected in Step 3k, and orphaned in-review issues detected in Step 3l.
For each issue with missing required labels, infer the missing labels from issue content using the same classification tables as board-fill Step 3:
type:* → infer from title/body keywords.priority:* → default priority:p2 unless urgency signals suggest otherwise.executor:* → infer from scope complexity.area:* → infer from file paths, modules, or subsystems mentioned.risk:* → infer from scope, dependencies, and architectural impact.Present inferred labels:
Health Fix — Missing Metadata:
| # | Title | Missing | Inferred |
|---|-------|---------|----------|
| #N | {title} | priority | priority:p2 (no urgency signals) |
| #M | {title} | type, executor | type:feature, executor:agent (clear scope) |
ASK: "Confirm or adjust inferred labels. Enter corrections per issue, or 'confirm all' / 'skip'."
Apply confirmed labels/tags using platform CLI:
gh issue edit N --add-label "..." (fall back to issue_write MCP).az boards work-item update --id N --fields "System.Tags=...".glab issue update N --label "...".Board sync drift remediation: For each issue flagged in Step 3k where label status and board column status diverge:
status:in-review: If the issue is closed (state = closed) but the label is status:in-review and the board shows "In Review":
status:in-review with status:done on the issue.board.statusOptions.done.Board Sync Drift Remediation:
| # | Title | Label Status | Board Status | Action |
|---|-------|-------------|--------------|--------|
| #N | {title} | status:ready | In Progress | Sync board -> Ready |
| #M | {title} | status:in-review (closed) | In Review | Label -> status:done, board -> Done |
No separate ASK — drift fixes are presented alongside the metadata fixes in the same Health Fix confirmation prompt.
Orphaned in-review remediation: For each issue flagged in Step 3l:
a. Closed issue with status:in-review (stale in-review): Suggest replacing status:in-review with status:done and syncing board to "Done". This is the post-merge terminal state that was not reached (see Post-Merge Terminal State in hatch3r-board-shared).
b. Open issue with status:in-review but no open PR/MR (orphaned in-review): Present the issue with context (last PR if any, time since last update). Suggest status:ready (if work appears abandoned) or status:in-progress (if rework is likely).
Orphaned In-Review Remediation:
| # | Title | State | Last PR | Suggested Status | Reason |
|---|-------|-------|---------|------------------|--------|
| #N | {title} | closed | PR #M (merged) | status:done | Closed issue still labeled in-review |
| #K | {title} | open | PR #J (closed, not merged) | status:ready | PR closed 14 days ago, no replacement |
ASK: "Confirm or adjust status changes for in-review issues. Enter per-issue decisions (e.g., '#N -> done, #K -> in-progress'), or 'confirm all' / 'skip'."
After all grooming actions are applied, re-evaluate readiness for all affected issues.
status:triage, check all readiness criteria from board-fill Step 5.6 (structural + substantive). If all criteria are met, propose promoting to status:ready.status:ready, verify readiness criteria still hold after the changes. If criteria no longer hold (e.g., scope was expanded but acceptance criteria weren't updated), flag but do not auto-demote -- demotion requires explicit user action via Step 4d.Present readiness changes:
Readiness Re-evaluation:
Promote to ready:
#N — all structural + substantive criteria met after health fix
Readiness warnings (still ready, but verify):
#M — priority changed from P3 to P1; confirm AC still reflect the higher urgency
ASK: "Confirm readiness promotions and acknowledge warnings. Confirm / adjust / skip."
status:triage, add status:ready. Sync Projects v2 status.For every issue/work item whose labels or status changed during Steps 4-5:
hatch3r-board-shared for each issue with a status label change. Map the new status label to the corresponding board status.hatch3r-board-shared).This step is mandatory. Do not skip.
meta:board-overview.hatch3r-board-shared. Use the dependency graph from Step 3d, updated with mutations from Step 4, as input. This includes inter-lane dependency computation, lane phasing, and the Lane Dependency Map.hatch3r-board-shared.hatch3r-board-shared, populated with cached board data updated with all mutations from Steps 4-6. Update using platform CLI:
gh issue edit {N} --body "..." (fall back to issue_write MCP).az boards work-item update --id {N} --description "...".glab issue update {N} --description "...".meta:board-overview and sync to the board.Do NOT re-fetch all issues; use cached data updated with this run's mutations.
This step is mandatory. Do not skip.
Run the End-of-Run Reconciliation Procedure from hatch3r-board-shared. This verifies board sync, sub-issue links, label consistency, and PR linkage for all issues created or updated during this grooming session. Output the reconciliation report before proceeding to Step 8.
Present a summary of all changes made during this grooming session:
Board Groom Complete:
Project: {owner}/{repo}
Overview issue: #{number} (updated / created)
Actions performed:
Re-prioritized: {count} issues
Reclassified: {count} issues
Re-scoped: {count} issues
Demoted to triage: {count} issues
Archived (closed): {count} issues
Decomposed: {count} issues → {count} new sub-issues
Merged: {count} duplicate pairs
Regrouped: {count} standalones → {count} epics ({count} new epics created)
Dependencies: {count} refs cleaned, {count} new deps added, {count} epics reordered
Health fixed: {count} issues (missing metadata resolved)
Readiness promoted: {count} issues (triage → ready)
Board State:
Total open: {count} ({epics} epics, {sub} sub-issues, {standalone} standalone)
Standalone ratio: {percentage}% (target <=10%)
Ready: {count} ({available} available, {depWaiting} waiting on deps)
In Progress: {count}
In Review: {count}
Triage: {count}
Blocked: {count}
Lanes: {laneCount} parallel lanes
This skill delegates per task size:
Source: .claude/rules/fan-out-discipline.md (P8 B2); agents/shared/efficiency-patterns.md.
gh auth login status and repository access."az login status and project access."glab auth login status and project access."hatch3r-board-shared. Warn and continue.meta:board-overview issue outside of Step 7. Steps 4-6 operate on work items only.status:in-progress require individual explicit confirmation even when the user selects "all".## Dependencies, ## Scope, or acceptance criteria, preserve all other sections of the issue body. Read the full body before editing, apply targeted replacements.hatch3r-board-shared. Use platform CLI as primary; MCP as fallback.