jackleh/claude-skills

Start Work Item

Turns a pasted ADO ticket into: a fresh (or correctly resumed) branch, a context memory that later sessions can resume from, grounded codebase discovery, and either a root cause analysis or a feature layout. It ends at a checkpoint — present findings and wait. No fix or feature code is written in this skill; the user approves the direction first, because a wrong RCA that ships quickly costs a full QA round trip.

0. Load the local config

Read config.local.md in this skill's folder first — before parsing the ticket. It holds the nouns this skill deliberately doesn't hard-code: branch prefix, base branch, the project's layering doc, where investigations live, code-index blind spots, and past memories worth pointing at. Discovery quality depends on those specifics, so don't skip it.

If it's missing (fresh install), infer what you can — base branch from git remote show origin (HEAD branch), prefix from the user's existing branches (git branch --list "*/*") — tell the user what you inferred, and offer to save it as config.local.md (see config.example.md).

The memory dir is the one your system prompt names for this project; the repo is the one you're working in. Neither needs config.

1. Parse the ticket

Extract, from whatever was pasted. ADO's page copy-paste is noisy: the first line is the type and ID in caps (USER STORY 12345, BUG 12346), each field label sits on its own line with the value on the next (State / Dev In Progress), tags appear as bare lines near the top, and there's UI chrome to ignore (Save, Follow, Click to add …, switch to HTML editor, empty TestRail sections). Images and attachments don't survive the paste.

• ID (number) and Work Item Type — Bug vs. User Story / Feature / PBI / Task. If the type is not stated, infer it (repro steps + expected/actual ⇒ bug; "As a … I want" or acceptance criteria ⇒ feature) and say what you inferred.
• Title, State, Area/Iteration if present
• Bug: repro steps, expected vs. actual, build number, platform/device/OS, deep links, attached log names, screenshots mentioned
• Feature: description, acceptance criteria, linked designs, feature flag / experiment names
• Discussion/comments: earlier attempts, QA notes and their dates, PR numbers

If there is no ID, ask for it before creating anything — the ID drives the branch and memory names. Note anything referenced but not visible (screenshots, logs) so you can ask for it at the checkpoint rather than guessing at its contents.

2. Branch

Run git in the repo you're working in (if the session is in a worktree or another clone, use that — never cd away from it):

git status --porcelain

If the tree is dirty, stop. List the files and the current branch, and ask how to proceed (carry over, stash, or commit on the old branch). Uncommitted files from one item leak into the next one's commits; the user decides this, not you.

When clean:

git fetch origin
git branch --list "<prefix>/<id>*"; git branch -r --list "origin/<prefix>/<id>*"

If no branch exists for the ID, cut <prefix>/<id> from origin/<base> and record the short SHA (git rev-parse --short HEAD).

If <prefix>/<id> or <prefix>/<id>-N already exists (local or remote), look at the newest one before deciding — the same ID can arrive at three very different moments:

git log --oneline origin/<base>..<prefix>/<id>[-N]   # unmerged commits?
git log --oneline origin/<base> --grep=<id>           # "Merged PR NNNN: ... <id>" = it landed

ADO squash-merges, so a merged branch still shows its commits as "ahead" of the base — the Merged PR line on the base branch is what tells you it landed. Read it together with the ticket's State and the date of the newest QA comment versus the branch's last commit.

