issue-create

What this skill does

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).


# Issue Create

## Purpose

Create a new ticket/issue for tracking work items, bugs, features, or tasks. Automatically uses the configured ticketing provider (Gitea, GitHub, Jira, Linear) or falls back to local file-based tracking.

## Task

Given a ticket title and optional description:

1. **Load configuration** from `.aiwg/config.yaml` or project `CLAUDE.md`
2. **Validate configuration** and authenticate with provider
3. **Check for regressions** (if bug report with `--check-regression`)
4. **Create ticket** using appropriate backend (MCP, CLI, or local file)
5. **Return ticket reference** (issue number, URL, or file path)

## Parameters

- **`<title>`** (required): Short, descriptive title for the ticket
- **`[description]`** (optional): Detailed description of the work item
- **`--provider NAME`** (optional): Override configured provider (gitea|github|jira|linear|local)
- **`--labels "label1,label2"`** (optional): Comma-separated labels/tags
- **`--assignee USER`** (optional): Assign to specific user
- **`--priority LEVEL`** (optional): Priority level (low|medium|high|critical)
- **`--milestone NAME`** (optional): Associate with milestone (provider-dependent)
- **`--check-regression`** (optional): Run regression check for bug reports (auto-runs if labels include "bug" or "regression")

## Inputs

**Configuration sources** (checked in order):
1. `.aiwg/config.yaml` - Project-level configuration
2. `CLAUDE.md` - User-level configuration
3. Default: `local` provider

**Required for Gitea**:
- Provider: `gitea`
- URL: Base URL (e.g., `https://git.integrolabs.net`)
- Owner: User or organization name
- Repo: Repository name
- Token: `~/.config/gitea/token` (or configured path)

**Required for GitHub**:
- Provider: `github`
- Owner: User or organization name
- Repo: Repository name
- Auth: `gh` CLI authenticated

**Required for Jira**:
- Provider: `jira`
- URL: Jira instance URL
- Owner: Project key
- Auth: `JIRA_API_TOKEN` environment variable

**Required for Linear**:
- Provider: `linear`
- URL: `https://api.linear.app`
- Owner: Team ID
- Auth: `LINEAR_API_TOKEN` environment variable

**Required for Local**:
- Provider: `local`
- Directory: `.aiwg/issues/` (created if missing)

## Outputs

**Gitea/GitHub/Jira/Linear**:
- Issue created on remote system
- Issue number returned
- URL to view ticket

**Local**:
- File created: `.aiwg/issues/ISSUE-{num}.md`
- Issue number returned
- File path returned

## Workflow

### Step 1: Parse Parameters

Extract from command invocation:

```bash
# Basic usage
/issue-create "Implement user auth"

# With description
/issue-create "Fix navigation bug" "Nav menu not showing on mobile devices"

# With labels
/issue-create "Add dark mode" "Implement theme toggle" --labels "feature,ui"

# With assignee
/issue-create "Security audit" "Run penetration test" --assignee "security-team" --priority high

# Bug report with regression check
/issue-create "Login broken after deployment" "Users can't login" --labels "bug,critical" --check-regression

# Override provider
/issue-create "Local task" "Quick reminder" --provider local
```

**Parameter extraction**:
- Title: First quoted argument (required)
- Description: Second quoted argument (optional, default: empty)
- Flags: Parse `--flag value` pairs

### Step 2: Load Configuration

**Resolution precedence** (highest first):

