pair

Files (1)

• SKILL.md

SKILL.md (first lines)

# pair

Pair-program on a ticket. **You drive, the human navigates.**

This skill is the opposite of walk-away. The human is at the keyboard, engaged, steering. You write the code, explain your thinking, surface decisions, and check in frequently. The rhythm is: explore → plan → check in → implement a step → check in → repeat.

The defining design principles are:

> **Driver/navigator dynamic.** You drive (write code, run exploration, propose changes). The human navigates (steers direction, makes judgment calls, approves changes, commits). Neither works alone.
>
> **Derisk first.** Before writing production code, identify what's uncertain and spike on it. Feasibility unknowns resolved early prevent wasted work late.
>
> **Atomic steps with checkpoints.** Each change is small enough to steer in one pass. The human sees the change, gives design feedback, and the session continues. Checkpoints are for steering, not code review.
>
> **PR-early.** Open the PR after the first commit, not when the branch is "done." The PR is a living review surface — each subsequent commit shows up as a reviewable increment in the GitHub UI, which is a better modality for review than CLI chat. The author and teammates can review from the GitHub mobile app between sessions. A PR with one commit signals "work started, visibility for the team"; it doesn't mean "ready to merge." PRs are cheap; delayed visibility is expensive.
>
> **Parallel where possible.** Use subagents for independent exploration and implementation tasks. Don't serialize work that can run concurrently. But always reconvene with the navigator before acting on findings.
>
> **Comment everything back to the ticket.** Assessments, spike findings, plans, and step completions are posted as Linear comments. This means a cancelled session can be picked up later — the ticket carries the full context.

**Commenting protocol.** All Linear comments are posted via the `comment` skill (`Skill("comment", ...)`). This skill describes what to comment; the comment skill handles formatting, provenance, and threading. A session's assessment, plan, step completions and wrap-up are all routine progress: they go as replies into the issue's **current thread** (`T{n}: …`), not as a top-level comment each. Keep the thread IDs the comment skill returns in context and reply to them directly for the rest of the session.

## Commit modes

The skill supports two commit modes. The navigator can switch between them at any time during the session. A typical pattern on non-trivial work: start in checkpoint to refine the design through implementation, then switch to yolo once the remaining work is known and trivial.

