/issue

Issue quality tooling. Three subcommands for different needs.

Subcommands

/issue lint [#N|--all]

Score issues against org-standards readiness rubric.

Process

• Load groom/references/org-standards.md for scoring rubric

• Fetch issue(s): gh issue view N --json title,body,labels,milestone

• Score each section per rubric (0-100 total)

• Classify findings as errors (blocking) or warnings (informational)

• Report score and findings

Scoring Rubric

Section Points Criteria

Acceptance Criteria 25 25: Given/When/Then with 2+ criteria. 15: checkboxes without GWT. 5: vague. 0: missing.

Problem 20 20: specific with evidence. 10: clear but no evidence. 0: vague/missing.

Affected Files 15 15: paths with descriptions. 8: paths only. 0: missing.

Verification 15 15: executable commands. 8: described not executable. 0: missing.

Labels 10 2 per required label (priority, type, horizon, effort, domain).

Effort 5 5: effort label present. 0: missing.

Diagram 5 5: appropriate. 3: wrong type. 0: missing (unless chore/dep bump).

Milestone 5 5: assigned. 0: missing.

Error Classification

Errors (block agent execution):

• Missing priority label

• No acceptance criteria (score 0)

• No problem statement (score 0)

• Missing affected files for code-change issues

Warnings (flag, don't block):

• No diagram (unless exempt)

• No effort label

• No verification commands

• No boundaries section

• Missing milestone

Output

ISSUE LINT: #42 "Add session token refresh" Score: 78/100 (Good — ready for execution)

Acceptance Criteria: 25/25 ✓ Problem: 20/20 ✓ Affected Files: 15/15 ✓ Verification: 8/15 ⚠ described but not executable Labels: 6/10 ⚠ missing effort label Effort: 0/5 ⚠ no effort label Diagram: 0/5 ⚠ no diagram Milestone: 5/5 ✓

Errors: 0 Warnings: 3

• verification: Add executable commands (pnpm test -- --grep "session")
• labels: Add effort/s|m|l|xl label
• diagram: Add flowchart for token refresh flow

--all mode

Lint all open issues. Output summary table:

BACKLOG LINT SUMMARY

Ready: 2 | Needs enrichment: 1 | Incomplete: 1

--fix mode

After linting, run /issue enrich on issues scoring < 70.

/issue enrich [#N]

Fill missing issue sections using sub-agent research.

Process

• Fetch issue: gh issue view N --json title,body,labels,milestone

• Run /issue lint N to identify gaps

• For each missing section, spawn appropriate sub-agent:

Missing Section Agent Prompt

Affected Files Codebase explorer "Find files related to [issue topic]. Check .glance.md and CODEBASE_MAP.md."

Verification Codebase explorer "Find test commands and verification steps for [affected area]."

Acceptance Criteria General-purpose "Write Given/When/Then acceptance criteria for: [problem statement]"

Approach Web researcher + codebase explorer "Research best practices for [topic]. Find existing patterns in codebase."

Context General-purpose "Read project.md and summarize relevant vision/domain context for [issue]."

Diagram General-purpose "Generate appropriate Mermaid diagram for [issue type]: [summary]"

• Rewrite issue body with all sections populated

• Apply missing labels

• Re-run /issue lint N to confirm score >= 70

Issue Update

gh issue edit N --body "$(cat <<'EOF' [enriched issue body] EOF )"

Add labels:

gh issue edit N --add-label "effort/m"

Output

ISSUE ENRICH: #35 "Improve error handling" Before: 45/100 (Needs work) After: 82/100 (Good)

Added:

• Acceptance Criteria (Given/When/Then)
• Affected Files (5 files identified)
• Verification commands
• Approach with code examples
• Boundaries
• effort/m label

/issue decompose [#N]

Split oversized issues into atomic sub-issues.

When to Decompose

• Issue has effort/xl label

• Issue touches 5+ files across 3+ directories

• Issue has 5+ acceptance criteria spanning different concerns

• Issue mixes feature work with refactoring

Process

• Fetch issue: gh issue view N --comments

• Analyze scope: file count, directory spread, acceptance criteria clusters

• Identify natural boundaries (by module, by concern, by dependency)

• Create child issues, each:

• References parent: "Part of #N"

• Has own acceptance criteria (subset of parent)

• Has own affected files (subset)

• Has dependency links where order matters

• Inherits parent's priority and domain labels

• Gets appropriate effort label (should be s or m)

• Update parent issue:

• Convert to epic type

• Add epic label

• Add checklist linking child issues

• Remove effort/xl (children have own estimates)

Dependency Links

When child issues have ordering dependencies:

Dependencies

• Blocked by: #N1 (API must exist before UI can call it)

Output

ISSUE DECOMPOSE: #28 "Implement payment retry system" Original: effort/xl, 8 acceptance criteria, 12 files

Created 4 sub-issues: #45 [P1] Add retry queue schema (effort/s, blocked by: none) #46 [P1] Implement retry worker (effort/m, blocked by: #45) #47 [P1] Add webhook retry handler (effort/m, blocked by: #45) #48 [P1] Add retry monitoring dashboard (effort/s, blocked by: #46, #47)

Parent #28 converted to epic with sub-issue checklist.

Related

• groom/references/org-standards.md — Scoring rubric and issue format

• /groom — Phase 5 uses /issue lint as quality gate

• /autopilot — Runs /issue lint before starting work

• /tidy — Runs /issue lint --all --fix