From aa90a50f6c4682ec774994f479ae7479bb80cc82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 1 Sep 2026 19:44:09 +0200 Subject: [PATCH] docs: clarify technical issue requirements --- AGENTS.md | 2 +- docs/agents/issue-tracker.md | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 37fe06a06f..4bb4dacbac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 104a8af21a..b9ae64a470 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -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