Triage

Triage

通过一组小型 triage roles state machine，在项目 issue tracker 中移动 issues。

Triage 期间发布到 issue tracker 的每条 comment 或 issue 必须以此 disclaimer 开头：

> *This was generated by AI during triage.*

Reference docs

• AGENT-BRIEF.md — 如何写持久可用的 agent briefs
• OUT-OF-SCOPE.md — .out-of-scope/ knowledge base 如何工作

Roles

两个 category roles：

• bug — 某个东西坏了
• enhancement — 新功能或改进

五个 state roles：

• needs-triage — maintainer 需要评估
• needs-info — 等待 reporter 提供更多信息
• ready-for-agent — 已完整说明，准备给 AFK agent 接手
• ready-for-human — 需要人工实现
• wontfix — 不会处理

每个已 triage 的 issue 应该刚好携带一个 category role 和一个 state role。如果 state roles 冲突，标记出来并先询问 maintainer，再做其他事。

这些是 canonical role names；issue tracker 中实际使用的 label strings 可能不同。映射应该已经提供给你；如果没有，运行 /setup-matt-pocock-skills。

State transitions：未标记的 issue 通常先进入 needs-triage；之后移动到 needs-info、ready-for-agent、ready-for-human 或 wontfix。needs-info 在 reporter 回复后回到 needs-triage。Maintainer 可以随时 override；对看起来异常的 transitions 标记并在继续前询问。

Invocation

Maintainer 调用 /triage，并用自然语言描述想要什么。解释请求并行动。示例：

• "Show me anything that needs my attention"
• "Let's look at #42"
• "Move #42 to ready-for-agent"
• "What's ready for agents to pick up?"

Show what needs attention

查询 issue tracker，并按最旧优先展示三个 buckets：

1. Unlabeled — 从未 triaged。 2. `needs-triage` — evaluation in progress。 3. `needs-info` with reporter activity since the last triage notes — 需要重新评估。

显示每个 bucket 的数量，以及每个 issue 的一行摘要。让 maintainer 选择。

Triage a specific issue

