baseref=$(git rev-parse --verify --quiet "origin/$base" || git rev-parse --verify --quiet "$base")

bash "<skill-dir>/scripts/check-env.sh"
bash "<skill-dir>/scripts/detect-base.sh"
bash "<skill-dir>/scripts/repo-context.sh"
bash "<skill-dir>/scripts/repo-ownership.sh" [<owner>/<repo>]
bash "<skill-dir>/scripts/pr-reviewers.sh" [<owner>/<repo>] [<limit>]
bash "<skill-dir>/scripts/issue-assignees.sh" [<owner>/<repo>] [<limit>]
bash "<skill-dir>/scripts/add-to-project.sh" <issue-number> <project-title> [status]
bash "<skill-dir>/scripts/get-issue-projects.sh" <issue-number>
bash "<skill-dir>/scripts/suggest-projects.sh" [<owner>/<repo>]
bash "<skill-dir>/scripts/project-status.sh" <issue-number> <status>

undefined

Use the current branch name to determine which steps are already done:
- On `issue-<N>` branch → Steps 1-2 are done, detect entry from there
- On base branch (main/master/etc.) with no changes → nothing to do
- On base branch with changes → full flow from Step 1

Determine entry step from user intent, check prerequisites, then proceed forward. Do NOT re-run earlier completed steps.

| User intent                          | Entry step | Prerequisite             |
| ------------------------------------ | ---------- | ------------------------ |
| "what's next", "pick an issue", "which issue" | Step 0 | gh authenticated       |
| Work intent with no issue number given | Step 0  | gh authenticated         |
| No arguments / empty invocation      | Step 1     | Staged or changed files  |
| "create issue", "new issue"          | Step 1     | gh authenticated         |
| "create issue linked to #N", "create sub-issue of #N" | Step 1 + Project Inheritance | Parent #N exists |
| "add sub-issues to #N", "link issues to #N" | Sub-issues | Parent issue exists |
| "X blocks #N", "block #N with #M", "unblock #N" | Blocked-by | Both issues exist |
| "start work on #N", "branch for #N"  | Step 2     | Issue exists             |
| "commit", "commit changes"           | Step 3     | On issue-* branch        |
| "snapshot", "wip snapshot"           | Step 3 snapshot | Dirty tree        |
| "push", "push changes"               | Step 4     | Commits ahead of remote  |
| "create PR", "open PR"               | Step 5     | Branch pushed            |
| "merge", "merge PR"                  | Step 6     | PR exists                |

gh api user --jq .login

bash "<skill-dir>/scripts/repo-ownership.sh"

bash "<skill-dir>/scripts/check-env.sh"
gh repo view --json nameWithOwner --jq '.nameWithOwner'
gh api user --jq .login

undefined

Wait for all four before proceeding. `detect-base.sh` is not needed until Step 2.

bash "<skill-dir>/scripts/issue-assignees.sh"

gh api "repos/<owner>/<repo>/issue-types" --jq '.[].name' 2>/dev/null || true

bash "<skill-dir>/scripts/suggest-projects.sh"

gh api "repos/<owner>/<repo>/milestones?state=open" --jq '.[] | {number, title, state, open_issues, closed_issues, due_on}'

Which milestone for this issue?
1. "<title1>" (Recommended) — X open / Y closed, due YYYY-MM-DD
2. "<title2>" — X open / Y closed, due YYYY-MM-DD
3. No milestone

gh issue create --title "<title>" --body-file <TMPDIR>/body.md --label "<label>" --assignee "<assignee>" [--milestone "<name>"]

PARENT=<parent_number>
for num in <child1> <child2> <child3>; do
  id=$(gh api repos/<owner>/<repo>/issues/$num --jq '.id')
  gh api repos/<owner>/<repo>/issues/$PARENT/sub_issues \
    --method POST \
    -F sub_issue_id="$id"
done

gh api repos/<owner>/<repo>/issues/<parent_number>/sub_issues --jq '.[].number'

bash "<skill-dir>/scripts/get-issue-projects.sh" <parent_number>

gh api graphql -f query='{
  repository(owner: "<owner>", name: "<repo>") {
    a: issue(number: <blocking-num>) { id }
    b: issue(number: <blocked-num>) { id }
  }
}'

gh api graphql -f query='mutation {
  addBlockedBy(input: {
    issueId: "<node-id-of-b>",
    blockingIssueId: "<node-id-of-a>"
  }) { issue { number } blockingIssue { number } }
}'

