Back to Details

issue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/issue

/issue

Issue quality tooling. Three subcommands for different needs.
Issue质量工具集。包含三个针对不同需求的子命令。

Subcommands

子命令

/issue lint [#N|--all]

/issue lint [#N|--all]

Score issues against org-standards readiness rubric.
依据组织标准就绪评估表为Issue评分。

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
  1. 加载
    groom/references/org-standards.md
    作为评分评估表
  2. 获取Issue：
    gh issue view N --json title,body,labels,milestone
  3. 依据评估表为每个部分评分（总分0-100）
  4. 将检查结果分为错误（阻塞性）或警告（提示性）
  5. 输出评分结果和检查发现

Scoring Rubric

评分评估表

SectionPointsCriteria
Acceptance Criteria2525: Given/When/Then with 2+ criteria. 15: checkboxes without GWT. 5: vague. 0: missing.
Problem2020: specific with evidence. 10: clear but no evidence. 0: vague/missing.
Affected Files1515: paths with descriptions. 8: paths only. 0: missing.
Verification1515: executable commands. 8: described not executable. 0: missing.
Labels102 per required label (priority, type, horizon, effort, domain).
Effort55: effort label present. 0: missing.
Diagram55: appropriate. 3: wrong type. 0: missing (unless chore/dep bump).
Milestone55: assigned. 0: missing.
部分分值评分标准
验收标准（Acceptance Criteria）2525分：包含2条及以上Given/When/Then格式的标准；15分：仅含复选框，无Given/When/Then；5分：描述模糊；0分：缺失。
问题描述2020分：描述具体且有证据支撑；10分：描述清晰但无证据；0分：描述模糊或缺失。
受影响文件1515分：包含文件路径及说明；8分：仅含文件路径；0分：缺失。
验证方式1515分：提供可执行命令；8分：仅描述但不可执行；0分：缺失。
标签10每个必填标签（优先级、类型、周期、工作量、领域）得2分。
工作量55分：已添加工作量标签；0分：缺失。
图表55分：图表类型合适；3分：图表类型错误；0分：缺失（例行任务/依赖更新除外）。
里程碑55分：已关联里程碑；0分：缺失。

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
错误（阻塞Agent执行）：
  • 缺失优先级标签
  • 无验收标准（得分为0）
  • 无问题描述（得分为0）
  • 代码变更类Issue缺失受影响文件
警告（仅提示，不阻塞）：
  • 无图表（豁免场景除外）
  • 无工作量标签
  • 无可执行验证命令
  • 无边界说明部分
  • 未关联里程碑

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

--all
模式

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
检查所有开放状态的Issue。输出汇总表格：
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

--fix
模式

After linting, run 
/issue enrich
on issues scoring < 70.
完成检查后，对评分低于70分的Issue自动运行
/issue enrich
。

/issue enrich [#N]

/issue enrich [#N]

Fill missing issue sections using sub-agent research.
通过子Agent研究补全Issue的缺失部分。

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:
Missing SectionAgentPrompt
Affected FilesCodebase explorer"Find files related to [issue topic]. Check .glance.md and CODEBASE_MAP.md."
VerificationCodebase explorer"Find test commands and verification steps for [affected area]."
Acceptance CriteriaGeneral-purpose"Write Given/When/Then acceptance criteria for: [problem statement]"
ApproachWeb researcher + codebase explorer"Research best practices for [topic]. Find existing patterns in codebase."
ContextGeneral-purpose"Read project.md and summarize relevant vision/domain context for [issue]."
DiagramGeneral-purpose"Generate appropriate Mermaid diagram for [issue type]: [summary]"
  1. Rewrite issue body with all sections populated
  2. Apply missing labels
  3. Re-run 
    /issue lint N
    to confirm score >= 70
  1. 获取Issue：
    gh issue view N --json title,body,labels,milestone
  2. 运行
    /issue lint N
    识别信息缺口
  3. 针对每个缺失部分，调用对应的子Agent：
缺失部分Agent提示词
受影响文件代码库探索Agent"查找与[Issue主题]相关的文件，检查.glance.md和CODEBASE_MAP.md。"
验证方式代码库探索Agent"查找[受影响区域]对应的测试命令和验证步骤。"
验收标准通用Agent"为以下问题描述编写Given/When/Then格式的验收标准：[问题描述]"
实现方案网络调研Agent + 代码库探索Agent"调研[主题]的最佳实践，查找代码库中已有的实现模式。"
上下文信息通用Agent"阅读project.md，总结与[Issue]相关的项目愿景/领域上下文。"
图表通用Agent"为以下Issue类型生成合适的Mermaid图表：[摘要]"
  1. 重写Issue正文，补全所有缺失部分
  2. 添加缺失的标签
  3. 重新运行
    /issue lint N
    ，确保评分≥70分

Issue Update

Issue更新操作

bash
gh issue edit N --body "$(cat <<'EOF'
[enriched issue body]
EOF
)"
Add labels:
bash
gh issue edit N --add-label "effort/m"
bash
gh issue edit N --body "$(cat <<'EOF'
[enriched issue body]
EOF
)"
添加标签：
bash
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 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]

/issue decompose [#N]

Split oversized issues into atomic sub-issues.
将大型Issue拆分为原子化子Issue。

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
  • Issue带有
    effort/xl
    标签
  • Issue涉及5个以上文件，且分布在3个以上目录
  • Issue包含5条及以上跨不同关注点的验收标准
  • Issue混合了功能开发与重构工作

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)
  1. 获取Issue及评论：
    gh issue view N --comments
  2. 分析范围：文件数量、目录分布、验收标准聚类
  3. 识别自然拆分边界（按模块、关注点、依赖关系）
  4. 创建子Issue，每个子Issue需满足：
    • 关联父Issue："Part of #N"
    • 拥有独立的验收标准（父Issue的子集）
    • 拥有独立的受影响文件（父Issue的子集）
    • 存在依赖顺序时添加依赖关联
    • 继承父Issue的优先级和领域标签
    • 添加合适的工作量标签（应为s或m）
  5. 更新父Issue：
    • 转换为Epic类型
    • 添加
      epic
      标签
    • 添加子Issue关联的复选清单
    • 移除
      effort/xl
      标签（子Issue已包含各自的工作量评估）

Dependency Links

依赖关联

When child issues have ordering dependencies:
markdown
undefined
当子Issue存在执行顺序依赖时：
markdown
undefined

Dependencies

Dependencies

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

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.
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
  • groom/references/org-standards.md
    — 评分评估表及Issue格式规范
  • /groom
    — 第5阶段将
    /issue lint
    作为质量门禁
  • /autopilot
    — 开始工作前自动运行
    /issue lint
  • /tidy
    — 自动运行
    /issue lint --all --fix