/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.mdfor 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
Score | Status | Issue
------|-----------|------
92 | Excellent | #42 Add session token refresh
78 | Good | #38 Fix webhook retry logic
45 | Needs work| #35 Improve error handling
23 | Incomplete| #31 Make things better
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 Nto 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 Nto 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/xllabel - 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 lintas quality gate/autopilot— Runs/issue lintbefore starting work/tidy— Runs/issue lint --all --fix