Smart Issue Creation

Create issues from natural language descriptions. AI extracts structured fields for you to review before confirming.

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 smart creation parses your description and suggests a title, description, priority, team, labels, and project — all constrained to valid values from your workspace.

Plan Requirement

Smart issue creation uses the AI Triage feature, which requires the Pro 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 the AI Create dialog.

2

Describe the issue

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 Generate) to submit.

3

Review AI suggestions

The dialog switches to an editable form pre-filled with AI-suggested values:

  • 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

Every field is editable. Change anything that doesn’t look right before creating the issue.

4

Create the issue

Click Create Issue to submit. The issue is created with all the fields you reviewed, exactly as if you had filled them in manually.

How It Works

Behind the scenes, the AI Create flow:

  • Fetches your workspace context (teams, labels, projects, statuses, members) so the LLM can only suggest valid values
  • Sends your description to the LLM with a structured prompt requesting JSON output
  • Validates all returned IDs against your actual workspace data — if the LLM returns an invalid team or label ID, it falls back gracefully
  • Tracks token usage and cost against your workspace’s AI budget

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.

API Endpoint

The smart creation is also available via the REST API at POST /api/ai/smart-create:

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
  }
}