- **Checkpoint mode:** The skill presents each atomic change with a drafted commit message (using the `commit` skill's methodology) and pauses for the navigator's steering input — design decisions, dropping constructs, changing approach. The navigator commits when satisfied. The skill never runs git write commands in this mode.
- **Yolo mode:** The skill auto-commits each atomic step using the `commit` skill's methodology for message generation. The navigator can interrupt at any time to steer.

**Commit messages are always drafted via the `/commit` skill.** Invoke it (or apply its methodology) for every commit message — never draft freehand. The `/commit` skill owns the full commit unit: convention lookup, staging checks, atomicity, type/scope selection, amend-vs-new, and message formatting. The modes differ in who *commits* (yolo: auto, checkpoint: navigator), not who *drafts the message*.

**Milestone file commit gate.** A `PostToolUse` hook monitors edits to milestone files (package manifests, lock files, flake.nix, etc.). When you see a `CHECKPOINT:` message from this hook, you **MUST** immediately:
1. Stop implementation work
2. Present the milestone file change to the navigator with a summary of what was added/changed
3. Wait for the navigator to commit (checkpoint mode) or auto-commit immediately (yolo mode)
4. Only then proceed to the next implementation step

This prevents atomic steps (like adding a dependency) from being tangled with subsequent implementation changes in the same uncommitted working tree. The hook fires on: package.json, package-lock.json, pnpm-lock.yaml, yarn.lock, Cargo.toml, Cargo.lock, flake.nix, flake.lock, pyproject.toml, poetry.lock, uv.lock, go.mod, go.sum, Gemfile, Gemfile.lock, mix.exs, mix.lock, and *.cabal files.

**Signed vs unsigned commits.** Default to `git commit` / `git push` — these produce signed, verified commits via the user's SSH key and 1Password. Fall back to `git mcommit` / `git mpush` (unsigned, HTTPS-based) only when:

- The navigator has explicitly said they're leaving the computer ("I'm stepping away", "walk-away mode", "keep going while I'm out"), OR
- The navigator has urged the agent to plow through something and signing fails (missed Touch ID prompt)

If a session has used `mcommit`/`mpush`, the PR contains unsigned commits — which is the intended signal for AI-produced work. **The merge gate is harder for unsigned PRs:** do not merge without explicit human approval, because the entire commit chain lacked interactive verification. The merge is where the human-in-the-loop catches up.

**System-scope commands are always HITL, even in yolo mode.** Commands that modify system state (`brew install`, `npm install -g`, `pip install`, `cargo install`, etc.) are never auto-approved. When a tool is missing, surface it to the navigator with context (e.g. "gitleaks is required by the pre-commit hook — install via `nix develop` or approve `brew install gitleaks`?") rather than resolving it silently. Imperative installs bypass version control and can't be reviewed or rolled back.

At the start of the session, if the skill detects this is a fresh ticket with no prior work, ask:

> "Checkpoint or yolo? (You can switch anytime.)"

Default to **checkpoint** for non-trivial work (multiple steps, unknowns). Default to **yolo** for simple/mechanical work (adding a package, small config change). If prior work exists on the branch, default to checkpoint without asking (the navigator is resuming deliberate work).

**Important:** In both modes, code review happens via PR on GitHub — not in the CLI chat. Checkpoints are for design steering, not line-by-line code review. When the navigator wants to review code, offer to prep a PR: "Shall I ship a PR so you can review on GitHub?"

## Check-in shape

Every chat-facing check-in ends with a **closing block**: the detail comes first, the conclusion and the ask come last, fused into one unit at the very bottom of the message.

**Why the conclusion closes rather than leads.** Returning to a chat, the operator lands at the *bottom* of the exchange. The top is off-screen, and finding it costs a scroll plus a visual scan; the last paragraph is spotted for free. This is the deliberate inverse of `/troubleshoot`, which opens with its TL;DR — do not "correct" it into alignment with that skill.

**Order within the block: TL;DR, then the ask.** An ask is only actionable once the state it arises from is known, so reading order matches reasoning order — and the final thing on screen is still the item requiring the navigator's action.

The TL;DR has **no fixed field list** (again unlike `/troubleshoot`). A handful of lines carrying facts, not topic labels: what was found, what changed, what state the work is in. "Assessment complete, plan drafted" is a label; "Gate passes, ticket's premise about an existing rule is wrong, nothing committed" is a fact.

**The block carries its own navigation.** Always state, as clickable links rather than bare identifiers:

- the **ticket** — identifier linked to its Linear URL
- the **PR** — number linked to its GitHub URL
- the **branch**, when it isn't otherwise obvious

The navigator should never have to fall back on the harness status bar, which is neither always visible nor always current. You always know the ticket and the PR, so always state them. **State absence explicitly** — write `no PR yet`, never omit the field, because a missing PR link is ambiguous between *there is none* and *it was forgotten*.

The shape:

```
[ findings, tables, detail — as long as it needs to be ]

---

**TL;DR** — Readiness gate passes. Two unknowns spiked out, one blocker left:
the ticket's token-expiry requirement is underspecified. Nothing committed.

[Z-123](https://linear.app/acme/issue/Z-123/add-oauth2-support) · no PR yet · `vidbina/z-123-add-oauth2-google-login`

**Ask:** silent refresh, explicit re-login, or both with fallback?
```

When there is genuinely nothing to ask — a progress note mid-step, a step completion in yolo mode — the block is just the TL;DR and its navigation. Don't manufacture a question to fill the slot.

This applies at every check-in that reports back to the navigator, and specifically at the three that carry the most: the Phase 1 assessment, spike findings, and the Phase 4 wrap-up.

## Phase 0 — Pick up the ticket

### Identify the work

Determine what ticket to work on, in this order:

1. **Explicit argument** — if the user passed a ticket ID (`LIN-123`, `Z-123`) or branch name, use that.
2. **Current branch** — run `git branch --show-current`. If the branch name contains a ticket identifier (e.g., `vidbina/z-123-some-description`), extract it.
3. **Ask** — if neither yields a ticket, ask the user what to work on.

### Check out the branch

If the ticket has a git branch name (from the Linear issue's `branchName` field or inferred from the ticket ID), and that branch is not currently checked out:

- Run `git fetch` to ensure the branch is available locally.
- Run `git checkout {branch}` to switch to it.
- If the branch doesn't exist yet, determine the correct base before asking:
  - If the ticket is a sub-issue, check whether the parent ticket has a branch. If it does, that branch is the base — branching from `main` would break the stack's mergeability.
  - If the ticket is top-level, default to `main` — but check whether there is an in-progress stack (e.g. a series of open PRs targeting each other) that this work should continue. If a stack exists, ask the navigator whether to extend it or start fresh from `main`.
  - Ask: "No branch for this ticket yet. Create `{suggested-branch-name}` from `{base}`?" naming the resolved base explicitly. On approval, create and check out.

If the user passed a branch name directly rather than a ticket ID, check it out if not already on it.

### Load context (parallel)

Once the ticket ID is known and the branch is checked out, fetch all of these in parallel:

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb