From 1616fa3d5b129956a1bd23872f0cac4f464e14b6 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:23:53 -0600 Subject: [PATCH 1/4] Add triage-issues-local skill for OS issue triage Add a new skill for the Oz management agent to triage community issues on the docs repo. The skill classifies issues, identifies affected pages, assesses priority, checks for duplicates, applies labels (triage + priority), and posts a structured comment with a welcome preamble and reviewer instructions. Labels (priority/high, priority/medium, priority/low, triage, and improve or update documentation) were created directly on the repo. Co-Authored-By: Oz --- .agents/skills/triage-issues-local/SKILL.md | 124 ++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 .agents/skills/triage-issues-local/SKILL.md diff --git a/.agents/skills/triage-issues-local/SKILL.md b/.agents/skills/triage-issues-local/SKILL.md new file mode 100644 index 00000000..e3ddcd48 --- /dev/null +++ b/.agents/skills/triage-issues-local/SKILL.md @@ -0,0 +1,124 @@ +--- +name: triage-issues-local +description: Triage new GitHub issues on the Warp docs repo. Classifies the issue, identifies affected pages, assesses priority, suggests a fix direction, checks for duplicates, applies labels, and posts a structured comment. Used by the Oz OSS repo management agent when a new issue is opened. +--- + +# Triage Docs Issue + +Triage a newly opened GitHub issue on the Warp docs repository. Analyze the issue, classify it, assess priority, and post a structured comment that serves both the contributor and the docs team. + +## Workflow + +### 1. Read the issue + +Read the issue title and body. Extract: +- What the reporter is describing (bug, content problem, feature request, or support question) +- Any URLs or page references mentioned +- Specific product areas or features referenced + +### 2. Classify the issue + +Determine the issue type: +- **Site bug** — The docs website platform is broken (search not returning results, navigation links failing, pages not rendering, styling broken, build errors). This is about the site infrastructure, not the content. +- **Content issue** — Documentation is incorrect, outdated, missing, unclear, has typos, or has formatting problems +- **Feature request** — A request for new documentation, new content types, or site enhancements +- **Support question** — A question that belongs in the [Warp community Slack](https://go.warp.dev/join-preview), not the issue tracker + +### 3. Identify affected pages + +Cross-reference the issue body against the docs site structure to find the specific page(s) involved. + +The documentation lives in `src/content/docs/` with these sections: +- `terminal/` — Warp Terminal features (blocks, editor, sessions, appearance) +- `agent-platform/` — Agent Platform (local agents, cloud agents, capabilities, integrations) +- `code/` — Code editor, code review, git worktrees +- `getting-started/` — Installation, setup, quickstart +- `reference/` — CLI and API/SDK reference +- `guides/` — Guides and tutorials +- `knowledge-and-collaboration/` — Warp Drive, teams, Admin Panel +- `support-and-community/` — Troubleshooting, billing, privacy +- `enterprise/` — Enterprise features +- `changelog/` — Release changelog + +Use `codebase_semantic_search` and `grep` to locate the relevant file(s). If the issue includes a URL like `docs.warp.dev/agent-platform/capabilities/skills`, map it to `src/content/docs/agent-platform/capabilities/skills.mdx`. + +### 4. Assess priority + +Apply this rubric: +- **`priority/high`** — Factually incorrect information, broken page, security-related content, or a docs page that causes users to take a wrong action +- **`priority/medium`** — Outdated content, confusing instructions, incomplete coverage, or misleading screenshots +- **`priority/low`** — Typos, minor formatting issues, small clarifications, nice-to-have improvements + +### 5. Suggest fix direction + +Briefly describe what a fix would involve. Be specific enough that someone unfamiliar with the issue could act on it. Examples: +- "Update the CLI command on the environments page to match the current `oz environment create` syntax." +- "Add a note about the macOS-only limitation to the SSH agent forwarding section." +- "Replace the screenshot showing the old Settings UI with the current layout." + +### 6. Check for duplicates + +Search open issues for potential duplicates: +- Use `gh issue list --repo warpdotdev/docs --state open` to list open issues +- Compare titles and descriptions for overlap +- If a likely duplicate exists, mention it in your comment (e.g., "This may be related to #16") + +### 7. Apply labels + +Apply the following labels to the issue: +- **`triage`** — Always apply this. It signals the issue needs human review. +- **One priority label** — `priority/high`, `priority/medium`, or `priority/low` based on your assessment. + +Use the GitHub CLI or API to apply labels. + +### 8. Post the triage comment + +Post a single comment on the issue with three sections: + +**Section 1 — Welcome preamble (for the contributor):** + +> Thanks for opening this issue! The Warp docs team has been notified and will review it within a few business days. +> +> If you'd like to contribute a fix yourself, see our [contribution guide](https://github.com/warpdotdev/docs/blob/main/CONTRIBUTING.md). Minor fixes like typos and broken links can go straight to a pull request. + +**Section 2 — Triage analysis:** + +Include: +- **Classification**: The issue type (site bug, content issue, feature request, or support question) +- **Affected pages**: List the specific page(s) with file paths +- **Priority**: The priority level with a one-sentence justification +- **Suggested fix**: The fix direction from step 5 +- **Duplicates**: Any related open issues, or "No duplicates found" + +**Section 3 — Reviewer callout (for the docs team):** + +> --- +> **Reviewers**: This issue needs triage. Remove the `triage` label once you've validated the issue, verified priority, and decided on next steps. + +## Reference material + +When analyzing issues, consult: +- **Style guide and terminology**: `AGENTS.md` at the repo root contains the docs style guide, content type guidance, and terminology standards. +- **Terminology glossary**: `.warp/references/terminology.md` has the full canonical glossary. Use it to validate that issue reports reference features by their correct names. +- **Site structure**: `astro.config.mjs` contains the sidebar configuration and all registered pages. +- **Source code** (when the issue reports incorrect documentation about a feature): Search `warp-internal` (client, Rust/Swift) and `warp-server` (server, Go) to verify actual product behavior. This helps confirm whether the docs are wrong or the reporter is mistaken. Use `codebase_semantic_search` on these repos, or `grep` for exact symbol names. Docs are the primary source of truth for user-facing answers, but source code is essential for validating accuracy when an issue disputes what the docs say. + +## Example comment + +```markdown +Thanks for opening this issue! The Warp docs team has been notified and will review it within a few business days. + +If you'd like to contribute a fix yourself, see our [contribution guide](https://github.com/warpdotdev/docs/blob/main/CONTRIBUTING.md). Minor fixes like typos and broken links can go straight to a pull request. + +## Triage + +- **Classification**: Content issue +- **Affected pages**: `src/content/docs/agent-platform/cloud-agents/environments.mdx` +- **Priority**: `priority/medium` — The environment creation steps reference a deprecated CLI flag +- **Suggested fix**: Update the `oz environment create` command example to use the current `--repo` flag instead of the deprecated `--repository` flag. Verify the correct syntax against `oz environment create --help`. +- **Duplicates**: No duplicates found + +--- + +**Reviewers**: This issue needs triage. Remove the `triage` label once you've validated the issue, verified priority, and decided on next steps. +``` From ee0f0da05dea6dd3cea62c2534fbf921f04114ab Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 2 Jun 2026 14:39:34 -0600 Subject: [PATCH 2/4] Address review feedback: rename skill, JSON artifact output, fix pagination - Rename triage-issues-local -> triage-issue-local (singular) to match the management agent's resolver convention - Switch from direct label/comment application to triage_result.json artifact output, consistent with the review-pr workflow pattern - Fix unpaginated gh issue list by adding --limit 100 - Add JSON validation step - Update example to show JSON schema instead of raw markdown comment Co-Authored-By: Oz --- .../SKILL.md | 101 ++++++++---------- 1 file changed, 47 insertions(+), 54 deletions(-) rename .agents/skills/{triage-issues-local => triage-issue-local}/SKILL.md (53%) diff --git a/.agents/skills/triage-issues-local/SKILL.md b/.agents/skills/triage-issue-local/SKILL.md similarity index 53% rename from .agents/skills/triage-issues-local/SKILL.md rename to .agents/skills/triage-issue-local/SKILL.md index e3ddcd48..1f4b034d 100644 --- a/.agents/skills/triage-issues-local/SKILL.md +++ b/.agents/skills/triage-issue-local/SKILL.md @@ -1,11 +1,11 @@ --- -name: triage-issues-local -description: Triage new GitHub issues on the Warp docs repo. Classifies the issue, identifies affected pages, assesses priority, suggests a fix direction, checks for duplicates, applies labels, and posts a structured comment. Used by the Oz OSS repo management agent when a new issue is opened. +name: triage-issue-local +description: Triage new GitHub issues on the Warp docs repo. Classifies the issue, identifies affected pages, assesses priority, suggests a fix direction, checks for duplicates, and outputs structured JSON for the triage workflow to apply. Used by the Oz OSS repo management agent when a new issue is opened. --- # Triage Docs Issue -Triage a newly opened GitHub issue on the Warp docs repository. Analyze the issue, classify it, assess priority, and post a structured comment that serves both the contributor and the docs team. +Triage a newly opened GitHub issue on the Warp docs repository. Analyze the issue, classify it, assess priority, and output a structured `triage_result.json` for the triage workflow to apply labels and post comments. ## Workflow @@ -59,41 +59,45 @@ Briefly describe what a fix would involve. Be specific enough that someone unfam ### 6. Check for duplicates Search open issues for potential duplicates: -- Use `gh issue list --repo warpdotdev/docs --state open` to list open issues +- Use `gh issue list --repo warpdotdev/docs --state open --limit 100` to list open issues (use `--limit` to avoid missing older issues) - Compare titles and descriptions for overlap -- If a likely duplicate exists, mention it in your comment (e.g., "This may be related to #16") - -### 7. Apply labels - -Apply the following labels to the issue: -- **`triage`** — Always apply this. It signals the issue needs human review. -- **One priority label** — `priority/high`, `priority/medium`, or `priority/low` based on your assessment. - -Use the GitHub CLI or API to apply labels. - -### 8. Post the triage comment - -Post a single comment on the issue with three sections: - -**Section 1 — Welcome preamble (for the contributor):** - -> Thanks for opening this issue! The Warp docs team has been notified and will review it within a few business days. -> -> If you'd like to contribute a fix yourself, see our [contribution guide](https://github.com/warpdotdev/docs/blob/main/CONTRIBUTING.md). Minor fixes like typos and broken links can go straight to a pull request. - -**Section 2 — Triage analysis:** - -Include: -- **Classification**: The issue type (site bug, content issue, feature request, or support question) -- **Affected pages**: List the specific page(s) with file paths -- **Priority**: The priority level with a one-sentence justification -- **Suggested fix**: The fix direction from step 5 -- **Duplicates**: Any related open issues, or "No duplicates found" - -**Section 3 — Reviewer callout (for the docs team):** +- If a likely duplicate exists, include it in the `duplicates` field of the output + +### 7. Write `triage_result.json` + +Write a `triage_result.json` file with the triage results. The workflow reads this file to apply labels and post the issue comment. Do not apply labels or post comments directly. + +Schema: + +```json +{ + "classification": "content", + "priority": "priority/medium", + "labels": ["triage", "priority/medium"], + "affected_pages": [ + "src/content/docs/agent-platform/cloud-agents/environments.mdx" + ], + "suggested_fix": "Update the `oz environment create` command example to use the current `--repo` flag instead of the deprecated `--repository` flag.", + "duplicates": [], + "summary": "The environment creation steps reference a deprecated CLI flag.", + "issue_body": "Thanks for opening this issue! The Warp docs team has been notified and will review it within a few business days.\n\nIf you'd like to contribute a fix yourself, see our [contribution guide](https://github.com/warpdotdev/docs/blob/main/CONTRIBUTING.md). Minor fixes like typos and broken links can go straight to a pull request.\n\n## Triage\n\n- **Classification**: Content issue\n- **Affected pages**: `src/content/docs/agent-platform/cloud-agents/environments.mdx`\n- **Priority**: `priority/medium` — The environment creation steps reference a deprecated CLI flag\n- **Suggested fix**: Update the `oz environment create` command example to use the current `--repo` flag instead of the deprecated `--repository` flag. Verify the correct syntax against `oz environment create --help`.\n- **Duplicates**: No duplicates found\n\n---\n\n**Reviewers**: This issue needs triage. Remove the `triage` label once you've validated the issue, verified priority, and decided on next steps." +} +``` -> --- -> **Reviewers**: This issue needs triage. Remove the `triage` label once you've validated the issue, verified priority, and decided on next steps. +Field reference: +- **`classification`** — One of: `site-bug`, `content`, `feature-request`, `support-question` +- **`priority`** — The priority label name: `priority/high`, `priority/medium`, or `priority/low` +- **`labels`** — Always include `triage` plus the priority label +- **`affected_pages`** — File paths relative to the repo root +- **`suggested_fix`** — One-sentence fix direction from step 5 +- **`duplicates`** — Array of issue numbers (e.g., `[16]`), or empty array if none found +- **`summary`** — One-sentence summary of the issue for Slack notifications +- **`issue_body`** — The full markdown comment to post on the issue, including the welcome preamble, triage analysis, and reviewer callout + +The `issue_body` should follow this structure: +1. Welcome preamble (for the contributor) +2. Triage analysis (classification, affected pages, priority, suggested fix, duplicates) +3. Reviewer callout after a horizontal rule (for the docs team) ## Reference material @@ -103,22 +107,11 @@ When analyzing issues, consult: - **Site structure**: `astro.config.mjs` contains the sidebar configuration and all registered pages. - **Source code** (when the issue reports incorrect documentation about a feature): Search `warp-internal` (client, Rust/Swift) and `warp-server` (server, Go) to verify actual product behavior. This helps confirm whether the docs are wrong or the reporter is mistaken. Use `codebase_semantic_search` on these repos, or `grep` for exact symbol names. Docs are the primary source of truth for user-facing answers, but source code is essential for validating accuracy when an issue disputes what the docs say. -## Example comment - -```markdown -Thanks for opening this issue! The Warp docs team has been notified and will review it within a few business days. - -If you'd like to contribute a fix yourself, see our [contribution guide](https://github.com/warpdotdev/docs/blob/main/CONTRIBUTING.md). Minor fixes like typos and broken links can go straight to a pull request. - -## Triage +## Validation -- **Classification**: Content issue -- **Affected pages**: `src/content/docs/agent-platform/cloud-agents/environments.mdx` -- **Priority**: `priority/medium` — The environment creation steps reference a deprecated CLI flag -- **Suggested fix**: Update the `oz environment create` command example to use the current `--repo` flag instead of the deprecated `--repository` flag. Verify the correct syntax against `oz environment create --help`. -- **Duplicates**: No duplicates found - ---- - -**Reviewers**: This issue needs triage. Remove the `triage` label once you've validated the issue, verified priority, and decided on next steps. -``` +After creating `triage_result.json`: +- Validate JSON with `jq . triage_result.json` — if this fails, fix the JSON syntax and try again +- Verify `classification` is one of the four allowed values +- Verify `priority` matches one of the three priority labels +- Verify `labels` includes both `triage` and the priority label +- Verify `affected_pages` paths exist in the repo From 9e18fa101fed424858e93327bfebf58e8e1706de Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 3 Jun 2026 10:51:53 -0600 Subject: [PATCH 3/4] Simplify skill to rules-only structure per Safia's feedback Rewrite triage-issue-local to match the pattern in the warp repo. The core triage-issue skill (managed by the OSS system) handles reading issues, writing triage_result.json, applying labels, posting comments, and checking duplicates. This local skill only provides repo-specific rules: - Heuristics for docs issues (site bugs vs content, URL mapping, source code verification) - Label taxonomy (priority labels, triage, ready-to-implement) - Follow-up question limit (2 max) - Information to check before asking follow-ups - Content structure reference Co-Authored-By: Oz --- .agents/skills/triage-issue-local/SKILL.md | 146 ++++++++------------- 1 file changed, 53 insertions(+), 93 deletions(-) diff --git a/.agents/skills/triage-issue-local/SKILL.md b/.agents/skills/triage-issue-local/SKILL.md index 1f4b034d..30fd7435 100644 --- a/.agents/skills/triage-issue-local/SKILL.md +++ b/.agents/skills/triage-issue-local/SKILL.md @@ -1,34 +1,68 @@ --- name: triage-issue-local -description: Triage new GitHub issues on the Warp docs repo. Classifies the issue, identifies affected pages, assesses priority, suggests a fix direction, checks for duplicates, and outputs structured JSON for the triage workflow to apply. Used by the Oz OSS repo management agent when a new issue is opened. +specializes: triage-issue +description: Repo-specific triage guidance for the Warp docs repo. Only the categories declared overridable by the core triage-issue skill may be specialized here. --- -# Triage Docs Issue +# Repo-specific triage guidance for `docs` -Triage a newly opened GitHub issue on the Warp docs repository. Analyze the issue, classify it, assess priority, and output a structured `triage_result.json` for the triage workflow to apply labels and post comments. +This file is a companion to the core `triage-issue` skill. It does not +redefine the triage output schema, safety rules, or follow-up-question +contract. It only specializes the override categories the core skill +marks as overridable. -## Workflow +## Heuristics -### 1. Read the issue +- `docs` is the public Warp documentation repository, built with Astro Starlight. Content lives in `src/content/docs/` as MDX files. Treat public issue reports as potentially incomplete. +- Distinguish between **site bugs** (the docs platform is broken — search, navigation, rendering, styling, build errors) and **content issues** (documentation is incorrect, outdated, missing, unclear, has typos, or has formatting problems). Most issues will be content issues. +- When the reporter provides a `docs.warp.dev` URL, map it to the source file: `docs.warp.dev/agent-platform/capabilities/skills` → `src/content/docs/agent-platform/capabilities/skills.mdx`. +- When an issue claims documentation is wrong about a feature's behavior, verify against the source repos (`warp-internal` for client/Rust, `warp-server` for server/Go) before concluding the docs are incorrect. Docs are the primary source of truth for user-facing content, but source code is essential for validating accuracy when disputed. +- Check the docs style guide (`AGENTS.md`) and terminology glossary (`.warp/references/terminology.md`) to validate that issue reports reference features by their correct names and that any proposed fixes would align with current terminology. +- If the report is a support question (e.g., "How do I do X?") rather than an issue with the docs themselves, direct the reporter to the [Warp community Slack](https://go.warp.dev/join-preview) and the [docs site](https://docs.warp.dev). -Read the issue title and body. Extract: -- What the reporter is describing (bug, content problem, feature request, or support question) -- Any URLs or page references mentioned -- Specific product areas or features referenced +## Follow-up question limit -### 2. Classify the issue +Ask **at most 2 follow-up questions** per triage response. Each question must be high-value: it should meaningfully change the label assignment or reproduction confidence if answered. Do not ask questions whose answers can be inferred from the issue body, linked URLs, or screenshots. -Determine the issue type: -- **Site bug** — The docs website platform is broken (search not returning results, navigation links failing, pages not rendering, styling broken, build errors). This is about the site infrastructure, not the content. -- **Content issue** — Documentation is incorrect, outdated, missing, unclear, has typos, or has formatting problems -- **Feature request** — A request for new documentation, new content types, or site enhancements -- **Support question** — A question that belongs in the [Warp community Slack](https://go.warp.dev/join-preview), not the issue tracker +## Label taxonomy -### 3. Identify affected pages +Use the following labels when triaging docs issues: -Cross-reference the issue body against the docs site structure to find the specific page(s) involved. +**Priority labels** (always apply exactly one): +- `priority/high` — Factually incorrect information, broken page, security-related content, or docs that cause users to take a wrong action +- `priority/medium` — Outdated content, confusing instructions, incomplete coverage, or misleading screenshots +- `priority/low` — Typos, minor formatting issues, small clarifications, nice-to-have improvements -The documentation lives in `src/content/docs/` with these sections: +**Status labels:** +- `triage` — Always apply on new issues. Signals the issue needs human review. +- `ready-to-implement` — Apply only when the issue is clear, the affected page is identified, and the fix is straightforward enough to implement without further discussion. Do not apply when the issue needs product clarification, design input, or significant investigation. + +**Existing template labels** (applied automatically by issue templates — do not remove): +- `bug` — Applied by the "Docs site bug" template +- `improve or update documentation` — Applied by the "Docs content issue" template + +Do not invent new labels. + +## Information to check before asking follow-up questions + +Before asking the reporter for more information, check the issue body, comments, and attachments for: + +- The specific page URL(s) or topic area affected +- What is incorrect, outdated, missing, or unclear (for content issues) +- Browser and OS (for site bugs — search, rendering, navigation issues) +- Screenshots or recordings showing the problem +- Whether the reporter has already suggested a fix or correction +- Whether the affected page exists in `src/content/docs/` and what it currently says + +## Recurring follow-up patterns + +- Content issue with no page URL: ask which page or topic is affected. +- "Docs are wrong" with no source: ask for the expected behavior or a reference (release notes, CLI help output, changelog) that contradicts the current docs. +- Site bug with no reproduction details: ask for browser, OS, and whether the issue persists in incognito/private browsing. + +## Content structure reference + +Documentation lives in `src/content/docs/` with these sections: - `terminal/` — Warp Terminal features (blocks, editor, sessions, appearance) - `agent-platform/` — Agent Platform (local agents, cloud agents, capabilities, integrations) - `code/` — Code editor, code review, git worktrees @@ -40,78 +74,4 @@ The documentation lives in `src/content/docs/` with these sections: - `enterprise/` — Enterprise features - `changelog/` — Release changelog -Use `codebase_semantic_search` and `grep` to locate the relevant file(s). If the issue includes a URL like `docs.warp.dev/agent-platform/capabilities/skills`, map it to `src/content/docs/agent-platform/capabilities/skills.mdx`. - -### 4. Assess priority - -Apply this rubric: -- **`priority/high`** — Factually incorrect information, broken page, security-related content, or a docs page that causes users to take a wrong action -- **`priority/medium`** — Outdated content, confusing instructions, incomplete coverage, or misleading screenshots -- **`priority/low`** — Typos, minor formatting issues, small clarifications, nice-to-have improvements - -### 5. Suggest fix direction - -Briefly describe what a fix would involve. Be specific enough that someone unfamiliar with the issue could act on it. Examples: -- "Update the CLI command on the environments page to match the current `oz environment create` syntax." -- "Add a note about the macOS-only limitation to the SSH agent forwarding section." -- "Replace the screenshot showing the old Settings UI with the current layout." - -### 6. Check for duplicates - -Search open issues for potential duplicates: -- Use `gh issue list --repo warpdotdev/docs --state open --limit 100` to list open issues (use `--limit` to avoid missing older issues) -- Compare titles and descriptions for overlap -- If a likely duplicate exists, include it in the `duplicates` field of the output - -### 7. Write `triage_result.json` - -Write a `triage_result.json` file with the triage results. The workflow reads this file to apply labels and post the issue comment. Do not apply labels or post comments directly. - -Schema: - -```json -{ - "classification": "content", - "priority": "priority/medium", - "labels": ["triage", "priority/medium"], - "affected_pages": [ - "src/content/docs/agent-platform/cloud-agents/environments.mdx" - ], - "suggested_fix": "Update the `oz environment create` command example to use the current `--repo` flag instead of the deprecated `--repository` flag.", - "duplicates": [], - "summary": "The environment creation steps reference a deprecated CLI flag.", - "issue_body": "Thanks for opening this issue! The Warp docs team has been notified and will review it within a few business days.\n\nIf you'd like to contribute a fix yourself, see our [contribution guide](https://github.com/warpdotdev/docs/blob/main/CONTRIBUTING.md). Minor fixes like typos and broken links can go straight to a pull request.\n\n## Triage\n\n- **Classification**: Content issue\n- **Affected pages**: `src/content/docs/agent-platform/cloud-agents/environments.mdx`\n- **Priority**: `priority/medium` — The environment creation steps reference a deprecated CLI flag\n- **Suggested fix**: Update the `oz environment create` command example to use the current `--repo` flag instead of the deprecated `--repository` flag. Verify the correct syntax against `oz environment create --help`.\n- **Duplicates**: No duplicates found\n\n---\n\n**Reviewers**: This issue needs triage. Remove the `triage` label once you've validated the issue, verified priority, and decided on next steps." -} -``` - -Field reference: -- **`classification`** — One of: `site-bug`, `content`, `feature-request`, `support-question` -- **`priority`** — The priority label name: `priority/high`, `priority/medium`, or `priority/low` -- **`labels`** — Always include `triage` plus the priority label -- **`affected_pages`** — File paths relative to the repo root -- **`suggested_fix`** — One-sentence fix direction from step 5 -- **`duplicates`** — Array of issue numbers (e.g., `[16]`), or empty array if none found -- **`summary`** — One-sentence summary of the issue for Slack notifications -- **`issue_body`** — The full markdown comment to post on the issue, including the welcome preamble, triage analysis, and reviewer callout - -The `issue_body` should follow this structure: -1. Welcome preamble (for the contributor) -2. Triage analysis (classification, affected pages, priority, suggested fix, duplicates) -3. Reviewer callout after a horizontal rule (for the docs team) - -## Reference material - -When analyzing issues, consult: -- **Style guide and terminology**: `AGENTS.md` at the repo root contains the docs style guide, content type guidance, and terminology standards. -- **Terminology glossary**: `.warp/references/terminology.md` has the full canonical glossary. Use it to validate that issue reports reference features by their correct names. -- **Site structure**: `astro.config.mjs` contains the sidebar configuration and all registered pages. -- **Source code** (when the issue reports incorrect documentation about a feature): Search `warp-internal` (client, Rust/Swift) and `warp-server` (server, Go) to verify actual product behavior. This helps confirm whether the docs are wrong or the reporter is mistaken. Use `codebase_semantic_search` on these repos, or `grep` for exact symbol names. Docs are the primary source of truth for user-facing answers, but source code is essential for validating accuracy when an issue disputes what the docs say. - -## Validation - -After creating `triage_result.json`: -- Validate JSON with `jq . triage_result.json` — if this fails, fix the JSON syntax and try again -- Verify `classification` is one of the four allowed values -- Verify `priority` matches one of the three priority labels -- Verify `labels` includes both `triage` and the priority label -- Verify `affected_pages` paths exist in the repo +The sidebar configuration is in `astro.config.mjs` at the repo root. From fa3e0431cb25b4480fe791134a3e37425504da46 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 3 Jun 2026 11:10:19 -0600 Subject: [PATCH 4/4] Update .agents/skills/triage-issue-local/SKILL.md Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --- .agents/skills/triage-issue-local/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/triage-issue-local/SKILL.md b/.agents/skills/triage-issue-local/SKILL.md index 30fd7435..a96aeac5 100644 --- a/.agents/skills/triage-issue-local/SKILL.md +++ b/.agents/skills/triage-issue-local/SKILL.md @@ -35,7 +35,7 @@ Use the following labels when triaging docs issues: **Status labels:** - `triage` — Always apply on new issues. Signals the issue needs human review. -- `ready-to-implement` — Apply only when the issue is clear, the affected page is identified, and the fix is straightforward enough to implement without further discussion. Do not apply when the issue needs product clarification, design input, or significant investigation. +- `ready-to-implement` — Reserved for human maintainers. Do not apply automatically; mention implementation readiness in the triage analysis instead. **Existing template labels** (applied automatically by issue templates — do not remove): - `bug` — Applied by the "Docs site bug" template