Skip to content

docs: clarify technical issue requirements #2226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thymikee merged 1 commit into from
Sep 1, 2026
Merged

docs: clarify technical issue requirements #2226

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ task procedures only when needed:
| Adding or changing a CLI flag | `docs/agents/cli-flags.md` |
| Opening or reviewing a PR | `docs/agents/pull-requests.md` |
| Running against a real device | `docs/agents/device-verification.md` |
| Issues, PRDs, and triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
| Writing issues or PRDs, and triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
| Web backend setup or diagnostics | `docs/agents/web-backend.md` |

Versioned CLI help is the source of truth for command behavior. Start workflow planning with
Expand Down
5 changes: 5 additions & 0 deletions docs/agents/issue-tracker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ External PRs are not part of the triage request queue. Use `gh pr` commands only

## Conventions

Write issues as concise implementation contracts. Start with the purpose. Include a concrete API,
data shape, or CLI example when the issue changes a boundary. State required behavior, observable
completion conditions, and dependencies. Use plain, direct sentences. Remove persuasion, repeated
context, and filler, but never remove a normative requirement to make the issue shorter.

`gh` authentication may only be available through the user's login shell. In sandboxed agent environments, run GitHub operations through the login shell and request escalation for network/auth access, for example:

```sh
Expand Down
Loading