AGENT-BRIEF.md - AiToEarn

AGENT-BRIEF.md

1	# Writing Agent Briefs
2
3	An 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
9	The 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
19	Describe 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
28	The 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
35	State 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:
46	Describe what happens now. For bugs, this is the broken behavior.
47	For enhancements, this is the status quo the feature builds on.
48
49	Desired behavior:
50	Describe what should happen after the agent's work is complete.
51	Be 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:
79	When a skill description exceeds 1024 characters, it is truncated at exactly
80	1024 characters regardless of word boundaries. This produces descriptions
81	that end mid-word (e.g. "Use when the user wants to confi").
82
83	Desired behavior:
84	Truncation should break at the last word boundary before 1024 characters
85	and 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:
114	When a feature request is rejected, the issue is closed with a `wontfix` label
115	and a comment. There is no persistent record of the decision or reasoning.
116	Future similar requests require the maintainer to recall or search for the
117	prior discussion.
118
119	Desired behavior:
120	Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
121	files that capture the decision, reasoning, and links to all issues that
122	requested the feature. When triaging new issues, these files should be
123	checked 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:
154	The triage thing is broken. Look at the main file and fix it.
155	The 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
162	This 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

169 lines MARKDOWN