1. Gather context. 读取完整 issue（body、comments、labels、reporter、dates）。解析任何之前的 triage notes，避免重新询问已解决的问题。使用项目 domain glossary 探索 codebase，并遵守相关 ADRs。读取 .out-of-scope/*.md，并指出任何与此 issue 相似的既往拒绝。

2. Recommend. 告诉 maintainer 你的 category 和 state 推荐及理由，并给出与 issue 相关的简短 codebase summary。等待指示。

3. Reproduce（仅 bugs）. 在任何 grilling 前尝试复现：读取 reporter 的步骤，追踪相关代码，运行 tests 或 commands。报告发生了什么：成功复现及 code path、复现失败，或细节不足（强烈的 needs-info 信号）。已确认复现会让 agent brief 更有力。

4. Grill（如果需要）. 如果 issue 需要进一步充实，运行一次 /grill-with-docs session。

5. Apply the outcome:

• ready-for-agent — 发布 agent brief comment（AGENT-BRIEF.md）。
• ready-for-human — 使用与 agent brief 相同的结构，但说明为什么不能委托（judgment calls、external access、design decisions、manual testing）。
• needs-info — 发布 triage notes（见下方 template）。
• wontfix（bug）— 礼貌解释，然后 close。
• wontfix（enhancement）— 写入 .out-of-scope/，从 comment 链接到它，然后 close（OUT-OF-SCOPE.md）。
• needs-triage — 应用 role。如果有部分进展，可选择 comment。

Quick state override

如果 maintainer 说 “move #42 to ready-for-agent”，相信他们并直接应用 role。确认你即将做什么（role changes、comment、close），然后执行。跳过 grilling。如果在没有 grilling session 的情况下移动到 ready-for-agent，询问他们是否想写 agent brief。

Needs-info template

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

把 grilling 期间已经解决的所有内容都捕获到 “established so far” 下，避免工作丢失。问题必须具体且可执行，而不是 “please provide more info”。

Resuming a previous session

如果 issue 上已有 triage notes，读取它们，检查 reporter 是否回答了任何 outstanding questions，并在继续前展示更新后的情况。不要重复询问已解决的问题。

Writing Agent Briefs

Agent brief 是 issue 移动到 ready-for-agent 时发布在 GitHub issue 上的结构化 comment。它是 AFK agent 后续工作的权威 spec。原始 issue body 和讨论是 context；agent brief 是 contract。

Principles

Durability over precision

Issue 可能会在 ready-for-agent 中停留数天或数周。期间 codebase 会变化。写 brief 时要让它在文件被重命名、移动或 refactor 后仍然有用。

• Do 描述 interfaces、types 和 behavioral contracts
• Do 命名 agent 应该查找或修改的具体 types、function signatures 或 config shapes
• Don't 引用 file paths；它们会过期
• Don't 引用 line numbers
• Don't 假设当前 implementation structure 会保持不变

Behavioral, not procedural

描述系统应该做什么，而不是如何实现。Agent 会重新探索 codebase，并做出自己的 implementation decisions。

• Good: "The SkillConfig type should accept an optional schedule field of type CronExpression"
• Bad: "Open src/types/skill.ts and add a schedule field on line 42"
• Good: "When a user runs /triage with no arguments, they should see a summary of issues needing attention"
• Bad: "Add a switch statement in the main handler function"

Complete acceptance criteria

Agent 需要知道什么时候算完成。每个 agent brief 都必须有具体、可测试的 acceptance criteria。每条 criterion 都应该能独立验证。

• Good: "Running gh issue list --label needs-triage returns issues that have been through initial classification"
• Bad: "Triage should work correctly"

Explicit scope boundaries

说明什么不在范围内。这可以防止 agent gold-plating 或对相邻功能做假设。

Template

## Agent Brief

**Category:** bug / enhancement
**Summary:** one-line description of what needs to happen

**Current behavior:**
Describe what happens now. For bugs, this is the broken behavior.
For enhancements, this is the status quo the feature builds on.

**Desired behavior:**
Describe what should happen after the agent's work is complete.
Be specific about edge cases and error conditions.

**Key interfaces:**
- `TypeName` — what needs to change and why
- `functionName()` return type — what it currently returns vs what it should return
- Config shape — any new configuration options needed

**Acceptance criteria:**
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3

**Out of scope:**
- Thing that should NOT be changed or addressed in this issue
- Adjacent feature that might seem related but is separate

Examples

Good agent brief (bug)

## Agent Brief

**Category:** bug
**Summary:** Skill description truncation drops mid-word, producing broken output

**Current behavior:**
When a skill description exceeds 1024 characters, it is truncated at exactly
1024 characters regardless of word boundaries. This produces descriptions
that end mid-word (e.g. "Use when the user wants to confi").

**Desired behavior:**
Truncation should break at the last word boundary before 1024 characters
and append "..." to indicate truncation.

**Key interfaces:**
- The `SkillMetadata` type's `description` field — no type change needed,
  but the validation/processing logic that populates it needs to respect
  word boundaries
- Any function that reads SKILL.md frontmatter and extracts the description

**Acceptance criteria:**
- [ ] Descriptions under 1024 chars are unchanged
- [ ] Descriptions over 1024 chars are truncated at the last word boundary
      before 1024 chars
- [ ] Truncated descriptions end with "..."
- [ ] The total length including "..." does not exceed 1024 chars

**Out of scope:**
- Changing the 1024 char limit itself
- Multi-line description support

Good agent brief (enhancement)

## Agent Brief

**Category:** enhancement
**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests

**Current behavior:**
When a feature request is rejected, the issue is closed with a `wontfix` label
and a comment. There is no persistent record of the decision or reasoning.
Future similar requests require the maintainer to recall or search for the
prior discussion.

**Desired behavior:**
Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
files that capture the decision, reasoning, and links to all issues that
requested the feature. When triaging new issues, these files should be
checked for matches.

**Key interfaces:**
- Markdown file format in `.out-of-scope/` — each file should have a
  `# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
  and a `**Prior requests:**` list with issue links
- The triage workflow should read all `.out-of-scope/*.md` files early
  and match incoming issues against them by concept similarity

**Acceptance criteria:**
- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
- [ ] The file includes the decision, reasoning, and link to the closed issue
- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
      appended to its "Prior requests" list rather than creating a duplicate
- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
      when a new issue matches a prior rejection

**Out of scope:**
- Automated matching (human confirms the match)
- Reopening previously rejected features
- Bug reports (only enhancement rejections go to `.out-of-scope/`)

Bad agent brief

## Agent Brief

**Summary:** Fix the triage bug

**What to do:**
The triage thing is broken. Look at the main file and fix it.
The function around line 150 has the issue.

**Files to change:**
- src/triage/handler.ts (line 150)
- src/types.ts (line 42)

它不好，因为：

• 没有 category
• 描述含糊（“the triage thing is broken”）
• 引用了会过期的 file paths 和 line numbers
• 没有 acceptance criteria
• 没有 scope boundaries
• 没有说明 current vs desired behavior

Out-of-Scope Knowledge Base

Repo 中的 .out-of-scope/ 目录保存被拒绝 feature requests 的持久记录。它有两个用途：

1. Institutional memory — 记录为什么某个 feature 被拒绝，避免 issue 关闭后理由丢失 2. Deduplication — 当新 issue 与既往拒绝匹配时，skill 可以指出之前的决策，而不是重新争论

Directory structure

.out-of-scope/
├── dark-mode.md
├── plugin-system.md
└── graphql-api.md

每个概念一个文件，而不是每个 issue 一个文件。多个请求同一件事的 issues 归入同一个文件。

File format

文件应该用轻松、可读的风格编写，更像短 design document，而不是 database entry。使用段落、code samples 和 examples，让第一次看到它的人也能理解理由。

# Dark Mode

This project does not support dark mode or user-facing theming.

## Why this is out of scope

The rendering pipeline assumes a single color palette defined in
`ThemeConfig`. Supporting multiple themes would require:

- A theme context provider wrapping the entire component tree
- Per-component theme-aware style resolution
- A persistence layer for user theme preferences

This is a significant architectural change that doesn't align with the
project's focus on content authoring. Theming is a concern for downstream
consumers who embed or redistribute the output.

// The current ThemeConfig interface is not designed for runtime switching: interface ThemeConfig { colors: ColorPalette; // single palette, resolved at build time fonts: FontStack; }

## Prior requests

- #42 — "Add dark mode support"
- #87 — "Night theme for accessibility"
- #134 — "Dark theme option"

Naming the file

为概念使用简短、描述性的 kebab-case 名称：dark-mode.md、plugin-system.md、graphql-api.md。文件名应该足够清晰，让浏览目录的人不用打开文件也能知道被拒绝的是什么。

Writing the reason

理由应该有实质内容，不是“we don't want this”，而是为什么。好的理由会引用：

• Project scope or philosophy（“This project focuses on X; theming is a downstream concern”）
• Technical constraints（“Supporting this would require Y, which conflicts with our Z architecture”）
• Strategic decisions（“We chose to use A instead of B because...”）

理由应该持久。避免引用临时情况（“we're too busy right now”）；那不是真正拒绝，而是延期。

When to check .out-of-scope/

在 triage 期间（Step 1: Gather context），读取 .out-of-scope/ 中的所有文件。评估新 issue 时：

• 检查请求是否匹配现有 out-of-scope concept
• 匹配依据是 concept similarity，不是 keyword；“night theme” 匹配 dark-mode.md
• 如果匹配，向 maintainer 指出：“This is similar to .out-of-scope/dark-mode.md — we rejected this before because [reason]. Do you still feel the same way?”

Maintainer 可能会：

• Confirm — 新 issue 被添加到现有文件的 “Prior requests” list，然后关闭
• Reconsider — 删除或更新 out-of-scope 文件，并让 issue 走正常 triage
• Disagree — issues 相关但不同，继续正常 triage

When to write to .out-of-scope/

只有当一个 enhancement（不是 bug）被拒绝为 wontfix 时才写。流程：

1. Maintainer 决定某个 feature request 不在范围内 2. 检查是否已有匹配的 .out-of-scope/ 文件 3. 如果有：把新 issue 追加到 “Prior requests” list 4. 如果没有：用 concept name、decision、reason 和第一个 prior request 创建新文件 5. 在 issue 上发布 comment，解释决策并提到 .out-of-scope/ 文件 6. 使用 wontfix label 关闭 issue

Updating or removing out-of-scope files

如果 maintainer 改变了对既往拒绝 concept 的看法：

• 删除 .out-of-scope/ 文件
• Skill 不需要重新打开旧 issues；它们是历史记录
• 触发重新考虑的新 issue 继续正常 triage