From d3c10c809d3596184ab74fdce5691939caeaa387 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 00:29:01 +0000 Subject: [PATCH 01/11] docs: add Factory issue triage recipe Co-Authored-By: Oz --- .../docs/factories/use-cases/issue-triage.mdx | 84 ++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 2b13a881e..cd13f91fd 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -1,8 +1,90 @@ --- -title: Triage incoming issues with a factory +title: Triaging incoming issues with a factory description: >- Configure a factory to investigate, categorize, and prioritize incoming issues before implementation starts. --- +A triage factory turns a new issue into evidence a maintainer can act on: a category, priority, scope, reproduction or root-cause notes, and a clear next step. Use this pattern when issue volume is high enough that maintainers spend time collecting the same context repeatedly. +Keep triage separate from implementation. A triage run should improve the issue and stop when the next action needs product judgment. + +## Prerequisites + +* **A connected code host** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), or [Azure DevOps](/factories/integrations/azure-devops/) and grant access to the repositories the agent must inspect. +* **A triage policy** - Define the categories, priority levels, evidence requirements, and escalation conditions your team uses. +* **Write access to issues** - The code-host integration needs permission to comment, label, assign, or update work items. +* **A test repository** - Validate the recipe away from a production backlog before widening the automation filter. + +## Recommended recipe + +Use a dedicated triage agent and one automation that watches a narrow intake event. + +| Part | Recommendation | +| --- | --- | +| Trigger | `issue_created` for full automation, or `issue_labeled` with a `needs-triage` label for controlled rollout | +| Agent | A `TRIAGE` agent that investigates and updates the issue but doesn't implement | +| Skills | A repo-specific triage skill with category, priority, reproduction, duplicate-search, and escalation rules | +| Settings | Start with one repository and one event; use the Warp Agent harness so built-in code-host tools are available | +| Output | One issue update with evidence, classification, priority, and the recommended next stage | + +This automation starts on every new issue in one repository: + +```markdown title="automations/triage-new-issues/automation.md" +--- +agent: triage +triggers: + - provider: github + event: issue_created + filter: + repos: [acme/payments-service] +--- + +Triage the new issue. Search for duplicates, inspect the relevant code, and +reproduce a bug only when the cause is not already supported by evidence. +Update the issue with category, priority, scope, and the next action. Do not +implement the change. +``` + +Configure the role separately: + +```markdown title="agents/triage/agent.md" +--- +description: Investigates and classifies incoming engineering issues +agentType: TRIAGE +--- + +Establish the cause and scope before recommending work. Use the repository's +triage skill for categories and priority. Ask for missing user evidence rather +than guessing, and stop after updating the issue. +``` + +## Configure issue triage + +1. Create a factory for the repositories that share one backlog. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. +2. Add or edit the triage agent. Give it read access to the relevant repositories and issue-write access through the code-host integration. +3. Add `agents/triage/skills/issue-triage/SKILL.md`. Record the allowed categories and priority levels, the evidence required for a bug, and when to ask a human. See [factory skills](/factories/factory-skills/) for the file format. +4. Add the automation above. For a controlled rollout, change the event to `issue_labeled` and filter on `needs-triage`. +5. Open a test issue with a concrete symptom. Confirm the run updates that issue once, uses only the allowed labels, and stops without creating a branch. +6. Review several results before expanding the repository or event filters. + +## Example workflow + +A customer opens `Checkout fails after applying two coupons` in `acme/payments-service`. The automation starts the triage agent, which searches for duplicates, identifies the discount calculation path, and reproduces the failure with the supplied cart data. + +The agent labels the issue `bug` and `payments`, assigns the team's `P1` priority according to the skill, and posts the failing test output and affected code path. It recommends implementation because the cause is bounded. If the report lacks cart data, the agent asks for that evidence and leaves the issue waiting for a human instead. + +## Best practices + +* **Use a closed classification set** - Put valid categories and priorities in a skill so the agent doesn't invent labels. +* **Separate evidence from confidence** - Require a code location, duplicate, log, or reproduction before assigning a root cause. +* **Control intake volume** - Begin with a label trigger when issue volume or run cost is uncertain. +* **Prevent duplicate routes** - Don't combine a broad `issue_created` automation with an overlapping label automation. +* **Keep implementation gated** - Route accepted issues to a separate [issue implementation recipe](/factories/use-cases/issue-implementation/). + +## Related pages + +* [Factory use cases](/factories/use-cases/) - Compare this recipe with other factory workflows. +* [Factory automations](/factories/automations/) - Configure triggers and filters. +* [Factory agents](/factories/factory-agents/) - Understand the default triage role. +* [GitHub integration](/factories/integrations/github/) - Review issue triggers, permissions, and outputs. {/* This scaffold is completed by its dependent guide PR. */} From 22c5afbd59d75fb0d1dc47490903a1c8ebfb55be Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 00:36:56 +0000 Subject: [PATCH 02/11] docs: clarify supported triage sources Co-Authored-By: Oz --- src/content/docs/factories/use-cases/issue-triage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index cd13f91fd..db2fcc39b 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -10,7 +10,7 @@ Keep triage separate from implementation. A triage run should improve the issue ## Prerequisites -* **A connected code host** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), or [Azure DevOps](/factories/integrations/azure-devops/) and grant access to the repositories the agent must inspect. +* **A connected issue source** - Connect [GitHub](/factories/integrations/github/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/) and grant access to the repositories the agent must inspect. GitLab doesn't provide a native issue-created trigger; use an explicit bot mention or a [custom webhook](/factories/webhooks/) instead. * **A triage policy** - Define the categories, priority levels, evidence requirements, and escalation conditions your team uses. * **Write access to issues** - The code-host integration needs permission to comment, label, assign, or update work items. * **A test repository** - Validate the recipe away from a production backlog before widening the automation filter. From a42d8d295af7cf65ab39482ac2ca1ffa27944daa Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 00:40:20 +0000 Subject: [PATCH 03/11] docs: remove scaffold marker --- src/content/docs/factories/use-cases/issue-triage.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index db2fcc39b..8ac7ef245 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -87,4 +87,3 @@ The agent labels the issue `bug` and `payments`, assigns the team's `P1` priorit * [Factory automations](/factories/automations/) - Configure triggers and filters. * [Factory agents](/factories/factory-agents/) - Understand the default triage role. * [GitHub integration](/factories/integrations/github/) - Review issue triggers, permissions, and outputs. -{/* This scaffold is completed by its dependent guide PR. */} From 795c86f3ffa16f832686193a21a1c21e7fec6083 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 00:57:21 +0000 Subject: [PATCH 04/11] docs: clarify provider issue triggers --- src/content/docs/factories/use-cases/issue-triage.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 8ac7ef245..cd081d9e7 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -21,13 +21,13 @@ Use a dedicated triage agent and one automation that watches a narrow intake eve | Part | Recommendation | | --- | --- | -| Trigger | `issue_created` for full automation, or `issue_labeled` with a `needs-triage` label for controlled rollout | +| Trigger | GitHub: `issue_created` or `issue_labeled`; Azure DevOps: `work_item_created` or `work_item_labeled` | | Agent | A `TRIAGE` agent that investigates and updates the issue but doesn't implement | | Skills | A repo-specific triage skill with category, priority, reproduction, duplicate-search, and escalation rules | | Settings | Start with one repository and one event; use the Warp Agent harness so built-in code-host tools are available | | Output | One issue update with evidence, classification, priority, and the recommended next stage | -This automation starts on every new issue in one repository: +The example below is specific to GitHub and starts on every new issue in one repository. For a controlled rollout, use `issue_labeled` with a label filter. On Azure DevOps, use `work_item_created` or `work_item_labeled` instead. ```markdown title="automations/triage-new-issues/automation.md" --- @@ -63,7 +63,7 @@ than guessing, and stop after updating the issue. 1. Create a factory for the repositories that share one backlog. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. 2. Add or edit the triage agent. Give it read access to the relevant repositories and issue-write access through the code-host integration. 3. Add `agents/triage/skills/issue-triage/SKILL.md`. Record the allowed categories and priority levels, the evidence required for a bug, and when to ask a human. See [factory skills](/factories/factory-skills/) for the file format. -4. Add the automation above. For a controlled rollout, change the event to `issue_labeled` and filter on `needs-triage`. +4. Add the GitHub automation above. For a controlled GitHub rollout, change the event to `issue_labeled` and filter on `needs-triage`. On Azure DevOps, use `work_item_created` or `work_item_labeled`. For Linear or Jira, select the provider event documented by the connected integration. 5. Open a test issue with a concrete symptom. Confirm the run updates that issue once, uses only the allowed labels, and stops without creating a branch. 6. Review several results before expanding the repository or event filters. From 24b4a6c25c57298fc63f15b27458423041ef3466 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 16 Oct 2026 13:57:05 -0600 Subject: [PATCH 05/11] docs: fix provider-specific issue triage guidance Co-Authored-By: Warp --- .../docs/factories/use-cases/issue-triage.mdx | 35 ++++++++++++++++--- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index cd081d9e7..6e2ef4b05 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -12,7 +12,7 @@ Keep triage separate from implementation. A triage run should improve the issue * **A connected issue source** - Connect [GitHub](/factories/integrations/github/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/) and grant access to the repositories the agent must inspect. GitLab doesn't provide a native issue-created trigger; use an explicit bot mention or a [custom webhook](/factories/webhooks/) instead. * **A triage policy** - Define the categories, priority levels, evidence requirements, and escalation conditions your team uses. -* **Write access to issues** - The code-host integration needs permission to comment, label, assign, or update work items. +* **Write access to issues** - Grant the connected issue source permission to make the updates your triage policy requires. For Linear and Jira, issue access comes from the issue-tracker integration; repository access is configured separately through the code host. * **A test repository** - Validate the recipe away from a production backlog before widening the automation filter. ## Recommended recipe @@ -27,7 +27,7 @@ Use a dedicated triage agent and one automation that watches a narrow intake eve | Settings | Start with one repository and one event; use the Warp Agent harness so built-in code-host tools are available | | Output | One issue update with evidence, classification, priority, and the recommended next stage | -The example below is specific to GitHub and starts on every new issue in one repository. For a controlled rollout, use `issue_labeled` with a label filter. On Azure DevOps, use `work_item_created` or `work_item_labeled` instead. +The example below is specific to GitHub and starts on every new issue in one repository. For a controlled rollout, use `issue_labeled` with a label filter. ```markdown title="automations/triage-new-issues/automation.md" --- @@ -45,7 +45,26 @@ Update the issue with category, priority, scope, and the next action. Do not implement the change. ``` -Configure the role separately: +For Azure DevOps, use a separate trigger with `provider: azure_devops`. This example starts triage when a work item matches the `needs-triage` label filter: + +```markdown title="automations/triage-new-work-items/automation.md" +--- +agent: triage +triggers: + - provider: azure_devops + event: work_item_labeled + filter: + labels: [needs-triage] +--- + +Triage the labeled work item using the repository's triage skill. Update it +with evidence, classification, priority, and the next action. Do not implement +the change. +``` + +This trigger filters work items, not repositories. Work item events accept `assignees`, `authors`, `labels`, and `work_item_types`, but not `repos`. Use `work_item_created` to triage newly created work items that match those filters. See [Azure DevOps events and filters](/factories/integrations/azure-devops/#supported-events-and-filters) for setup and scope. + +For either automation, configure the triage agent separately: ```markdown title="agents/triage/agent.md" --- @@ -61,9 +80,15 @@ than guessing, and stop after updating the issue. ## Configure issue triage 1. Create a factory for the repositories that share one backlog. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. -2. Add or edit the triage agent. Give it read access to the relevant repositories and issue-write access through the code-host integration. +2. Add or edit the triage agent. Give it read access to the relevant repositories through the code host and write access to issues through the connected issue source. 3. Add `agents/triage/skills/issue-triage/SKILL.md`. Record the allowed categories and priority levels, the evidence required for a bug, and when to ask a human. See [factory skills](/factories/factory-skills/) for the file format. -4. Add the GitHub automation above. For a controlled GitHub rollout, change the event to `issue_labeled` and filter on `needs-triage`. On Azure DevOps, use `work_item_created` or `work_item_labeled`. For Linear or Jira, select the provider event documented by the connected integration. +4. Add one automation for your issue source: + * **GitHub** - Use the GitHub example above. For a controlled rollout, change the event to `issue_labeled` and add `labels: [needs-triage]` alongside the `repos` filter. + * **Azure DevOps** - Use the separate work item example above, not the GitHub trigger. + * **Linear** - Use `provider: linear` with `issue_created` or `issue_labeled`. Replace the GitHub `repos` filter with Linear team or project filters, and add a label filter for a controlled rollout. + * **Jira** - Use `provider: jira` with `agent_session_created` and a `project_keys` filter. Start triage by assigning or mentioning **Warp** on a work item, following the [Jira automation setup](/factories/integrations/jira/#configure-the-automation-as-code). + + See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. 5. Open a test issue with a concrete symptom. Confirm the run updates that issue once, uses only the allowed labels, and stops without creating a branch. 6. Review several results before expanding the repository or event filters. From 9658d0fd67502008e0e0e9661d4d38fd3a85b523 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 16 Oct 2026 14:08:28 -0600 Subject: [PATCH 06/11] docs: test the selected issue triage trigger Co-Authored-By: Warp --- src/content/docs/factories/use-cases/issue-triage.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 6e2ef4b05..cd7022e55 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -89,7 +89,12 @@ than guessing, and stop after updating the issue. * **Jira** - Use `provider: jira` with `agent_session_created` and a `project_keys` filter. Start triage by assigning or mentioning **Warp** on a work item, following the [Jira automation setup](/factories/integrations/jira/#configure-the-automation-as-code). See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. -5. Open a test issue with a concrete symptom. Confirm the run updates that issue once, uses only the allowed labels, and stops without creating a branch. +5. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: + * **Creation intake** - Create an issue for GitHub or Linear, or a work item for Azure DevOps. Include any labels required by the filter when creating it. + * **Label intake** - Apply `needs-triage` to a test issue or work item after creating it. + * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the report. + + Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. 6. Review several results before expanding the repository or event filters. ## Example workflow From cb0f2949f41a6e4465d9aefbb14f09f63ce2cced Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 17 Oct 2026 15:11:37 -0600 Subject: [PATCH 07/11] docs: reframe issue triage as an existing-factory workflow Co-Authored-By: Warp --- .../docs/factories/use-cases/issue-triage.mdx | 47 ++++++++----------- 1 file changed, 19 insertions(+), 28 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index cd7022e55..0cf918d29 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -1,12 +1,12 @@ --- -title: Triaging incoming issues with a factory +title: Configuring issue triage in your factory description: >- - Configure a factory to investigate, categorize, and prioritize incoming - issues before implementation starts. + Route incoming issues to your factory's triage agent to investigate, + categorize, prioritize, and recommend the next step. --- -A triage factory turns a new issue into evidence a maintainer can act on: a category, priority, scope, reproduction or root-cause notes, and a clear next step. Use this pattern when issue volume is high enough that maintainers spend time collecting the same context repeatedly. +Automate issue triage in your factory so incoming issues include a category, priority, supporting evidence, and a recommended next step. Use this pattern when maintainers repeatedly collect the same context before deciding what work to take on. -Keep triage separate from implementation. A triage run should improve the issue and stop when the next action needs product judgment. +This recipe adds an intake automation for your factory's existing triage agent. Its prompt asks the agent to stop after triage; other workflows in the same factory can continue through specification, implementation, and review. ## Prerequisites @@ -17,12 +17,12 @@ Keep triage separate from implementation. A triage run should improve the issue ## Recommended recipe -Use a dedicated triage agent and one automation that watches a narrow intake event. +Add one automation that watches a narrow intake event and targets your factory's triage agent. | Part | Recommendation | | --- | --- | | Trigger | GitHub: `issue_created` or `issue_labeled`; Azure DevOps: `work_item_created` or `work_item_labeled` | -| Agent | A `TRIAGE` agent that investigates and updates the issue but doesn't implement | +| Agent | Your factory's existing triage agent | | Skills | A repo-specific triage skill with category, priority, reproduction, duplicate-search, and escalation rules | | Settings | Start with one repository and one event; use the Warp Agent harness so built-in code-host tools are available | | Output | One issue update with evidence, classification, priority, and the recommended next stage | @@ -41,8 +41,9 @@ triggers: Triage the new issue. Search for duplicates, inspect the relevant code, and reproduce a bug only when the cause is not already supported by evidence. -Update the issue with category, priority, scope, and the next action. Do not -implement the change. +Use the repository's triage skill for categories and priority. Ask for missing +evidence rather than guessing. Update the issue with category, priority, scope, +and the next action, then stop. Do not implement or start implementation. ``` For Azure DevOps, use a separate trigger with `provider: azure_devops`. This example starts triage when a work item matches the `needs-triage` label filter: @@ -58,29 +59,19 @@ triggers: --- Triage the labeled work item using the repository's triage skill. Update it -with evidence, classification, priority, and the next action. Do not implement -the change. +with evidence, classification, priority, and the next action, then stop. +Ask for missing evidence rather than guessing. Do not implement or start +implementation. ``` This trigger filters work items, not repositories. Work item events accept `assignees`, `authors`, `labels`, and `work_item_types`, but not `repos`. Use `work_item_created` to triage newly created work items that match those filters. See [Azure DevOps events and filters](/factories/integrations/azure-devops/#supported-events-and-filters) for setup and scope. -For either automation, configure the triage agent separately: - -```markdown title="agents/triage/agent.md" ---- -description: Investigates and classifies incoming engineering issues -agentType: TRIAGE ---- - -Establish the cause and scope before recommending work. Use the repository's -triage skill for categories and priority. Ask for missing user evidence rather -than guessing, and stop after updating the issue. -``` +Both examples use `agent: triage`. If your triage agent has a different name, use that name instead. Keep its shared instructions intact; put this workflow's stopping instructions in the automation prompt. ## Configure issue triage -1. Create a factory for the repositories that share one backlog. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. -2. Add or edit the triage agent. Give it read access to the relevant repositories through the code host and write access to issues through the connected issue source. +1. Choose an existing factory with access to the relevant repositories and issue source. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. +2. Confirm the factory has a [triage agent](/factories/factory-agents/#triage) with read access to the relevant repositories through the code host and write access to issues through the connected issue source. 3. Add `agents/triage/skills/issue-triage/SKILL.md`. Record the allowed categories and priority levels, the evidence required for a bug, and when to ask a human. See [factory skills](/factories/factory-skills/) for the file format. 4. Add one automation for your issue source: * **GitHub** - Use the GitHub example above. For a controlled rollout, change the event to `issue_labeled` and add `labels: [needs-triage]` alongside the `repos` filter. @@ -92,7 +83,7 @@ than guessing, and stop after updating the issue. 5. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: * **Creation intake** - Create an issue for GitHub or Linear, or a work item for Azure DevOps. Include any labels required by the filter when creating it. * **Label intake** - Apply `needs-triage` to a test issue or work item after creating it. - * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the report. + * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the issue. Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. 6. Review several results before expanding the repository or event filters. @@ -101,7 +92,7 @@ than guessing, and stop after updating the issue. A customer opens `Checkout fails after applying two coupons` in `acme/payments-service`. The automation starts the triage agent, which searches for duplicates, identifies the discount calculation path, and reproduces the failure with the supplied cart data. -The agent labels the issue `bug` and `payments`, assigns the team's `P1` priority according to the skill, and posts the failing test output and affected code path. It recommends implementation because the cause is bounded. If the report lacks cart data, the agent asks for that evidence and leaves the issue waiting for a human instead. +The agent labels the issue `bug` and `payments`, assigns the team's `P1` priority according to the skill, and posts the failing test output and affected code path. It recommends implementation because the cause is bounded. If the issue lacks cart data, the agent asks for that evidence and leaves the issue waiting for a human instead. ## Best practices @@ -109,7 +100,7 @@ The agent labels the issue `bug` and `payments`, assigns the team's `P1` priorit * **Separate evidence from confidence** - Require a code location, duplicate, log, or reproduction before assigning a root cause. * **Control intake volume** - Begin with a label trigger when issue volume or run cost is uncertain. * **Prevent duplicate routes** - Don't combine a broad `issue_created` automation with an overlapping label automation. -* **Keep implementation gated** - Route accepted issues to a separate [issue implementation recipe](/factories/use-cases/issue-implementation/). +* **Control the next step** - This automation requests triage only. To take accepted issues through implementation in the same factory, follow the [issue implementation recipe](/factories/use-cases/issue-implementation/). ## Related pages From 575e124f5fbee99eae41b3170542cbb6e038f6c7 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:02:12 -0600 Subject: [PATCH 08/11] docs: prevent overlapping Jira triage routes Co-Authored-By: Warp --- .../docs/factories/use-cases/issue-triage.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 0cf918d29..601b54d32 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -6,7 +6,7 @@ description: >- --- Automate issue triage in your factory so incoming issues include a category, priority, supporting evidence, and a recommended next step. Use this pattern when maintainers repeatedly collect the same context before deciding what work to take on. -This recipe adds an intake automation for your factory's existing triage agent. Its prompt asks the agent to stop after triage; other workflows in the same factory can continue through specification, implementation, and review. +This recipe configures an intake automation for your factory's existing triage agent. Its prompt asks the agent to stop after triage; other workflows in the same factory can continue through specification, implementation, and review. ## Prerequisites @@ -17,7 +17,7 @@ This recipe adds an intake automation for your factory's existing triage agent. ## Recommended recipe -Add one automation that watches a narrow intake event and targets your factory's triage agent. +Configure one automation that watches a narrow intake event and targets your factory's triage agent. Reuse an existing route when it already handles those requests. | Part | Recommendation | | --- | --- | @@ -73,11 +73,11 @@ Both examples use `agent: triage`. If your triage agent has a different name, us 1. Choose an existing factory with access to the relevant repositories and issue source. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. 2. Confirm the factory has a [triage agent](/factories/factory-agents/#triage) with read access to the relevant repositories through the code host and write access to issues through the connected issue source. 3. Add `agents/triage/skills/issue-triage/SKILL.md`. Record the allowed categories and priority levels, the evidence required for a bug, and when to ask a human. See [factory skills](/factories/factory-skills/) for the file format. -4. Add one automation for your issue source: +4. Configure one automation for your issue source: * **GitHub** - Use the GitHub example above. For a controlled rollout, change the event to `issue_labeled` and add `labels: [needs-triage]` alongside the `repos` filter. * **Azure DevOps** - Use the separate work item example above, not the GitHub trigger. * **Linear** - Use `provider: linear` with `issue_created` or `issue_labeled`. Replace the GitHub `repos` filter with Linear team or project filters, and add a label filter for a controlled rollout. - * **Jira** - Use `provider: jira` with `agent_session_created` and a `project_keys` filter. Start triage by assigning or mentioning **Warp** on a work item, following the [Jira automation setup](/factories/integrations/jira/#configure-the-automation-as-code). + * **Jira** - Check existing `agent_session_created` automations first; [Jira setup](/factories/integrations/jira/#connect-jira-and-add-an-automation) may already have created one for your projects. If all its requests need triage, retarget it to your triage agent and use the triage-only prompt above. If it also handles other workflows, keep that handler and narrow both routes' project or keyword filters so each request matches only one automation before adding a separate triage automation. Adding a keyword filter to the new route alone doesn't exclude it from an existing project-wide route. See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. 5. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: @@ -85,7 +85,7 @@ Both examples use `agent: triage`. If your triage agent has a different name, us * **Label intake** - Apply `needs-triage` to a test issue or work item after creating it. * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the issue. - Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. + Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. For Jira, also test that a non-triage request still reaches its intended handler. 6. Review several results before expanding the repository or event filters. ## Example workflow @@ -99,7 +99,7 @@ The agent labels the issue `bug` and `payments`, assigns the team's `P1` priorit * **Use a closed classification set** - Put valid categories and priorities in a skill so the agent doesn't invent labels. * **Separate evidence from confidence** - Require a code location, duplicate, log, or reproduction before assigning a root cause. * **Control intake volume** - Begin with a label trigger when issue volume or run cost is uncertain. -* **Prevent duplicate routes** - Don't combine a broad `issue_created` automation with an overlapping label automation. +* **Prevent duplicate routes** - Don't combine a broad `issue_created` automation with an overlapping label automation. For Jira, check every matching session automation; a triage-only prompt doesn't stop another automation from starting its own run. * **Control the next step** - This automation requests triage only. To take accepted issues through implementation in the same factory, follow the [issue implementation recipe](/factories/use-cases/issue-implementation/). ## Related pages From 1592facbbd696e7f9f08dee39c594cd2f1c2ccb2 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 19 Oct 2026 13:12:51 -0600 Subject: [PATCH 09/11] docs: apply triage definition changes before testing Co-Authored-By: Warp --- src/content/docs/factories/use-cases/issue-triage.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 601b54d32..907808b85 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -80,13 +80,14 @@ Both examples use `agent: triage`. If your triage agent has a different name, us * **Jira** - Check existing `agent_session_created` automations first; [Jira setup](/factories/integrations/jira/#connect-jira-and-add-an-automation) may already have created one for your projects. If all its requests need triage, retarget it to your triage agent and use the triage-only prompt above. If it also handles other workflows, keep that handler and narrow both routes' project or keyword filters so each request matches only one automation before adding a separate triage automation. Adding a keyword filter to the new route alone doesn't exclude it from an existing project-wide route. See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. -5. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: +5. Apply the definition changes before testing. For a Warp-managed factory, save the edits in the factory dashboard. For a GitHub-backed factory, merge the changes into its configured production branch. Confirm validation succeeds and the changes are applied. See [where the factory definition lives](/factories/factory-as-code/#where-the-definition-lives). +6. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: * **Creation intake** - Create an issue for GitHub or Linear, or a work item for Azure DevOps. Include any labels required by the filter when creating it. * **Label intake** - Apply `needs-triage` to a test issue or work item after creating it. * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the issue. Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. For Jira, also test that a non-triage request still reaches its intended handler. -6. Review several results before expanding the repository or event filters. +7. Review several results before expanding the repository or event filters. ## Example workflow From 38a72032ebe31a7f656f62659a768266afd64434 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:08:22 -0600 Subject: [PATCH 10/11] docs: clarify issue triage description and introduction Co-Authored-By: Warp --- src/content/docs/factories/use-cases/issue-triage.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 907808b85..4843d8ba5 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -1,12 +1,12 @@ --- title: Configuring issue triage in your factory description: >- - Route incoming issues to your factory's triage agent to investigate, - categorize, prioritize, and recommend the next step. + Have your factory's triage agent investigate, categorize, and prioritize + incoming issues, then recommend what to do next. --- -Automate issue triage in your factory so incoming issues include a category, priority, supporting evidence, and a recommended next step. Use this pattern when maintainers repeatedly collect the same context before deciding what work to take on. +Automate issue triage in your factory so incoming issues include a category, priority, supporting evidence, and a recommended next step. Use this pattern when your team spends time gathering information about each issue before deciding what to work on. -This recipe configures an intake automation for your factory's existing triage agent. Its prompt asks the agent to stop after triage; other workflows in the same factory can continue through specification, implementation, and review. +This recipe configures an intake automation for your factory's existing triage agent. Its prompt asks the agent to stop after triage, but other workflows in the same factory can continue through specification, implementation, and review. ## Prerequisites From fe7ce748e166301d428b87478a18b39514b0d98e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 20 Oct 2026 11:13:57 -0600 Subject: [PATCH 11/11] docs: clarify recipes and streamline issue triage setup Co-Authored-By: Warp --- .../docs/factories/use-cases/index.mdx | 2 +- .../docs/factories/use-cases/issue-triage.mdx | 135 ++++++++++-------- 2 files changed, 75 insertions(+), 62 deletions(-) diff --git a/src/content/docs/factories/use-cases/index.mdx b/src/content/docs/factories/use-cases/index.mdx index fc08a3a54..a6ddb2df4 100644 --- a/src/content/docs/factories/use-cases/index.mdx +++ b/src/content/docs/factories/use-cases/index.mdx @@ -8,7 +8,7 @@ sidebar: --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -Factory use cases are working patterns for combining agents, automations, integrations, skills, and repository controls. Start with the smallest recipe that solves your current bottleneck, then add stages only when the simpler factory is reliable. +A recipe is a recommended configuration and set of instructions for completing a specific task with your factory. Recipes combine agents, automations, integrations, skills, and repository controls. Test the recipe's results before expanding the workflow. For example, check that issue triage categorizes issues correctly before adding implementation. Each guide links to the canonical configuration and integration references. The examples use definitions as code so you can review changes, validate them in CI, and adapt the same pattern to a Warp-managed factory. diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 4843d8ba5..c4f0ced4a 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -6,88 +6,107 @@ description: >- --- Automate issue triage in your factory so incoming issues include a category, priority, supporting evidence, and a recommended next step. Use this pattern when your team spends time gathering information about each issue before deciding what to work on. -This recipe configures an intake automation for your factory's existing triage agent. Its prompt asks the agent to stop after triage, but other workflows in the same factory can continue through specification, implementation, and review. +This [recipe](/factories/use-cases/) configures an intake automation for your factory's existing triage agent. + +The automation prompt asks the agent to stop after triage, but other workflows in the same factory can continue through specification, implementation, and review. ## Prerequisites -* **A connected issue source** - Connect [GitHub](/factories/integrations/github/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/) and grant access to the repositories the agent must inspect. GitLab doesn't provide a native issue-created trigger; use an explicit bot mention or a [custom webhook](/factories/webhooks/) instead. -* **A triage policy** - Define the categories, priority levels, evidence requirements, and escalation conditions your team uses. -* **Write access to issues** - Grant the connected issue source permission to make the updates your triage policy requires. For Linear and Jira, issue access comes from the issue-tracker integration; repository access is configured separately through the code host. -* **A test repository** - Validate the recipe away from a production backlog before widening the automation filter. +* A [factory](/factories/quickstart/) with read access to the relevant repositories. +* A connected issue source ([GitHub](/factories/integrations/github/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/)) with permission to comment on and update issues. +* A triage policy defining categories, priority levels, required evidence, and when to ask a human. +* A test repository or issue-tracker project outside your production backlog. -## Recommended recipe +## Recommended configuration -Configure one automation that watches a narrow intake event and targets your factory's triage agent. Reuse an existing route when it already handles those requests. +Use the following table to choose the trigger, agent, skills, settings, and expected output for your issue-triage automation. | Part | Recommendation | | --- | --- | -| Trigger | GitHub: `issue_created` or `issue_labeled`; Azure DevOps: `work_item_created` or `work_item_labeled` | +| Trigger | A new issue, a triage label added, or an explicit Jira request | | Agent | Your factory's existing triage agent | | Skills | A repo-specific triage skill with category, priority, reproduction, duplicate-search, and escalation rules | | Settings | Start with one repository and one event; use the Warp Agent harness so built-in code-host tools are available | | Output | One issue update with evidence, classification, priority, and the recommended next stage | -The example below is specific to GitHub and starts on every new issue in one repository. For a controlled rollout, use `issue_labeled` with a label filter. +## Set up issue triage -```markdown title="automations/triage-new-issues/automation.md" ---- -agent: triage -triggers: - - provider: github - event: issue_created - filter: - repos: [acme/payments-service] ---- +1. Use your factory's existing [triage agent](/factories/factory-agents/#triage) and keep its shared instructions intact. +2. Add `agents/triage/skills/issue-triage/SKILL.md`, using your agent's directory name if different. Define allowed categories and priorities, duplicate-search rules, required evidence, and when to ask a human. Require a code location, duplicate issue, log, or reproduction before assigning a root cause. See [factory skills](/factories/factory-skills/) for the file format. +3. Add or edit an automation for your issue source using the examples below. They use `agent: triage`. Replace `triage` if your agent has a different name, and keep the stopping instructions in the automation prompt. -Triage the new issue. Search for duplicates, inspect the relevant code, and -reproduce a bug only when the cause is not already supported by evidence. -Use the repository's triage skill for categories and priority. Ask for missing -evidence rather than guessing. Update the issue with category, priority, scope, -and the next action, then stop. Do not implement or start implementation. -``` + Reuse an existing automation when it already handles those requests. Avoid overlapping routes, including a broad issue-created automation and a label automation that could both start work on the same issue. See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. -For Azure DevOps, use a separate trigger with `provider: azure_devops`. This example starts triage when a work item matches the `needs-triage` label filter: + ### GitHub: Triage newly created issues -```markdown title="automations/triage-new-work-items/automation.md" ---- -agent: triage -triggers: - - provider: azure_devops - event: work_item_labeled - filter: - labels: [needs-triage] ---- + This automation starts on every new issue in `acme/payments-service`. Replace that repository with your own. + + ```markdown title="automations/triage-new-issues/automation.md" + --- + agent: triage + triggers: + - provider: github + event: issue_created + filter: + repos: [acme/payments-service] + --- + + Triage the new issue. Search for duplicates, inspect the relevant code, and + reproduce a bug only when the cause is not already supported by evidence. + Use the repository's triage skill for categories and priority. Ask for missing + evidence rather than guessing. Update the issue with category, priority, scope, + and the next action, then stop. Do not implement or start implementation. + ``` + + For a controlled rollout, change the event to `issue_labeled` and add `labels: [needs-triage]` alongside `repos`. + + ### Azure DevOps: Triage labeled work items -Triage the labeled work item using the repository's triage skill. Update it -with evidence, classification, priority, and the next action, then stop. -Ask for missing evidence rather than guessing. Do not implement or start -implementation. -``` + This automation starts when a work item receives the `needs-triage` label: -This trigger filters work items, not repositories. Work item events accept `assignees`, `authors`, `labels`, and `work_item_types`, but not `repos`. Use `work_item_created` to triage newly created work items that match those filters. See [Azure DevOps events and filters](/factories/integrations/azure-devops/#supported-events-and-filters) for setup and scope. + ```markdown title="automations/triage-new-work-items/automation.md" + --- + agent: triage + triggers: + - provider: azure_devops + event: work_item_labeled + filter: + labels: [needs-triage] + --- -Both examples use `agent: triage`. If your triage agent has a different name, use that name instead. Keep its shared instructions intact; put this workflow's stopping instructions in the automation prompt. + Triage the labeled work item using the repository's triage skill. Update it + with evidence, classification, priority, and the next action, then stop. + Ask for missing evidence rather than guessing. Do not implement or start + implementation. + ``` -## Configure issue triage + Work item events accept `assignees`, `authors`, `labels`, and `work_item_types`, but not `repos`. Use `work_item_created` instead to triage newly created work items that match those filters. See [Azure DevOps events and filters](/factories/integrations/azure-devops/#supported-events-and-filters) for setup and scope. -1. Choose an existing factory with access to the relevant repositories and issue source. Follow the [Warp Factories quickstart](/factories/quickstart/) if you don't have one. -2. Confirm the factory has a [triage agent](/factories/factory-agents/#triage) with read access to the relevant repositories through the code host and write access to issues through the connected issue source. -3. Add `agents/triage/skills/issue-triage/SKILL.md`. Record the allowed categories and priority levels, the evidence required for a bug, and when to ask a human. See [factory skills](/factories/factory-skills/) for the file format. -4. Configure one automation for your issue source: - * **GitHub** - Use the GitHub example above. For a controlled rollout, change the event to `issue_labeled` and add `labels: [needs-triage]` alongside the `repos` filter. - * **Azure DevOps** - Use the separate work item example above, not the GitHub trigger. - * **Linear** - Use `provider: linear` with `issue_created` or `issue_labeled`. Replace the GitHub `repos` filter with Linear team or project filters, and add a label filter for a controlled rollout. - * **Jira** - Check existing `agent_session_created` automations first; [Jira setup](/factories/integrations/jira/#connect-jira-and-add-an-automation) may already have created one for your projects. If all its requests need triage, retarget it to your triage agent and use the triage-only prompt above. If it also handles other workflows, keep that handler and narrow both routes' project or keyword filters so each request matches only one automation before adding a separate triage automation. Adding a keyword filter to the new route alone doesn't exclude it from an existing project-wide route. + ### Linear - See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. -5. Apply the definition changes before testing. For a Warp-managed factory, save the edits in the factory dashboard. For a GitHub-backed factory, merge the changes into its configured production branch. Confirm validation succeeds and the changes are applied. See [where the factory definition lives](/factories/factory-as-code/#where-the-definition-lives). -6. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: + Use `provider: linear` with `issue_created` or `issue_labeled`. Replace the GitHub example's `repos` filter with Linear team or project filters, and add a label filter for a controlled rollout. + + ### Jira + + Use `provider: jira` with `agent_session_created` and a `project_keys` filter. Check existing automations first. [Jira setup](/factories/integrations/jira/#connect-jira-and-add-an-automation) may already have created one for your projects. + + * **All requests need triage** - Retarget the existing automation to your triage agent and use the triage-only prompt above. + * **Other workflows share the handler** - Keep that handler and narrow both routes' project or keyword filters so each request matches only one automation before adding a separate triage automation. + + Adding a keyword filter to the new route alone doesn't exclude it from an existing project-wide route. A triage-only prompt also doesn't stop another automation from starting its own run. + + ### GitLab + + GitLab has no native issue-created trigger. Use an explicit bot mention or a [custom webhook](/factories/webhooks/). + +4. Apply the definition changes. For a Warp-managed factory, save the edits in the factory dashboard. For a GitHub-backed factory, merge the changes into its configured production branch. Confirm validation succeeds and the changes are applied. See [where the factory definition lives](/factories/factory-as-code/#where-the-definition-lives). +5. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: * **Creation intake** - Create an issue for GitHub or Linear, or a work item for Azure DevOps. Include any labels required by the filter when creating it. * **Label intake** - Apply `needs-triage` to a test issue or work item after creating it. * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the issue. Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. For Jira, also test that a non-triage request still reaches its intended handler. -7. Review several results before expanding the repository or event filters. +6. Review several results before expanding the repository or event filters. ## Example workflow @@ -95,13 +114,7 @@ A customer opens `Checkout fails after applying two coupons` in `acme/payments-s The agent labels the issue `bug` and `payments`, assigns the team's `P1` priority according to the skill, and posts the failing test output and affected code path. It recommends implementation because the cause is bounded. If the issue lacks cart data, the agent asks for that evidence and leaves the issue waiting for a human instead. -## Best practices - -* **Use a closed classification set** - Put valid categories and priorities in a skill so the agent doesn't invent labels. -* **Separate evidence from confidence** - Require a code location, duplicate, log, or reproduction before assigning a root cause. -* **Control intake volume** - Begin with a label trigger when issue volume or run cost is uncertain. -* **Prevent duplicate routes** - Don't combine a broad `issue_created` automation with an overlapping label automation. For Jira, check every matching session automation; a triage-only prompt doesn't stop another automation from starting its own run. -* **Control the next step** - This automation requests triage only. To take accepted issues through implementation in the same factory, follow the [issue implementation recipe](/factories/use-cases/issue-implementation/). +To take accepted issues through implementation in the same factory, follow the [issue implementation recipe](/factories/use-cases/issue-implementation/). ## Related pages