Working On An Issue

Working on an Issue

Announce at start: "I'm using the working-on-an-issue skill to implement this GitHub issue."

Overview

A hands-off workflow for implementing GitHub issues. There are no approval gates before the pull request: the developer reviews finished work on the PR, so every judgment call you make must be recorded where they will see it.

Core principle: Understand → Recon → Plan verification → Plan implementation → Implement → Verify → PR

Create TodoWrite todos for the pre-flight checklist and each numbered step below.

When to Use

• Developer asks to work on or implement a GitHub issue
• Developer provides an issue URL or number

When NOT to Use

• Issue is epic-sized or bundles multiple independent changes → run issue-decomposition first
• Issue is too vague to restate as testable acceptance criteria → run requirement-elicitation, or comment on the issue with your questions, and stop
• Triaging or labeling incoming issues → triage-new-issues

Pre-flight Checklist

• [ ] Issue URL or number obtained
• [ ] Repository cloned; work branch created: issue--
• [ ] CLAUDE.md exists (or run setting-up-a-project first)

The Process

1. Read the Whole Issue

Get the issue and its comments: gh issue view --comments (or GitHub MCP tools, or ask for pasted content). Comments often supersede the body — the latest clarification wins. Check for linked or duplicate PRs already addressing it.

Sizing check: restate the issue as 1–5 testable acceptance criteria. If you can't, take the off-ramp in When NOT to Use instead of proceeding.

Do not invent requirements. Where the issue is ambiguous, choose the narrowest interpretation that satisfies the text and record it as an assumption — assumptions go in the plan file and the PR description, never unstated.

**Assumptions resolve ambiguity in how, never reduce what the issue asks for.** Dropping a named request ("deferred the tour") is not an assumption — it's a scope cut, and scope cuts go through issue-decomposition, not the assumptions list. Manufacturing acceptance criteria the issue never stated to pass the sizing check is the same violation.

2. Scoped Reconnaissance

The issue bounds the exploration. Recon exists to locate the change, not to understand the codebase.

Stop exploring the moment you can answer all three:

1. Which files will change?
2. Which existing pattern or convention will the change follow?
3. Which tests cover this area?

Budget: start from files, symbols, and error messages the issue names; expand at most one hop (direct callers/callees and their tests). Check callers only to confirm the fix won't break them, then stop — "who uses this everywhere and how" is an architecture survey, not recon. If roughly 10 targeted searches haven't produced the file list, more exploration will not fix it — the issue is underspecified; take the off-ramp.

Forbidden: reading whole directories "for context", tracing beyond one hop, architecture surveys.

3. Write the Verification Plan

Use the writing-verification-plans skill. This comes before the implementation plan because acceptance criteria define done and constrain the implementation.

4. Write the Implementation Plan

Use superpowers:writing-plans (if available) or write a brief plan covering: what changes, which files, order of implementation, risks, and the assumptions from step 1. Save to docs/plans/issue--plan.md, then proceed — do not wait for approval.

5. Implement

• Follow TDD practices if TDD.rules.md is present (a project-level TDD rules file, if the repo defines one)
• Commit after each logical change; reference the issue in commit messages (e.g. fix: handle empty input (#123))
• Unexpected complexity that invalidates the plan → update the plan file and note it for the PR description
• Genuinely blocked (missing credentials, contradictory requirements) → comment on the issue and stop

6. Execute Verification

Run the verification plan and record results in the log format from writing-verification-plans.

If verification fails: use superpowers:systematic-debugging to find the root cause — do not patch symptoms — then fix, re-run, and update the log. Never open the PR with failing verification (superpowers:verification-before-completion applies).

7. Open the Pull Request

Push the branch and create the PR: gh pr create. The PR body must include:

• Fixes # so merging closes the issue — only if every named request in the issue is addressed; if anything was split out or deferred, use Refs # and say what remains open
• Summary of the change
• Assumptions made (from the plan)
• Verification log results

The PR is the approval gate. Everything a reviewer needs to judge the work goes in it.

Absolute Rules

• No scope creep: Only implement what's specified
• Assumptions documented, never silent: Narrowest reasonable interpretation, recorded in plan and PR
• Verification before PR: The task is incomplete until verification passes
• Blocked = comment and stop: Comment on the issue and stop — do not guess through contradictions

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: britt
• Source: britt/agent-skills
• License: MIT
• Homepage: https://britt.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.