Newest existing branch	Typical ticket state	What to do
No commits beyond origin/<base> (often the branch you're on — the user cut it before pasting)	New / Dev In Progress	Reuse it. Check it out, git merge --ff-only origin/<base>.
Merged (a Merged PR for this ID on the base) and QA has failed it since	Active / reopened, failed-QA comment newer than the merge	Cut the next suffix (-1, -2, …) from origin/<base>; the previous attempt becomes prime discovery material.
Unmerged commits (pushed or not), or a PR still open	PR Review / Ready for Test / In Progress	In flight — don't branch. Report what's on it (commits, whether it's pushed, how far behind the base it is), make it the subject of discovery, and ask whether to resume or start a fresh attempt.

If the signals disagree (e.g. state says New but there's an unmerged branch), treat it as in flight and ask — cutting a duplicate branch is the expensive mistake. If git fetch fails (VPN / auth), say so and use the local origin/<base>, noting the base may be stale.

Don't push and don't commit — the user hasn't asked.

3. Context memory (write it now, update it later)

Write the memory before discovery, with status ⏳, so the item is resumable even if the session dies mid-investigation. Use references/memory-template.md.

• Bug → bug-<id>-context.md, feature/story/task → feature-<id>-context.md
• If one already exists for this ID, update it instead of creating a second one — and correct anything in it the git state now contradicts.
• Add a one-line pointer to MEMORY.md. Without it, later sessions never find the memory.

4. Codebase discovery

The goal is to find the actual code paths the ticket touches and the history around them — enough that the RCA/layout cites file:line, not guesses.

• Use the code index if there is one (CodeGraph, LSP): start with a context query on the ticket's nouns (page, control, service, DTO), then one explore call on what it surfaces; callers/impact on the suspect symbol. Check config for the index's blind spots (file types it doesn't parse) and grep those instead.
• Routes and UI names: page routes, component names, CSS classes and deep-link schemes from the ticket are good grep terms.
• Prior work: git log --oneline --all --grep=<id>, git log --oneline -20 -- <suspect files>, the project's docs/investigations folder (config), and the memory dir for write-ups on the same area. An earlier fix for the same symptom that failed QA is the most valuable thing you can find.
• Compare the passing and failing cases. When QA lists cases that pass and one that fails, find what actually differs between them in code — the host page, the data path, the timing — before settling on a mechanism.
• Every head/platform: if the UI is shared across hosts (mobile shell, web), check whether the ticket is platform-specific and whether the code is.
• Don't build during discovery. Reading code is enough here; builds are slow and belong to implementation.

For broad sweeps across many folders, an Explore subagent is fine; for a known area, do it directly.

5a. Bug → root cause analysis

Use the superpowers:systematic-debugging skill for the method if it's available. The bar is measured, not guessed: name the mechanism and the exact file:line, and explain why it produces precisely the reported symptom and not some other one (why the failing case fails and the passing ones pass).

• Trace the path from the user action in the repro steps to the faulty state. Quote the relevant lines.
• Reproduce where feasible without a device: component tests for state/markup, a headless-browser static replica for layout/scroll/CSS issues (config may point at a memory describing an existing harness). If you can't reproduce, say so plainly, state your confidence, and what evidence would confirm it (e.g. a specific log line or screenshot from QA).
• Separate the root cause from contributing factors and from adjacent problems that belong in other tickets.
• Propose a fix direction (or 2–3 options with a recommendation) and the regression test that would pin it — but don't write them yet.
• In-flight item (step 2): the RCA becomes a review of the fix already on the branch — does it address the newest QA failure, and what residual risks would make it fail on the device? Recommend resuming it, and say what QA result would justify a fresh attempt.

5b. Feature → layout and elaboration

Use the superpowers:brainstorming skill for the design conversation if it's available.

First judge whether the acceptance criteria are sufficient. They are sufficient when:

• every AC can be turned into a concrete test assertion and mapped to a file to touch, and
• UI states (loading, empty, error, disabled), per-platform behavior, analytics events, and feature flagging are either specified or clearly not applicable.

If they're sufficient, don't ask questions for the sake of it — lay out the feature. If they're not, elaboration is required: ask only about the gaps, batched in one AskUserQuestion (up to 4 questions, concrete options, a recommended default first). Vague ACs that get guessed at produce rework.

Sort each gap before asking: if the answer would change the design (what's shown, where data comes from, what the user sees on tap), it's a question. If it's something with an obvious house convention — a feature flag key, an analytics event name, a DI registration — pick the conventional value, write it in the layout as Assumed: so the user can correct it at a glance, and don't ask. The 4-question batch is the whole ask; no "also, please confirm…" tail after it, because that's just more questions without options.

The layout covers:

• Files to add/modify, placed per the project's layering (config points at the doc that defines it), including DI registration in each host
• Data flow: where the data comes from, which service owns state, how it reaches the component
• AC → test mapping, naming the test project for each
• Platform differences, analytics/flags, risks and open questions

6. Checkpoint

Update the memory file with what you found (status 🔄, root cause or layout summary, open questions), then present to the user:

Bug:

## Bug <id>: <title>
Branch: <prefix>/<id> (from origin/<base> @ <sha>)   — or: in flight on <branch>, no new branch
Memory: bug-<id>-context.md

### Root cause
<mechanism, file:line, why it matches the symptom> — Confidence: <high/medium/low + what would raise it>

### Evidence
<code quotes, repro results, history: earlier PRs/attempts>

### Proposed fix
<direction or options + recommendation; regression test to add; files to touch>

### Need from you
<missing screenshots/logs, decisions>

Feature:

## Feature <id>: <title>
Branch / Memory: ...

### What the ACs say vs. what's missing
### Proposed layout (files, data flow, AC → tests, every platform, Assumed: …)
### Questions  (or "None — ACs are sufficient")

Then stop and wait for approval. If the RCA or layout spans 5+ files or changes architecture, offer to write it up in the project's docs/investigations folder (config) — offer, don't auto-create.