issue

Files (1)

• SKILL.md

SKILL.md (first lines)

# issue

Create Linear issues — from a design note's action items, from an existing ticket (iteration), or freeform from a prompt. All modes enforce value-oriented titles via a quality gate and flag well-formed but premature tickets via an advisory scope gate, use an in-chat confirmation gate, and support idempotent re-runs.

The defining design principles of this skill are:

> **The design note is the single source of truth. The skill reads it, derives tickets, and writes Linear ticket IDs back into it. No parallel work-plan file. No re-modeling.**
>
> **Confirm in chat, not via files.** The skill prints proposed tickets in the conversation, confirms with the user in one shot, and creates on approval. One invocation, one session.
>
> **Idempotent re-runs.** A note that's already been linearized has inline `Linear: LIN-NNN` annotations. The skill detects them and updates instead of duplicating.
>
> **Descriptions stay minimal; comments carry the thinking.** A ticket's title and description are stable and concise — what the work is, nothing more. Scope crystallization (additions, reductions, pushback, context, reasoning) happens through comments, which are never rewritten and so preserve the history of thinking. Keep descriptions short and pragmatic. Never use them as a context dump from the design note — the backlink to the note is enough. This principle applies in both filing mode and iteration mode.

## How this fits the broader workflow

```
prompt
  │
  ▼
decision skill  →  design note (with action items in canonical sections)
  │
  ▼
[HITL gate: human reviews, edits, greenlights the note]
  │
  ▼
issue       →  prints proposed tickets in chat
  │
  ▼
[HITL gate: user confirmation]
  │
  ▼
creates tickets + writes Linear: LIN-NNN annotations back into the note
```

The human gate on the design note itself is where the real review happens. By the time `issue` runs, the note is greenlit — ticket derivation is mechanical. The in-chat confirmation is a final sanity check, not a deep review.

## Tools declared in allowed-tools

- File discovery and reading tools (`Glob`, `Grep`, `Read`) — discover and parse the design note
- File editing tool (`Edit`) — append cross-references and Status Log rows back to the note
- URL fetching (`WebFetch`) — follow URLs referenced in the note when enriching ticket descriptions
- User confirmation (`AskUserQuestion`) — the confirmation gate (and batched clarification if needed)
- Linear MCP read tools — search for existing tickets, resolve teams/projects, look up statuses and labels
- `Skill` — invoke the `comment` skill for posting comments to Linear issues
- Linear MCP write tools — create or update the issue on Linear (e.g. `save_issue`)

The skill does not declare `Task` — there is no parallel research phase. Ticket derivation is deterministic and serial.

The skill does not declare `Write` — it never creates new files. It only edits the existing design note (appending cross-references and a Status Log row).

## Phase 0 — Preflight

### Parse invocation and detect mode

Examine the first argument (or the full prompt if no explicit argument):

