/issue

Subcommands

/issue lint [#N|--all]

Process

1. Load

   groom/references/org-standards.md

   for scoring rubric
2. Fetch issue(s):

   gh issue view N --json title,body,labels,milestone

3. Score each section per rubric (0-100 total)
4. Classify findings as errors (blocking) or warnings (informational)
5. Report score and findings

Scoring Rubric

Error Classification

• Missing priority label
• No acceptance criteria (score 0)
• No problem statement (score 0)
• Missing affected files for code-change issues

• 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

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

/issue enrich

/issue enrich [#N]

Process

1. Fetch issue:

   gh issue view N --json title,body,labels,milestone

2. Run

   /issue lint N

   to identify gaps
3. For each missing section, spawn appropriate sub-agent:

1. Rewrite issue body with all sections populated
2. Apply missing labels
3. Re-run

   /issue lint N

   to confirm score >= 70

Issue Update

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

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]

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

1. Fetch issue:

   gh issue view N --comments

2. Analyze scope: file count, directory spread, acceptance criteria clusters
3. Identify natural boundaries (by module, by concern, by dependency)
4. 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)
5. Update parent issue:
   • Convert to epic type
   • Add

     epic

     label
   • Add checklist linking child issues
   • Remove

     effort/xl

     (children have own estimates)

Dependency Links

## 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