| Issue | Title                   | Milestone   |
| ----- | ----------------------- | ----------- |
| [#10023](https://github.com/owner/repo/issues/10023) | AnchorDialog for Editor | Alpha (MVP) |
| [#10024](https://github.com/owner/repo/issues/10024) | Toolbar refactor        | Alpha (MVP) |

git checkout -b issue-<number>

git checkout <base> && git pull origin <base>
git checkout -b issue-<number>

bash "<skill-dir>/scripts/project-status.sh" <number> "In Progress"

baseref=$(git rev-parse --verify --quiet "origin/$base" || git rev-parse --verify --quiet "$base")
git merge-base "$baseref" HEAD

base=$(bash "<skill-dir>/scripts/detect-base.sh" 2>/dev/null | tail -n1) || base=""
[ -n "$base" ] || { echo "No base branch — add a remote first."; exit 1; }
baseref=$(git rev-parse --verify --quiet "origin/$base" || git rev-parse --verify --quiet "$base")
fork=$(git merge-base "$baseref" HEAD)
git log "$fork"..HEAD --oneline

git diff --cached --name-only
git restore --staged <path>      # per file that does not belong in the commit

git add <files>
git commit -m "<subject>" -m "<body>"

git status --short          # confirm nothing scratch is about to be staged
git add -A && git commit -m "wip: snapshot"

git push -u origin issue-<number>

before=$(git rev-parse "origin/issue-<number>" 2>/dev/null || true)
git fetch origin <base>
git rebase origin/<base>
if [ -n "$before" ]; then
  git push --force-with-lease="issue-<number>:$before"
else
  git push -u origin issue-<number>
fi

before=$(git rev-parse "origin/issue-<number>" 2>/dev/null || true)
git commit --amend -m "<subject>" -m "<body>"
if [ -n "$before" ]; then
  git push --force-with-lease="issue-<number>:$before"
else
  git push -u origin issue-<number>
fi

before=$(git rev-parse "origin/issue-<number>" 2>/dev/null || true)

`rev-parse` is guarded because the branch may not be on the remote yet, and a bare
`git rev-parse origin/issue-<number>` exits 128 with `unknown revision` — which under
`set -e` aborts the step instead of pushing. An empty `$before` means there is nothing to
lease against, so that case is a plain `git push -u origin issue-<number>`.

A bare `git push --force-with-lease` leases against `refs/remotes/origin/issue-<number>`.
Any fetch that refreshes that ref makes the lease describe where the remote is *now*
rather than where it was when you started — at which point it permits exactly the
overwrite it exists to prevent. `detect-base.sh` runs a bare `git fetch origin`, which
refreshes every branch, inside Step 3 → Consolidate; and nothing stops an unrelated fetch
landing between the rewrite and the push. Reading the SHA before any of that is what makes
the lease mean anything.

`--force-if-includes` (git 2.30+) is not a substitute here. `git help push` is explicit
that when it is combined with `--force-with-lease=<refname>:<expect>` it is a **no-op** —
so alongside the pinned form above it does literally nothing. It is the right tool for the
*valueless* `--force-with-lease`, since it consults the local reflog rather than the
remote-tracking ref; but it needs git 2.30+, it fails oddly after a `gc` or in a fresh
clone where the reflog is thin, and it would diverge from the pinned idiom used
everywhere else in this file. Pin the SHA instead.

If the push is rejected, the remote moved: fetch, rebase onto the new tip, and re-run
rather than escalating to `--force`.

Print the Step 4 report.

before=$(git rev-parse "origin/issue-<number>")

This must happen before PR body generation, since consolidating changes the commit log.

undefined

undefined

bash "<skill-dir>/scripts/pr-reviewers.sh"

gh api user --jq .login

gh pr create --title "<title>" --body-file <TMPDIR>/pr-body.md --base <base> --assignee @me --assignee <reviewer> --reviewer <reviewer>

gh pr create --title "<title>" --body-file <TMPDIR>/pr-body.md --base <base> --assignee @me

bash "<skill-dir>/scripts/project-status.sh" <number> "Review"

for i in 1 2 3; do
  state=$(gh pr view <pr-number> --json mergeable,mergeStateStatus --jq '.mergeable + " " + .mergeStateStatus')
  case "$state" in UNKNOWN*) sleep 3 ;; *) break ;; esac
done
echo "$state"

PR #<number> is ready for review by @<reviewer> (mergeable: <state from Step 5>). Merge skipped — awaiting external review.

gh pr view <pr-number> --json state,mergeable

gh pr checks <pr-number> --watch --fail-fast

gh pr view <pr-number> --json mergeable --jq '.mergeable'

gh pr merge --rebase --delete-branch

undefined

Update project status to "Done":

```bash
bash "<skill-dir>/scripts/project-status.sh" <number> "Done"