- **Iteration mode** — if the input contains a Linear issue URL (`https://linear.app/...`) or a bare issue identifier matching the pattern `[A-Z][A-Z0-9]*-\d+` (e.g. `VID-123`, `Z-419`, `A1-221`), enter **iteration mode**. The character class admits digits after the first letter because a team key may contain them; `[A-Z]+` would not match `A1-221`, silently dropping through to freeform mode and filing a *new* ticket instead of iterating on the existing one. Capture the issue ID and the rest of the prompt as the user's intent. Skip to the [Iteration mode](#iteration-mode) section below; do not run the filing-mode phases.
- **Filing mode** — if the input references a decision record path (explicitly or inferable from `docs/decisions/`), enter **filing mode**. Continue with the filing-mode phases below.
- **Freeform mode** — if the input is neither a Linear URL/ID nor a design note path — e.g. "create an issue for X", "file a ticket about Y", "new issue: Z", a bare description of work to be ticketed, or a batch of items to file — enter **freeform mode**. Skip to the [Freeform mode](#freeform-mode) section below.

### Rename the session

After detecting the mode, rename the session to reflect the scope:

Rename the session so the user can identify it at a glance (e.g. in a terminal tab). A good name reflects the mode and scope — e.g. "card layout abstraction (issue)" for filing, "VID-123 OAuth2 Google login (issue:iterate)" for iteration, or "auth token storage (issue:freeform)" for freeform.

If a tool or command is available to rename the session programmatically, use it. Otherwise, suggest the user rename it — but don't block on this. Move on to the next phase either way.

### Triage: check for duplicates and scope overlap

Before creating any new issue — whether from a design note or freeform — run a tiered check to avoid duplicates, scope overlap, and contradictions in the backlog. This applies in both filing mode and when other skills (pair, freeform conversation) route through issue creation to create a ticket.

**Tier 0 — Project fit (always run, before anything else):**

Check whether each proposed ticket belongs in the ambient project or should route elsewhere. Don't default to the current project without questioning it.

Heuristics:
- **References skill files, agent infrastructure, `CLAUDE.md`/`AGENTS.md`, or cross-project tooling** → suggest the KB (Knowledge Base) project.
- **References product code, features, domain concepts, or user-facing behavior** → keep in the current project.
- **References CI/CD, deployment, or repo-specific infrastructure** → keep in the repo's own project.
- **Ambiguous** → surface it: "This looks like it might belong in {other-project} — route there, or keep in {current-project}?"

When filing a batch, run the check per ticket — different items may route to different projects. If any ticket routes differently from the ambient project, flag it explicitly in the confirmation output (Phase 3).

**Tier 1 — Current work (always run, lightweight):**
- Check the current branch and the last 2 branches worked on (`git branch --sort=-committerdate | head -3`).
- Cross-reference with GitHub — list pull requests and read PR details (e.g. `list_pull_requests`, `pull_request_read`) to confirm merge state — local state may be stale.
- If an in-progress branch covers this scope, surface it: "This looks like it fits in VID-XYZ which is still on branch X — want me to fold it in?"

**Tier 2 — Related issues (always run):**
- If a ticket ID is known (from the branch name, the design note, or the user's prompt), fetch the issue from Linear (e.g. `get_issue`) with relations included and check its related issues.
- Scan the related issues for scope overlap or contradictions with the proposed new ticket.

**Tier 3 — Backlog scan (run when the issue is complex or duplicates seem likely):**
- Search for related issues on Linear (e.g. `list_issues`, filtered by project and team) for tickets with similar titles or keywords.
- If matches are found, present them: "These existing tickets look related — should we extend one of them, or is this genuinely new?"
- Propose resolution: merge scopes, re-prioritize an existing ticket, mark as duplicate, or confirm isolation.

If the triage surfaces a match, ask the user to choose:
- **Fold into VID-XYZ** — add scope to the existing ticket (comment the new context)
- **Stack on VID-XYZ** — create as a sub-issue or related issue
- **Mark as duplicate** — set `duplicateOf` on the old ticket, transition to Cancelled, and **comment why** on the cancelled ticket (see cancellation rule below)
- **Create new** — confirmed isolated, proceed with filing
- **Cancel** — the user decides to handle it differently

Only proceed to filing after the user confirms the triage result.

### Cancellation and duplication rule

**Every ticket state change that removes a ticket from the active backlog (Cancelled, Duplicate) must carry a comment explaining why.** A cancelled ticket with no explanation is a dead end for anyone reviewing the backlog later — they can't tell if it was superseded, descoped, invalid, or accidentally closed.

When cancelling or duplicating a ticket:
1. Post a comment via `/comment` with a heading like "Cancelled: {reason}" or "Duplicated by {TICKET-ID}"
2. Include a one-sentence explanation of why (e.g. "KB-36 bundles this rename with two others — same mechanical pattern, one ticket instead of three")
3. If superseded by another ticket, reference it so readers can follow the chain

This rule applies regardless of which skill triggers the cancellation — `/issue` triage, `/pair` scope discovery, or manual operator action. If the operator cancels directly, suggest the comment.

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb