Tohuhono/Oberon / .agents/skills/triage
triage
VerifiedTriage Oberon's GitHub issues and explicitly named PRs, verify requests, and write agent-ready briefs.
| File | Kind | Size |
|---|---|---|
| AGENT-BRIEF.md | markdown | 7.9 KB |
| OUT-OF-SCOPE.md | markdown | 2.5 KB |
| SKILL.md | skill md | 6.0 KB |
| agents/openai.yaml | config | 135 B |
AGENT-BRIEF.md
View on GitHub# Writing Agent Briefs
An agent brief is a structured comment posted on a GitHub issue or PR when it moves to
`ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The
original body and discussion are context: the agent brief is the contract.
Use [CONTEXT.md](../../CONTEXT.md) for domain names and [TESTING.md](../../TESTING.md) for
verification scope. Include both Playgrounds when the behavior requires CMS parity.
The brief states **what the agent should do**, which stretches to both surfaces: for an issue,
that's building the change from nothing; for a PR, it's what's left to do _to the existing diff_:
finish it, close gaps, address review points. Same principles either way; the PR example below shows
the difference.
## Principles
### Durability over precision
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.
- **Do** describe interfaces, types, and behavioral contracts
- **Do** name specific types, function signatures, or config shapes that the agent should look for
or modify
- **Don't** reference file paths: they go stale
- **Don't** reference line numbers
- **Don't** assume the current implementation structure will remain the same
### Behavioral, not procedural
Describe **what** the system should do, not **how** to implement it. The agent will explore the
codebase fresh and make its own 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
The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance
criteria. Each criterion should be independently verifiable.
- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through
initial classification"
- **Bad:** "Triage should work correctly"
### Explicit scope boundaries
State what is out of scope. This prevents the agent from gold-plating or making assumptions about
adjacent features.
## Template
```markdown
## 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)
```markdown
## 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)
```markdown
## Agent Brief
**Category:** enhancement **Summary:** Add `.agents/out-of-scope/` 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
`.agents/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 `.agents/out-of-scope/`: use the record structure in
[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)
- The triage workflow should read all `.agents/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 `.agents/out-of-scope/`
- [ ] The file includes the decision, reasoning, and link to the closed issue
- [ ] If a matching `.agents/out-of-scope/` file already exists, the new issue is appended to its
"Prior requests" list rather than creating a duplicate
- [ ] During triage, existing `.agents/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 `.agents/out-of-scope/`)
```
### Good agent brief (PR)
For a PR, "Current behavior" describes the state of the diff, and the brief asks the agent to finish
or fix it rather than build from scratch.
```markdown
## Agent Brief
**Category:** enhancement **Summary:** Finish the contributor's `--json` output flag for
`triage list`
**Current behavior:** The PR adds a `--json` flag that serializes the issue list to JSON. The happy
path works and the diff matches the project's command structure. Two gaps remain: errors are still
printed as human text (not JSON), and the new flag has no test coverage.
**Desired behavior:** With `--json`, all output (including errors) is well-formed JSON on stdout,
and the command's exit codes are unchanged. The existing human-readable output is untouched when the
flag is absent.
**Key interfaces:**
- The command's error path should emit `{ "error": string }` under `--json` instead of the
plain-text error
- Reuse the existing serializer the PR already added; don't introduce a second
**Acceptance criteria:**
- [ ] `triage list --json` emits valid JSON for both success and error cases
- [ ] Exit codes match the non-JSON command
- [ ] A test covers the `--json` success output and one error case
- [ ] Default (non-JSON) output is byte-for-byte unchanged
**Out of scope:**
- Adding `--json` to any other command
- Changing the JSON shape of the success payload the PR already defined
```
### Bad agent brief
```markdown
## 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)
```
This is bad because:
- No category
- Vague description ("the triage thing is broken")
- References file paths and line numbers that will go stale
- No acceptance criteria
- No scope boundaries
- No description of current vs desired behavior
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |