st

name	st
description	Start task issue-first.
user-invocable	true
allowed-tools	["Bash","Read","Edit","Write"]

st — Start Task (issue-first)

Kick off a new piece of work issue-first: never jump straight into a PR. Every new task gets a tracking issue before any branch or edit. This is the complement to gi — gi grabs an issue that already exists; st is for work you have in mind that isn't tracked yet, so you write the issue first and then flow into the same implement → PR → ARDI tail.

When this fires

• "st", "start a task", "start a new task", "new task", "let's work on X" where X has no open issue yet.
• Any time you're about to start coding something that isn't already covered by an open tracking issue.

Core rule: issue before PR

Before branching or editing, ensure an issue exists:

1. Search the tracker for an existing issue covering the task.
2. Exists → use it — this is just gi on that number.
3. None → file one first, then proceed.

Why issue-first: the issue is the durable record of intent, scope, and "done" criteria. It gives reviewers context, lets the PR auto-close it via Closes #N, prevents duplicate/undiscoverable work, and means there's a tracked home for the task even if the PR stalls.

Procedure

1. Restate the task and "done" criteria

One or two sentences: what's the change, why, and what "done" looks like. If you can't state "done", the issue isn't ready to write yet — clarify scope first.

2. Search for an existing issue

# GitHub — open first, then all states (it may already be filed or closed)
gh issue list --state open --search "<keywords>" --json number,title,url | cat   # SEARCH_ISSUES
gh issue list --state all  --search "<keywords>" --limit 10 \
  --json number,title,state,url | cat   # SEARCH_ISSUES

# GitLab
glab issue list --search "<keywords>" --per-page=20 2>&1 | cat

• Open match → an issue already exists, so this is just gi on that number: invoke the gi skill from its claim step onward (claim → check history → branch → open draft PR → implement → mark ready → ARDI). Skip the rest of st — you don't need to file anything.
• Closed match → surface it ("looks like #N already covered this and was closed") and confirm with the user before re-doing the work.

3. File the issue (if none exists)

# GitHub
gh issue create --title "<concise title>" --body "<what & why>

**Done when:** <acceptance criteria>
<scope notes / out-of-scope>"   # CREATE_ISSUE

# GitLab
glab issue create --title "<concise title>" --description "<what & why>

**Done when:** <acceptance criteria>"

• Keep scope tight — one concern per issue (see split-concerns). If the task is really several concerns, file several issues.
• Capture acceptance criteria so "done" is unambiguous later.
• Label it if the repo uses labels.
• Then claim it (claim-pr pattern) so a parallel session / the @claude bot doesn't collide:

  gh issue comment <N> --body "Claude Code CLI (local session) is working on this — please hold off until I'm done.
  
  _Posted by Claude Code (AI agent) --- not written by a human._"   # COMMENT_ISSUE
  

4. Check history

Invoke check-history before implementing — review merged/closed MRs that touched the same area so you don't undo past progress.

5. Branch → open draft PR → implement → ready → ARDI

From here the tail is identical to gi:

git fetch origin main                       # FETCH
git checkout -b <type>/<slug> origin/main   # CREATE_BRANCH — fix/ feat/ docs/ refactor/

• Open the draft PR now, before implementing — an empty commit gives the branch a diff to open against, kept as a draft so the review bot doesn't run on an empty diff (see pr-on-claim):

  git commit --allow-empty -m "start: <title> (closes #<N>)"   # COMMIT
  git push -u origin <type>/<slug>                              # PUSH
  gh pr create --draft --title "<title>" --body "Closes #<N>
  
  WIP — opened up front to claim the issue; implementing now."   # CREATE_PR
  

• Implement (code, tests, docs), run the repo's standard checks, and push the implementation onto the PR, committing with a message referencing the issue (fix: … (closes #N)).
• Mark the PR ready for review (gh pr ready <N> — MARK_PR_READY) and request the repository owner as reviewer (request-pr-review).
• ARDI the PR to a clean verdict (ardi). Don't merge unless asked.

6. Report

Linked issue + PR, ARDI round count, and any deferred follow-up issues.

Relationship to other skills

• brainstorm — when the task's shape isn't settled yet (multiple reasonable interpretations, a real design tradeoff, "done" can't yet be stated in one sentence), run brainstorm first to resolve that through a Socratic Q&A loop and a plan file, then hand the result to this skill's "restate the task and 'done' criteria" step instead of starting from scratch.
• gi — once the issue exists, the implement → PR → ARDI tail is the same; st is "gi, but you write the issue first."
• defer-issue — same issue-creation mechanics, for sub-tasks that emerge.
• check-history, claim-pr, pr-on-claim, request-pr-review, ardi, split-concerns — invoked along the way (pr-on-claim is the "open the draft PR before implementing" step).
• post-merge — closes the lifecycle that st opens, once the PR lands.

Anti-patterns

• ❌ Opening a PR with no tracking issue behind it.
• ❌ Filing a duplicate without searching open and closed issues first.
• ❌ A vague issue with no "done" criteria.
• ❌ Re-doing already-closed work without flagging it to the user.
• ❌ Cramming multiple independent concerns into one issue/PR.