linear-issue-creator

What this skill does

# Linear Issue Creator Skill

## Purpose

Transform a natural-language request into a fully-structured Linear issue. The skill discovers and explores the target project — from GitHub or a local path — before writing, so the issue description contains real, sourced technical content rather than placeholders.

**Always runs in the main Claude Code session** (never as a sub-agent), because it calls `mcp__linear-server__save_issue` directly.

---

## Input Expected from User

Minimum:
```
"Crée une issue pour [description libre]"
"Issue sur [sujet]"
```

Optional enrichments:
- **Project source** (one of):
  - GitHub URL: `https://github.com/org/repo`
  - Local path: `D:\Projects\my-app` or `/home/user/my-app`
  - Current working directory (implicit if not specified)
- **Linear project name**: which Linear project to file the issue under (e.g. `Rikka`, `Desktop App`)
- **Type hint**: "c'est un bug" / "feature" / "tech-debt" / "hotfix" / "idée"
- **Priority hint**: "urgent" / "important" / "mineur"
- **Source label**: "remontée client" / "idée PO" / dev interne

**If neither a GitHub URL nor a local path is given**, and the request topic does not obviously match the current working directory, ask the user:
> "Sur quel projet dois-je créer cette issue ? Donne-moi une URL GitHub ou un chemin local."

---

## Workflow

### Step 0: Resolve Project Source

Determine **where** to read project context from.

#### Case A — GitHub URL provided

Use `gh` CLI (already authenticated, works for private and public repos).

```bash
# 1. Extract org/repo from the URL
#    https://github.com/org/repo  →  org/repo

# 2. Get the full file tree
gh api repos/{org}/{repo}/git/trees/HEAD?recursive=1 \
  --jq '[.tree[] | select(.type=="blob") | .path]'

# 3. Read README
gh api repos/{org}/{repo}/contents/README.md \
  --jq '.content' | base64 -d

# 4. Read key structural files (package.json, requirements.txt, go.mod,
#    Cargo.toml, docker-compose.yml, Makefile — whichever exist)
gh api repos/{org}/{repo}/contents/{path} \
  --jq '.content' | base64 -d

# 5. Read files most relevant to the issue topic (found in tree from step 2)
#    Limit to 4–5 files total.
```

Stop after the tree + 5 file reads. Work with what you have.

#### Case B — Local path provided (or current directory)

```
1. Glob: {path}/**/* to get the file tree (limit to first 200 results)
2. Identify: language/stack, main directories, framework patterns
3. Read key structural files: package.json / requirements.txt / Cargo.toml /
   go.mod / *.csproj / Makefile / docker-compose.yml (whichever exist)
4. Look for documentation: README.md, docs/, wiki/, any *DOC* folders, Obsidian vaults
```

#### Project structure fingerprinting

After initial discovery, identify:

| Signal | What it tells you |
|--------|------------------|
| `package.json` with React/Vue/Angular | Frontend JS/TS project |
| `requirements.txt` / `pyproject.toml` | Python backend |
| `*.csproj` / `*.sln` | .NET project |
| `go.mod` | Go project |
| `Cargo.toml` | Rust project |
| `docker-compose.yml` | Multi-service architecture |
| `[DOC]-*/` or `docs/` or `wiki/` | Has documentation vault |
| `*obsidian*` or `.obsidian/` | Obsidian documentation vault |

This fingerprint guides exploration in Step 2.

---

### Step 1: Classify the Issue Type

Apply this decision tree (first match wins):

```
Does the request describe a broken behavior in something that exists?
  ("ça marche pas", "bug", "broken", "ne se supprime pas", "erreur", "reste bloqué")
      → BUG

Is it an active production emergency — service down, critical function broken right now?
  ("urgent prod", "bloquant pour les users maintenant", "service down", "prod cassée")
      → HOTFIX

Is it cleanup / refacto / dependency update / technical debt with no new user-facing capability?
  ("clean", "refacto", "extraire", "mettre à jour la lib", "dette technique", "sécurité code")
      → TECH-DEBT

Is it a clearly scoped new capability — we know what it does and who benefits?
  ("ajouter X", "permettre à l'utilisateur de Y", "nouvelle page Z", "implémenter")
      → FEATURE

Otherwise (vague, exploratory, "tester si…", "voir pour…", beneficiary or scope unclear):
      → IDÉE
```

