Execution Tickets
Generate scoped engineering tickets from document blocks and push to GitHub, Linear, or Jira.
Overview
Execution tickets bridge the gap between product documents and engineering work. After structuring a document into typed blocks in the PM IDE, you can generate scoped tickets — each with a title, description, acceptance criteria, priority, effort estimate, and labels — then review, edit, and push them to GitHub, Linear, or Jira in bulk.
How It Works
Structure your document into blocks
Open a document in the PM IDE and ensure it has typed blocks (problem, persona, solution, user_story, metrics, etc.). The quality of generated tickets depends on the specificity of each block.
Generate tickets
Call POST /api/execution/generate with your workspace_id, document_id, and optionally an include_block_types filter to focus on specific block types (e.g., only user_story and solution blocks).
The AI agent analyses each block and produces one or more scoped tickets. Each ticket includes:
| Field | Description |
|---|---|
title | Concise ticket title |
body | Detailed description in Markdown |
ticket_type | Default: task |
priority | P0 (critical), P1 (high), P2 (medium), P3 (low) |
labels | Suggested labels |
acceptance_criteria | Checklist of completion criteria |
estimated_effort | Qualitative effort estimate |
Review and edit
Generated tickets start with status generated. Review each one and make edits via PATCH /api/execution/tickets/{ticket_id}:
You can update the title, body, priority, labels, acceptance criteria, and effort estimate before pushing.
Push to your platform
Push tickets to GitHub, Linear, or Jira with POST /api/execution/push:
{
"workspace_id": "your-workspace-uuid",
"document_id": "doc-uuid",
"platform": "github",
"ticket_ids": ["ticket-uuid-1", "ticket-uuid-2"]
}If you omit ticket_ids, all reviewed tickets for the document are pushed.
Ticket Status Flow
generated → reviewed → pushed
→ push_failed
pushed → synced
| Status | Description |
|---|---|
generated | AI-generated, pending review |
reviewed | Edited and approved for push |
pushed | Successfully created on the external platform |
push_failed | Push attempt failed (see push_error field) |
synced | Status synced back from external platform |
Platform-Specific Behaviour
GitHub
Issues are created with the ticket title, Markdown body, and labels. Priority is included in the body text.
Linear
Priority maps to Linear's priority system: P0 → Urgent (1), P1 → High (2), P2 → Medium (3), P3 → Low (4). Issues are created in the selected team with optional project assignment.
Jira
Issues are created with the configured project key and issue type. Priority and labels are mapped to Jira fields.
Syncing Status
After pushing, sync ticket status from the external platform:
POST /api/execution/sync
{
"workspace_id": "your-workspace-uuid",
"document_id": "doc-uuid"
}The response reports how many tickets were synced, unchanged, or had errors.
Key Concepts
- Block-level traceability — Each ticket links back to its source block via the
BlockTicketLinkrelationship, maintaining full traceability from engineering ticket → document block → recommendation → insight → research source. - Bulk push — Push multiple tickets to the same platform in one operation. Failed pushes don't block successful ones.
- Pre-push review — The review step ensures no auto-generated ticket reaches your issue tracker without human approval.
You can also generate tickets from the chat agent: "Generate execution tickets from my onboarding PRD and push them to Linear."
What's Next
Understand how the AI agent selects models and effort levels in the Models & Effort Levels guide.
Was this helpful?