撰写 Agent Brief

agent brief 是 issue 移到 ready-for-agent 时发布在 GitHub issue 上的结构化 comment。它是 AFK agent 工作的 authoritative 规格。原始 issue body 与讨论是 context——agent brief 是 contract。

原则

耐久性优于精确性

issue 可能在 ready-for-agent 停留数天或数周。代码库 meantime 会变。brief 应即使文件 rename、移动或 refactor 仍有用。

Do 描述 interface、type 与 behavioral contract
Do 命名 agent 应查找或修改的具体 type、function signature 或 config shape
Don't 引用 file path——会 stale
Don't 引用 line number
Don't assume 当前实现结构不变

行为性，非程序性

描述系统 应做什么，而非 如何实现。agent 会 fresh 探索代码库并自行做实现决策。

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"

完整的 acceptance criteria

agent 需要知道何时 done。每个 agent brief 必须有 concrete、可测试的 acceptance criteria。每条 criterion 应可独立验证。

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

明确的 scope 边界

说明 out of scope 的内容。防止 agent gold-plating 或对 adjacent feature 做 assume。

模板

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

示例

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

好的 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/`)

差的 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
- vague 描述（"the triage thing is broken"）
- 引用会 stale 的 file path 与 line number
- 无 acceptance criteria
- 无 scope 边界
- 无 current vs desired behavior 描述