# Sks Issue

> Use when opening an issue in shikanime-labs or shikanime-studio: body is the problem statement, acceptance criteria as a command-decidable tasklist.

- Skill: `shikanime-labs/sks-issue` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add shikanime-labs/sks-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shikanime-labs/sks-issue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: shikanime-labs (https://skillmd.com/u/shikanime-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shikanime-labs/sks-issue

---


# Shikanime Org Issue Creation

Open issues in `shikanime-labs/*` / `shikanime-studio/*`; English (no French).
Open the issue before the PR, link it via `sks-pr`.

Prereqs: `gh` authenticated to the canonical org repo; target it directly.
`gh auth status` clean.

## When to Use

- "Create a new shikanime issue."
- "Track and manage a shikanime GitHub issue."
- "Verify issue exists before opening a PR (issue-first policy)."

## Procedure

### 0. Check for existing issues

Search before creating to avoid duplicates:

```bash
gh issue list --repo <org>/<repo> --state all --search "<keywords>" --limit 10
```

If an open (or recently closed) issue matches, surface the `#N` and confirm with
the user whether to reuse it instead of opening a new one. Only create when no
matching issue exists (or the user explicitly wants a fresh ticket).

### 1. Repo + type

```bash
gh issue create --repo <org>/<repo> --title "<summary>" --label <type> --body "..."
```

- Bug: `--label bug`. Feature: `--label enhancement`.
- Verify repo labels first: `gh label list --repo <org>/<repo> --limit 100`.

### 2. Body = problem statement only

GitHub issue body is free text — never wrap lines and never insert hard line
breaks at a column width. Write natural paragraphs; a blank line separates
paragraphs and everything else renders as-is. Never run `nix fmt` / `mdformat`
over an issue body; those tools enforce an 80-column wrap that does not apply
to GitHub bodies.

- A bare `@name` in prose pings that user/team — wrap any literal `@` (NestJS
  `@Inject(x)`, decorators, config keys) in a code span or fenced block; only
  code disables mention parsing.

Body = clean problem statement (Description, reproduction steps, affected
version, impact). Post root-cause / investigation findings as a **comment**
(`gh issue comment <N> --repo <org>/<repo> --body-file <file>`), never in the
body — it must stay stable for triage. The issue is a clean conversation, not a
notebook: concluded findings + open questions only, never raw reasoning/status
chatter; interim comments deletable after convergence.

Encourage a Mermaid diagram (e.g. `flowchart TD`) in the body when a visual
aids the reader — GitHub renders Mermaid inline in issue bodies. The diagram is
optional reinforcement, never a substitute for the prose.

Acceptance criteria: a `- [ ]` tasklist, each item phrased so a command can
decide it. An item is done only once its check ran, never from memory; an
impossible criterion is struck with a comment, never dropped. Candidate
solutions belong in comments, not tasklist/body.

Comments follow the same prose rules as the body (free text, no wrapping) and
stay terse: lead with the conclusion, back it with the cited evidence, stop.
One subject per comment — split unrelated findings into separate comments.
Never nest parentheticals; an aside becomes its own sentence. Run command
output through a fenced block instead of narrating it inline.

Observed variant (see `references/example-issue-body.md`): `## Problem` /
`## Acceptance` with no separate References block — same content, fewer
headings; either shape is acceptable. Keep the body stable; post
findings/root-cause as `gh issue comment` and cite concrete evidence (the exact
`- old` → `+ new` diff lines, or command output), not prose summaries. Interim
comments may be deleted after convergence.

The issue template (`## Problem` / `## Acceptance`) is issue-only. The PR body
must not reuse it — the PR side uses the `## What` / `## Why` / `## References`
shape from `sks-pr`.

Body has a **References** section: official material (docs, linked issues/PRs,
commits, changelogs, specs); more may be posted as comments to steer resolution,
but proof of the solution belongs in the PR. Close deliberately — ledger
verified N of N after final merge.

### 3. Triage metadata

Delegate to `sks-issue-triage`: sets each empty, determinable field (type,
labels, assignee, milestone, project); rules live there.

## Pitfalls

- Wrong repo — always use the org repo.
- Rewriting body with findings — findings go in a comment.
- Inventing labels the repo lacks — verify with `gh label list` first.
- English only; don't carry over cpn's French templates.

## Verification

```bash
gh issue view <N> --repo <org>/<repo> --json number,title,labels
```

Confirm title + label set; issue in org repo.

## See also

`sks-discussion`, `sks-pr` (links back via `Related:`), `sks-issue-refine`,
`sks-issue-triage` (run after creation), `sks-doc`.