1# Writing Agent Briefs
2 
3An agent brief is a structured comment posted on a GitHub issue when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
4 
5## Principles
6 
7### Durability over precision
8 
9The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
10 
11- **Do** describe interfaces, types, and behavioral contracts
12- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
13- **Don't** reference file paths — they go stale
14- **Don't** reference line numbers
15- **Don't** assume the current implementation structure will remain the same
16 
17### Behavioral, not procedural
18 
19Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
20 
21- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
22- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
23- **Good:** "When a user runs `/triage` with no arguments, they should see a summary of issues needing attention"
24- **Bad:** "Add a switch statement in the main handler function"
25 
26### Complete acceptance criteria
27 
28The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
29 
30- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
31- **Bad:** "Triage should work correctly"
32 
33### Explicit scope boundaries
34 
35State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
36 
37## Template
38 
39```markdown
40## Agent Brief
41 
42**Category:** bug / enhancement
43**Summary:** one-line description of what needs to happen
44 
45**Current behavior:**
46Describe what happens now. For bugs, this is the broken behavior.
47For enhancements, this is the status quo the feature builds on.
48 
49**Desired behavior:**
50Describe what should happen after the agent's work is complete.
51Be specific about edge cases and error conditions.
52 
53**Key interfaces:**
54- `TypeName` — what needs to change and why
55- `functionName()` return type — what it currently returns vs what it should return
56- Config shape — any new configuration options needed
57 
58**Acceptance criteria:**
59- [ ] Specific, testable criterion 1
60- [ ] Specific, testable criterion 2
61- [ ] Specific, testable criterion 3
62 
63**Out of scope:**
64- Thing that should NOT be changed or addressed in this issue
65- Adjacent feature that might seem related but is separate
66```
67 
68## Examples
69 
70### Good agent brief (bug)
71 
72```markdown
73## Agent Brief
74 
75**Category:** bug
76**Summary:** Skill description truncation drops mid-word, producing broken output
77 
78**Current behavior:**
79When a skill description exceeds 1024 characters, it is truncated at exactly
801024 characters regardless of word boundaries. This produces descriptions
81that end mid-word (e.g. "Use when the user wants to confi").
82 
83**Desired behavior:**
84Truncation should break at the last word boundary before 1024 characters
85and append "..." to indicate truncation.
86 
87**Key interfaces:**
88- The `SkillMetadata` type's `description` field — no type change needed,
89  but the validation/processing logic that populates it needs to respect
90  word boundaries
91- Any function that reads SKILL.md frontmatter and extracts the description
92 
93**Acceptance criteria:**
94- [ ] Descriptions under 1024 chars are unchanged
95- [ ] Descriptions over 1024 chars are truncated at the last word boundary
96      before 1024 chars
97- [ ] Truncated descriptions end with "..."
98- [ ] The total length including "..." does not exceed 1024 chars
99 
100**Out of scope:**
101- Changing the 1024 char limit itself
102- Multi-line description support
103```
104 
105### Good agent brief (enhancement)
106 
107```markdown
108## Agent Brief
109 
110**Category:** enhancement
111**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
112 
113**Current behavior:**
114When a feature request is rejected, the issue is closed with a `wontfix` label
115and a comment. There is no persistent record of the decision or reasoning.
116Future similar requests require the maintainer to recall or search for the
117prior discussion.
118 
119**Desired behavior:**
120Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
121files that capture the decision, reasoning, and links to all issues that
122requested the feature. When triaging new issues, these files should be
123checked for matches.
124 
125**Key interfaces:**
126- Markdown file format in `.out-of-scope/` — each file should have a
127  `# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
128  and a `**Prior requests:**` list with issue links
129- The triage workflow should read all `.out-of-scope/*.md` files early
130  and match incoming issues against them by concept similarity
131 
132**Acceptance criteria:**
133- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
134- [ ] The file includes the decision, reasoning, and link to the closed issue
135- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
136      appended to its "Prior requests" list rather than creating a duplicate
137- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
138      when a new issue matches a prior rejection
139 
140**Out of scope:**
141- Automated matching (human confirms the match)
142- Reopening previously rejected features
143- Bug reports (only enhancement rejections go to `.out-of-scope/`)
144```
145 
146### Bad agent brief
147 
148```markdown
149## Agent Brief
150 
151**Summary:** Fix the triage bug
152 
153**What to do:**
154The triage thing is broken. Look at the main file and fix it.
155The function around line 150 has the issue.
156 
157**Files to change:**
158- src/triage/handler.ts (line 150)
159- src/types.ts (line 42)
160```
161 
162This is bad because:
163- No category
164- Vague description ("the triage thing is broken")
165- References file paths and line numbers that will go stale
166- No acceptance criteria
167- No scope boundaries
168- No description of current vs desired behavior
169