docs: add Factory issue triage recipe

[warp-agent-staging]

What this feature does

An issue-triage factory investigates incoming issues, applies a controlled classification and priority, and records the evidence a maintainer needs to choose the next step.

Summary

Replaces the issue-triage scaffold with a practical recipe built from validated automation, role, skill, and integration patterns.

Changes

src/content/docs/factories/use-cases/issue-triage.mdx

• Defines prerequisites, a recommended recipe, and example factory configuration.
• Adds a six-step rollout procedure, example workflow, best practices, and related references.
• Adds explicit GitHub and Azure DevOps issue-event mappings, provides separate provider-specific setup, and documents the GitLab trigger gap.

Content design plan

Audience and JTBD: A maintainer with a busy engineering backlog who needs new issues categorized and supported by evidence before assigning implementation work.

Problem: Factory primitives are documented separately, so the reader must infer how to combine an issue event, triage role, policy skill, and issue update.

Goals:

• The reader can configure a narrow issue-triage automation.
• The reader can define consistent categories, priorities, evidence, and escalation.
• The reader can confirm the agent stops before implementation.

Purpose and value: The guide provides a reusable first automation that reduces repeated intake work while preserving product judgment.

Content type: Feature documentation (combined) — the reader needs the workflow model and the configuration procedure together.

Skill and template: draft_feature_doc / .agents/templates/feature-doc.md.

High-impact scenarios:

• Covers: issue intake from GitHub, Azure DevOps, and Linear; explicit Jira agent-session requests; controlled label rollout; evidence-backed issue updates.
• Excludes: automatic implementation and a native GitLab issue-created trigger, which is not currently available.

Source files consulted

Implementation sources read on 2026-10-16 at warpdotdev/warp-server@91da52f5b26cde1472da76fd49ddb28fe74f91f9:

• model/types/triggers/triggers.go: canonical provider events. Its kind catalogue defines accepted filters and the GitLab event set; the Azure DevOps work-item filter has no repos field.
• logic/factoryfile/schema/automation.go: generates schemas from the trigger filter catalogue. This establishes the configuration contract, not deployed provider delivery.
• client/packages/factory/src/pages/FactoryAutomations/jira.ts: lists editor events, including issue creation, labels, status changes, and agent sessions.

Documentation consulted at warpdotdev/docs@24b4a6c25c57298fc63f15b27458423041ef3466: src/content/docs/factories/factory-as-code.mdx and the azure-devops.mdx, linear.mdx, and jira.mdx pages under src/content/docs/factories/integrations/ (provider setup, filters, and access).

Live configuration evidence

Checked on 2026-10-16 through the connected staging Factory MCP:

• get_factory_file_schema(document: automation.schema.json) returned v1alpha1, including common.schema.json. Documents checked: automation schema and shared definitions. These URLs are mutable; implementation sources above are pinned.
• validate_factory_files reproduced FF_INVALID_EVENT for github.work_item_created and FF_INVALID_FILTER for azure_devops.work_item_created with filter.repos.
• A complete validation tree with a minimal factory root, foreman, recipe triage agent, both automation examples, and rollout variants returned valid: true, no diagnostics, and no deferred resolutions. Variants covered GitHub issue_labeled, Azure DevOps work_item_created, Linear issue_created and issue_labeled, and Jira agent_session_created.
• Validation did not run provider-alias resolution or state-dependent model, environment, secret, runner-reference, MCP-server, integration, worker-host, or entitlement checks. No provider-triggered runs were started.

Unverified claims

• End-to-end event delivery, provider permissions, issue updates, and agent stopping behavior have not been exercised in live provider workflows for this recipe.
• The Jira guide says factories receive only agent sessions, while the server catalogue and editor also list issue events. Automatic Jira issue intake remains unverified; the recipe uses the documented agent-session route.
• The original claim that all described behavior shipped in v0.2026.10.07.08.29.stable_00 (2026-10-07) lacks verified release/deployment evidence. It has been removed from the feature summary pending confirmation. Current source and staging schema acceptance do not prove stable availability.

