Smart Issue Creation

Turn a request into one issue or a reviewed plan of several issues. Discuss and edit the proposed work before approving creation.

Overview

Instead of manually filling in every field when creating an issue, you can describe it in plain English and let AI do the structuring. Velocity’s planner suggests actionable work with a title, description, acceptance criteria, priority, team, labels and project. Simple requests can stay as one issue; larger requests can become several independent deliverables. When the scope is unclear, answer its questions before creating anything.

Plan Requirement

Smart issue creation uses the AI Triage feature, which requires the Business plan or higher.

How to Use

1

Click the AI button

On the Issues page, click the AI button (sparkle icon) in the toolbar next to “+ New Issue”. This opens “Plan issues with AI”.

2

Describe the issue

Paste screenshots with Ctrl+V or Cmd+V, or choose Attach screenshot. You can attach up to three PNG, JPEG or WebP images per plan, up to 4 MiB each, both initially and when refining. Review the previews and remove any image before submitting. Retry or remove failed uploads before analyzing. AI receives the image contents and can include relevant screenshots in proposed issue descriptions. Draft screenshots are private and expire after 24 hours.

Type a free-form description in the text area. Be as detailed as you like. For example:

The checkout page crashes on Safari when using Apple Pay.
This is high priority and should be assigned to the
Engineering team. Tag it as a bug.

Press Cmd+Enter (or click Analyze request) to submit.

3

Review AI suggestions

Review the explanation and the count of selected proposals. Click a proposal to expand its editable fields:

  • Title — a concise, actionable issue title
  • Description — a well-structured description with context
  • Priority — inferred from your description (Urgent, High, Medium, Low, None)
  • Team — the most relevant team from your workspace
  • Project — a matching project, if one fits
  • Labels — relevant labels from your workspace

Edit fields directly, select or exclude proposals, add or remove items, and choose proposed parents. Descriptions support screenshots and images. Direct edits stay protected during whole-plan AI refinements. Use Refine this item to explicitly ask AI to revise one item, including its protected fields, while preserving the other proposals.

Send further feedback with Refine plan: request changes, a split, a merge or a clearer scope. Repeat until the selection is right. Expand Compare with the previous proposals to review the previous titles, descriptions and selections. Each analysis uses your AI allowance; manual review and saved edits use no AI. After approval, created issues follow your normal workspace automations.

4

Approve the selected issues

Use Save edits for review after manual changes, then click Approve and create N issues. This creates exactly the latest selected proposals and shows links to the resulting issues. Selected subissues need their proposed parent selected too.

Analysis, feedback, editing and closing the dialog create no issues. If creation fails validation, the entire batch is rolled back. If a response is lost, load the saved plan or creation receipt before trying again: the same approved revision returns its existing issues rather than creating duplicates. A changed plan must be reviewed again.

How It Works

Behind the scenes, the AI Create flow:

  • Fetches your workspace context (teams, labels, projects, statuses, and statuses) to ground proposals in your workspace
  • Sends your description to the LLM with a structured prompt requesting JSON output
  • Saves private drafts and conversation separately from issues, and checks current access, workspace fields, issue limits and the approved revision before committing the selected batch
  • Tracks token usage and cost against your workspace’s AI budget

Conversational API and CLI

Use the same endpoint with mode: "plan" for the reviewed workflow. The management CLI supports this payload through velocity ai smart-create --input @plan.json (or vel ai smart-create). Its selected workspace is supplied automatically. Authentication must allow the selected workspace and issue writes.

{
  "mode": "plan",
  "action": "analyze",
  "planId": "a-client-generated-uuid",
  "revision": 0,
  "text": "Fix checkout and update its documentation",
  "proposals": []
}

Keep the returned plan.id, plan.revision and complete plan.proposals. For subsequent analysis, send the current revision and proposals with new text; optionally set targetId to refine one proposal. action: "save"saves manual edits and returns a new revision. action: "read"loads the latest private draft or creation receipt without AI.

{
  "mode": "plan",
  "action": "approve",
  "planId": "the-saved-plan-uuid",
  "revision": 2,
  "approved": true,
  "selection": ["selected-proposal-uuid-in-displayed-order"]
}

Approval must use the saved revision and its exact ordered selected IDs. Retry that same approval after a network failure, or read its receipt; never start a new plan merely to retry creation. The approved batch returns issues and replayed. Drafts are private to their author in the workspace and are included in their scoped account export.

Tips for Best Results

  • Be specific — mention the area of the app, the expected vs. actual behavior, and the severity
  • Name teams and labels — if you say “assign to Engineering” or “tag as bug”, the AI will match them precisely
  • Set priority explicitly — saying “high priority” or “urgent” maps directly to the priority field
  • Always review — AI suggestions are a starting point, not the final word. Adjust any field before confirming.

Single-suggestion API

Existing callers without mode continue to receive one suggestion from POST /api/ai/smart-create. This mode never creates an issue:

POST /api/ai/smart-create
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "text": "High priority bug: checkout crashes on Safari with Apple Pay",
  "workspaceId": "workspace-uuid"
}

// Response:
{
  "suggestion": {
    "title": "Checkout crashes on Safari with Apple Pay",
    "description": "The checkout page crashes when...",
    "priority": "HIGH",
    "teamId": "team-uuid",
    "teamName": "Engineering",
    "labelIds": ["label-uuid"],
    "labelNames": ["bug"],
    "projectId": null,
    "projectName": null
  },
  "usage": {
    "inputTokens": 850,
    "outputTokens": 120
  }
}