1. **`--provider` flag** — explicit override always wins.
2. **`.aiwg/aiwg.config` `remotes.issue_tracker`** (#994) — derive provider from the remote's URL.
3. **Legacy `.aiwg/config.yaml`** (`ticketing` block) — back-compat for older projects.
4. **`CLAUDE.md` "Issueing Configuration" block** — fallback for projects pre-dating either.
5. **`local`** — default if nothing is configured.

**Resolving from `.aiwg/aiwg.config`** (the preferred path):

```ts
import { readAiwgConfig, resolveRemotes, resolveRemoteProvider } from 'aiwg/config';

const cfg = await readAiwgConfig(projectDir);
const resolved = resolveRemotes(cfg?.remotes);
// resolved.issue_tracker is a git remote name (defaults to "origin")

// Resolve the URL via `git remote get-url <name>`
const url = exec(`git remote get-url ${resolved.issue_tracker}`).trim();
const provider = resolveRemoteProvider(url); // 'gitea' | 'github' | 'gitlab' | 'unknown'
```

When `provider === 'unknown'` (self-hosted instances we can't classify by URL), the operator must pass `--provider` explicitly. Don't guess.

**Worked example for this repo** (`origin` → `git.integrolabs.net/roctinam/aiwg`):

- `resolved.issue_tracker` = `'origin'`
- `git remote get-url origin` = `[email protected]:roctinam/aiwg.git`
- `resolveRemoteProvider(url)` returns `'unknown'` (the host doesn't include "gitea")
- → operator must set `--provider gitea`, OR the project's `aiwg.config` providers list must explicitly include `gitea` so we can fall through to that.

**Override warning**: if `--provider` differs from the auto-resolved one, print:
`⚠️ Using --provider github (resolved from .aiwg/aiwg.config: gitea)`

### Step 3: Regression Detection (for Bug Reports)

**Trigger conditions**:
- Explicit: `--check-regression` flag provided
- Automatic: `--labels` contains "bug" OR "regression"
- Type: Issue is categorized as bug/defect

**Regression check process**:

```bash
# Detect if regression check should run
if [[ "$LABELS" == *"bug"* ]] || [[ "$LABELS" == *"regression"* ]] || [[ "$CHECK_REGRESSION" == "true" ]]; then
  echo "⏳ Running regression check..."

  # Run regression check against main branch
  /regression-check --baseline main --scope changed-files --format summary > /tmp/regression-results.md

  # Parse results
  REGRESSION_DETECTED=$(grep "REGRESSIONS DETECTED" /tmp/regression-results.md)

  if [ -n "$REGRESSION_DETECTED" ]; then
    # Escalate priority and add labels
    PRIORITY="critical"
    LABELS="${LABELS},regression-confirmed"

    # Extract regression details for issue body
    REGRESSION_SUMMARY=$(sed -n '/### Critical Regressions/,/###/p' /tmp/regression-results.md)

    # Append to description
    DESCRIPTION="${DESCRIPTION}

---

## Regression Analysis

${REGRESSION_SUMMARY}

**Full Report**: See attached regression-results.md"
  else
    # No regression detected
    LABELS="${LABELS},no-regression"
  fi
fi
```

**Impact on issue creation**:

| Regression Status | Priority | Labels | Action |
|-------------------|----------|--------|--------|
| REGRESSION DETECTED | Critical | bug, regression-confirmed | Escalate, include analysis |
| NO REGRESSION | Original | bug, no-regression | Standard bug workflow |
| CHECK FAILED | Original | bug, regression-check-failed | Create issue, note failure |

### Step 4: Validate Configuration

**For each provider, validate required fields**:

**Gitea**:
- [ ] `url` present and valid URL
- [ ] `owner` present
- [ ] `repo` present
- [ ] Token file exists and readable

**GitHub**:
- [ ] `owner` present
- [ ] `repo` present
- [ ] `gh` CLI installed (`which gh`)
- [ ] `gh` authenticated (`gh auth status`)

**Jira**:
- [ ] `url` present and valid URL
- [ ] `owner` (project key) present
- [ ] `JIRA_API_TOKEN` environment variable set

**Linear**:
- [ ] `url` present (default: `https://api.linear.app`)
- [ ] `owner` (team ID) present
- [ ] `LINEAR_API_TOKEN` environment variable set

**Local**:
- [ ] `.aiwg/issues/` directory exists or can be created
- [ ] Directory is writable

**Error handling**:
- If validation fails, re