Documentation risk

Risk: engineering-review-required
Rationale: Adds new public Factory workflow guidance and configuration examples that require product review.
Docs override: none

PR stack

• #895 — Navigation and structure
• #896 — Issue triage
• #897 — Code review
• #898 — Issue implementation
• #899 — Production incident resolution
• #900 — Computer Use verification
• #901 — End-to-end SDLC automation

Dependency: #895 is the shared base and targets main. PRs #896–#901 each independently target factory/factory-use-cases-structure; no guide PR depends on another guide PR.

Human review focus

• Confirm the native issue-source matrix and GitLab limitation.
• Confirm the recommended boundary between triage and implementation.

Co-Authored-By: Oz oz-agent@warp.dev

Co-Authored-By: Warp agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 17, 2026 9:14pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  

Test changes

No affected Factories to test.

[warp-for-oss]

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR replaces the issue-triage use-case scaffold with a practical Factory recipe that covers prerequisites, an example GitHub automation, rollout steps, and related references.

Concerns

• The prerequisites describe issue-write access as a code-host integration permission even though the page also covers Linear and Jira, where issue updates are granted by the issue-tracker integration rather than the code-host integration.
• The Linear/Jira rollout instruction sends readers to provider docs for event names instead of naming the supported issue-triage events or linking the schema reference.

Comment and test audit

• Added or changed comments: none; the old scaffold comment is removed.
• Added or changed tests: none; this is a documentation-only change.
• Security pass: no security findings.
• Spec alignment: no approved or repository spec context was provided.

Verdict

Found: 0 critical, 1 important, 1 suggestions

Request changes

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

⚠️ [IMPORTANT] This prerequisite is scoped to code hosts, but the page also lists Linear and Jira; for those providers, issue comments, labels, assignments, or status updates come from the issue-tracker integration rather than the code-host integration.

[warp-for-oss]

💡 [SUGGESTION] Name the Linear and Jira event values here, or link the trigger schema, so readers can complete the rollout without hunting through provider pages that don't consistently list definition-file event names.

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/use-cases/issue-triage.mdx:66 (also line 30) — [CRITICAL] The Azure DevOps instructions substitute work_item_created or work_item_labeled into the GitHub example without explaining the required provider and filter changes. Live factory validation rejects github.work_item_created with FF_INVALID_EVENT; changing provider to azure_devops still produces FF_INVALID_FILTER because repos is unsupported for work-item events. Requested resolution: add a separately validated Azure DevOps example using provider: azure_devops and supported filters (assignees, authors, labels, or work_item_types), explain its scope, and update both passages consistently; alternatively, keep the recipe GitHub-only and link to the Azure DevOps integration guide instead of giving an incomplete substitution.

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/use-cases/issue-triage.mdx:92 — [IMPORTANT] Opening a test issue alone does not trigger the label-based GitHub, Linear, or Azure DevOps options or Jira agent_session_created. Requested change: make the test exercise the selected event by applying needs-triage for label intake, assigning or mentioning Warp for Jira, or creating an issue or work item for creation intake, then verify the run's updates and stopping behavior.
• src/content/docs/factories/use-cases/issue-triage.mdx:13 — [SUGGESTION] The PR cites no Source files consulted, so its runtime provider claims and asserted release availability cannot be independently checked from cited implementation sources; live schema validation only establishes configuration validity. Requested change: add source paths with revisions or precise live evidence to the PR body, identify the schemas checked, and list any remaining unverified behavior under Unverified claims.

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/use-cases/issue-triage.mdx:80 — [IMPORTANT] Step 4 adds a Jira agent_session_created automation filtered only by project, but factories connected to Jira during creation already have an automation for those sessions. Both routes can start runs, and the triage prompt does not stop the existing handler. Requested change: reuse and retarget the existing Jira automation where appropriate, or narrow or disable overlapping routes so each triage request matches only one automation while preserving other workflows.

Verdict

Request changes