st

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 → cut a worktree and 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>" \
  --label ai-authored --label "model:<model-id>" --label P2   # CREATE_ISSUE

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

**Done when:** <acceptance criteria>" \
  --label "ai-authored,model:<model-id>,P2"

• 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.
• The labels above are not optional: every issue an agent files into a repo we administrate carries ai-authored, model:<model-id> and one of P1, P2 or P3 (P2 is the default), per issue-first. Normalize the model id and create the labels where they are missing, per label-agent-filed-issues.
• Add any further labels the repo's own taxonomy calls for.
• 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
  

3a. If the task builds on an existing issue or PR

When the task naturally builds on an open issue or PR (it needs that work's code, or edits the same passages), link the two before branching, per issue-first:

1. File the new issue as usual.
2. Mark it blocked by the existing issue (or the existing PR) in GitHub's issue relationships field: gh issue edit <new> --add-blocked-by <existing number or URL> (the REST fallback for older gh is in issue-first).
3. Then either wait for the lower-level issue or PR to finish, or, if feasible, stack a new PR on it with stack-prs. Run stack-prs's decision gate first; step 5's branch from main applies only when the work is independent of every open PR.

4. Check history and research DRW

• Invoke check-history before implementing --- review merged/closed MRs that touched the same area so you don't undo past progress.
• Perform a research step to check whether the functionality or helper already exists (Don't Reinvent the Wheel / DRW): search our own repos (Morrison-Lab/gha, lab packages, ai-config) and trustworthy upstream ecosystems (standard libraries, r-lib / tidyverse, PyPI, npm) via prefer-upstream and dont-reinvent-wheel before hand-rolling custom code.
• Choose explicitly whether to centralize or distribute the content or other work, both within the repo and across repos, and state the choice in the issue or PR, per centralize-or-distribute. Ezra, 2026-11-09: "when planning and/or performing work, we should choose explicitly whether to centralize vs distribute content or other work, both within and across repos" (ai-config#5185).

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
  

  Push as a separate Bash call, per check-before-pushing's "Keep the commit in its own Bash call":

  git push -u origin <type>/<slug>   # PUSH
  

  Open the draft PR in a separate Bash call:

  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), researching existing libraries/functions before hand-rolling custom code, 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.
• stack-prs --- step 3a hands off to it when the task builds on an open PR; it supplies the decision gate and the branch mechanics.
• gi — once the issue exists, the implement → PR → ARDI tail is the same; st is "gi, but you write the issue first."
• prefer-upstream --- search existing packages and tools before writing custom code to prevent reinventing the wheel.
• 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.
• ❌ Hand-rolling custom code without researching existing libraries/packages first (violating DRW).
• ❌ Cramming multiple independent concerns into one issue/PR.