Address Issue

---
name: address-issue
description: Use when the user asks to address or implement an issue.
---

# Address issue

Implement a provided issue in the harness- or user-supplied workspace and Git
context. Core loop: plan → atomic TODOs → one commit per TODO → PR (or
comment+close when no code change).

## Project status

When changing issue status, reuse an attached GitHub Project. Otherwise use a
relevant project for the repository and add the issue to it. If neither exists,
skip status tracking.

## Workflow

### 1. Identify the issue and repo state

- Parse the issue number or URL; ask only if ambiguous.
- Harness-supplied repo root, worktree, branch, and base are authoritative;
  change them only on explicit user request. Do not relocate the task to dodge a
  dirty tree.
- From that root:

```bash
git rev-parse --show-toplevel
git status --short
gh issue view <issue-number> --json number,title,body,labels,state
```

If the issue is closed, stop unless the user asked to reopen or work closed
issues. If uncommitted changes exist outside `.plans/`, ask how to handle them
before mixing work.

Once the issue is open and the workspace is ready, move it to **In Progress**
before planning or implementation.

### 2. Read, understand, and draft the plan

Read the issue body and relevant code first. Search for existing patterns, tests,
and conventions.

If no code change is warranted (question, duplicate, already fixed,
works-as-intended): post findings as an issue comment, close with
`gh issue close <n> --reason "not planned"` or `completed`, and stop. No branch,
no PR.

When plans are part of the repo's conventions, create/update
`.plans/<number>-<slug>.md`:

```markdown
# #<number> <issue title>

## Summary
<What the issue asks for in your own words.>

## Acceptance criteria
- [ ] <Observable outcome from the issue>

## TODOs
- [ ] <Small concrete implementation step>
- [ ] <Small concrete test/validation step>

## Notes
- Decisions, discoveries, and commands run.
```

TODO rules: each independently committable; include tests/validation as TODOs;
prefer 3–8; split vague ones before coding; unclear requirements → Notes + ask
before coding.

Commit the initial plan only when that is normal for the repo. If `.plans/` is
ignored or local-only, keep it updated without committing.

### 3. Execute one TODO at a time

For each TODO:

1. Mark in progress (`- [~]`) or note it under Notes.
2. Smallest change that completes it.
3. Focused validation for that TODO.
4. Mark complete (`- [x]`), record validation, revise TODOs on discovery.
5. Commit before the next TODO:

```bash
git status --short
git diff
git add <paths>
git commit -m "<type>(<scope>): <complete this TODO>" -m "Implements TODO: <exact TODO text>." -m "Refs #<issue-number>"
```

One completed TODO per commit (or per split item). Keep commits buildable.
`Refs #<n>` on intermediate commits; `Closes #<n>` only on the final
implementation commit or PR body when the issue is fully resolved.

### 4. Final validation

After all TODOs:

```bash
git status --short
# Project scripts, e.g. pnpm test / lint / check
```

On failure: diagnose, fix, or record residual risk before filing the PR.

### 5. Capture UI evidence

If the PR touches UI, capture the affected UI or behaviour on the base revision
and the PR revision. Use comparable viewport sizes, data, and interaction steps.
Include labelled before-and-after screenshots for appearance changes, and video
or GIFs when motion or interaction is needed to show the behaviour. For new UI,
show the previous entry point or workflow as the before state.

Inspect the media, then attach or embed it in the PR so reviewers can see the
change. Follow the repo's browser rules. If capture is blocked, report the exact
blocker and leave this step incomplete; test results do not replace UI evidence.

### 6. Push and file the PR

Push the current harness-provided branch (no rename/replace). Then follow
[pr-file](../pr-file/SKILL.md) for rebase, title, push mechanics, and creation;
repo templates and CONTRIBUTING win over defaults.

Issue-specific body deltas on top of pr-file:

- Keyword deliberately: `Closes #n` only when this PR fully resolves the issue;
  otherwise `Refs #n` plus one line on scope covered and what remains.
  `pr-merge` closes every directly referenced open issue.
- Acceptance criteria from the plan/issue: all checked, or defer under a
  `Refs` issue with the deferral noted.
- Tests: commands actually run, with real results.

### 7. Mark the issue ready for review

After the PR is filed and all validation is complete, move the issue to
**Ready**. This is the final action before reporting the PR URL, branch,
completed TODOs, and validation.

## Rules

- Workspace / worktree / branch / base belong to the harness or explicit user
  instruction.
- The plan file is source of truth while working; keep it current.
- File the PR only when every TODO is complete or explicitly deferred with a
  reason.
- Prefer existing repo conventions over this skill's defaults.