bugfix

Files (3)

• SKILL.md
• openai.yaml · agents/
• incidental-issues.md · references/

SKILL.md (first lines)

# Bugfix Skill

Read and follow **agent-conduct**, **testing-principles**, and **subagents**
before starting. **subagents** owns delegation: agent choice, briefing, skill
discovery, and error handling. This skill covers only the bugfix procedure.

## Input

One or more bug descriptions. Parse into a numbered list of discrete issues.
Same procedure whether one bug or many.

An issue may come from the user, a failed quality gate, or a verified PR review
finding. Preserve the original description and any source metadata supplied by
the caller, such as a PR thread ID. Source metadata is bookkeeping only; verify
and fix the underlying behaviour in the same way as any other bug.

Interpret reports by intent, not literally. Separate **visual** complaints
("this box is ugly") from **layout** requirements: hiding an element
visually is fine if it still serves sizing/layout. Don't delete structure
that other things depend on.

## Invocation mode

- **Standalone:** Own the checklist and commits. Do not push unless the user
  explicitly asked or **agent-conduct**'s standing rebase authorization applies.
  A dependency publication hold in [routing](references/incidental-issues.md)
  keeps the branch local even under that standing authorization.
- **Batched caller (for example, pr-resolver):** Own the checklist and commits,
  but never push, reply to reviews, resolve threads, or wait on remote events.
  Return control after the local queue is drained. The caller owns one batched
  push and all remote state. Reuse one checklist for the caller's whole active
  session; append later findings instead of starting another bugfix workflow.

If the user reports another bug while this workflow is active, append it to the
current queue and checklist. Finish the current fix-review-commit cycle, then
process the new item before returning to the caller. Do not start a parallel
bugfix workflow or push an incomplete batch.

Before starting, establish the queue owner using
[incidental issue routing](references/incidental-issues.md). Apply it whenever
another issue appears and again at completion. A batched caller's local queue
contains only work routed to its current branch; return deferred items to the
owner without processing them.

Before PR branch workers, apply
[Workspace Boundary](../agent-conduct/SKILL.md#workspace-boundary).

## Discover Quality Gates (once, up front)

Before fixing anything, read `README.md`, `Makefile`/`justfile`/`package.json`
scripts, and any CONTRIBUTING doc to identify the project's lint, test, and
fixture/dev commands (e.g. `make lint`, `make test`, `make dev-fixtures`,
`npm run lint`). Include project performance policy using
[gate policy](../implementation-principles/references/performance-gates.md).
Pass applicable commands and policy to each implementor and reviewer;
subagents must run these gates, not invent their own.
For user-visible changes, include
[user-path verification](../testing-principles/SKILL.md#user-path-verification).

## Checklist File

Reuse a supplied or existing checklist only when its `Branch` metadata matches
the current branch and it belongs to this workflow. An inherited checklist
from another branch is history, not the active ledger. Otherwise create
`.docs/bugfixes/<YYMMDD>-<short-slug>-<id>.md`, with a readable task slug and an
independently generated random ID, such as `uuid.uuid4().hex`. Generate the
name once and retain it on resume. Never choose a next-free number.

Record `Branch`, resolved `Base` ref and SHA, and queue owner branch/checklist
in the header. For a dependent local branch, include the dependency and
publication hold metadata from [routing](references/incidental-issues.md).
Use repository-relative paths in committed metadata and evidence, never
absolute workspace paths. Write each bug verbatim except for secret or
personal-data redactions:

```markdown
- [ ] <bug description, verbatim>
  - Source: <caller metadata, if supplied>
```

Record the red command and before screenshot path under its item. On success,
check the item and add the files touched and approach before committing the
checklist with the fix. Deferred entries carry the branch and committed entry
reference required by [routing](references/incidental-issues.md); they are
handoffs, not successful fixes.

**Before starting a new bug, scan prior `.docs/bugfixes/*.md` checklists.**
Their checked items define behaviour that must not regress. A new fix may
only change a previously-fixed behaviour if that prior item is demonstrably
wrong; if so, note the reasoning in the new checklist entry.

## Evidence hygiene

These rules govern evidence copied into repository files or added to a commit.
They do not restrict terminal or subagent output that stays outside the
repository.

- Before writing evidence, redact credentials, tokens, cookies, personal data,
  private payload fields, and unrelated environment values. Preserve the
  failure's meaning and mark each replacement `[REDACTED]`. Evidence supplied
  by a caller is verbatim after redaction, not before it.
- In the checklist, record the command, its exit status, and the smallest
  output excerpt that proves the failure. Cap the excerpt at 80 lines and 8
  KiB. Do not copy larger logs, traces, response bodies, or payloads into the
  repository.
- Reach visual states with synthetic fixtures. Sanitize any image before
  adding it to the repository.
- Follow the project's evidence policy. With none, commit only the sanitized
  before and after images needed to review a perceptual bug, each no larger
  than 5 MiB. Keep bounded text evidence in the checklist.

## Procedure

Process each bug **sequentially**. Complete fix -> review -> commit before
starting the next, except when a discovered blocker prevents completion.
Pause the affected item, resolve the blocker first, then resume and rerun the
item's checks.

### For each bug:

From wtsi-hgi/agentskills, MIT.

More from wtsi-hgi/agentskills