The user's type hint is a **clue, not a verdict**. Apply the tree and justify any override.

**Priority mapping:**

| User hint | Value |
|-----------|-------|
| "urgent" / "prod cassée" / "bloquant" | 1 (Urgent) |
| "important" / "high" | 2 (High) |
| no hint | Template default — Bug→2, Feature→3, Tech-Debt→4, Idée→0, Hotfix→1 |
| "mineur" / "nice to have" / "low" | 4 (Low) |

---

### Step 2: Research Project Context

**Goal**: produce real, sourced content for the issue description. Never invent technical details.

#### 2a. Adaptive exploration strategy

Search for the **key terms from the user's request** first:

```
# For local projects:
Grep: pattern="{keyword}" path="{project_root}" — to find relevant files

# Then read the files found:
Read: {file_path}  ← focus on the relevant sections
```

Then adapt depth based on issue type:

**BUG** — find the broken component:
- Where is the code path that handles the described behavior?
- What function / class / component / endpoint is involved?
- Are there existing error logs, tests, or comments that mention this issue?

**FEATURE** — find the integration surface:
- Is there an existing similar feature to use as a model?
- What services, APIs, DB tables, or components would be touched?
- Are there related issues, TODOs, or commented-out code?

**TECH-DEBT** — measure the scope:
- Which specific files / patterns are problematic?
- How many occurrences? What's the blast radius of a refactor?
- Are there existing tests covering the affected code?

**IDÉE** — check for overlap:
- Does a similar feature already exist in the codebase?
- Are there any existing issues, TODOs, or feature flags related to this idea?

**HOTFIX** — find the immediate source:
- What's the specific file/function causing the production error?
- Is there a recent commit that could have introduced it?

#### 2b. Documentation discovery

After exploring the code, look for project documentation:

```
Priority order for reading docs:
1. Specification files: CDC-*.md, spec-*.md, requirements-*.md
2. Database/schema docs: DB-*.md, schema.md, ERD files
3. Architecture docs: ARCH-*.md, architecture.md, ADR-*.md
4. Feature specs: FEAT-*.md, features/*.md
5. README and general docs
```

Use `Glob` to find documentation files:
```
{project_root}/**/*.md        ← all markdown
{project_root}/**/ADR-*.md   ← architecture decisions
{project_root}/**/*spec*.md  ← specifications
```

If a documentation vault exists (Obsidian or otherwise), check it for existing feature specs related to the issue topic before writing the description.

#### 2c. Stop condition

Stop researching when you have:
- The file path(s) most relevant to the issue
- An understanding of what already exists vs. what's new
- Enough context to write the acceptance criteria

**Maximum research budget**: ~10 file reads or web fetches. If you haven't found what you need, write "_à préciser_" for that section rather than inventing.

#### 2d. Zero hallucination rule

Every technical claim in the description must be either:
- **Sourced**: `"d'après \`path/to/file.py:42\`…"`, `"cf. FEAT-009…"`, `"service X dans docker-compose.yml"`
- **Flagged as uncertain**: `"_à confirmer lors de la phase spec_"`

Never invent file paths, function names, table names, or behaviors.

---

### Step 3: Build the Issue

#### 3a. Fill the correct template

Use the exact template structure from `references/linear-templates.md`. Copy section headers verbatim.

**Filling rules:**

**Context / Why** (Feature, Tech-Debt, Idée):
- One factual paragraph explaining the business/technical need
- Source everything: `"cf. \`src/services/auth.ts\`"`, `"d'après la doc ARCH-*.md"`

**Symptom / Reproduction** (Bug, Hotfix):
- Use real file paths and component names found in Step 2
- If rep