By Ashley Kays. Worked examples use fictional inputs; expected results are illustrations for testing, not performance claims.
A useful development skill preserves the engineering steps that disappear when a task feels urgent: reproduce the issue, understand the affected code, make a small change and verify the behavior. Its value comes from making the evidence visible.
What you will build
A scoped fix proposal or patch, a verification record and a clear account of what remains untested.
Gather the inputs
Bug report; expected and actual behavior; reproduction steps; repository instructions; relevant environment; available test commands; permission to edit code when needed.
1. Capture the failure
Write the smallest reproducible case. If reproduction is blocked, record the blocker and use the available evidence without pretending the bug was reproduced.
2. Inspect the project
Read repository guidance and the affected implementation. Identify constraints and existing tests before changing code.
3. Make a scoped change
Edit the smallest coherent set of files. Avoid unrelated refactoring or new dependencies unless the fix requires them.
4. Verify behavior
Run the relevant checks when available. For each, record command, result and limitation. Distinguish an intended check from an executed one.
5. Prepare the handoff
Explain the trigger, resulting behavior, validation and remaining risk. Require separate authorization for deployment or destructive operations.
A worked example
Fictional bug: saving a profile with a blank optional display name throws an error. Expected behavior: accept an empty optional field. Existing validation and test commands must be read from the actual repository.
Expected handoff: identify the null or empty-string handling defect; make the smallest validation change; verify empty, populated and invalid inputs using the repository test setup. This is an example of the required evidence, not a claim that a patch or tests were run.
Copyable skill instructions
Use this focused template in the skill-creation flow described in the starter guide. Review and adapt it to your own work before saving. It is not installed by downloading this article.
---
name: scoped-bug-fix
description: >-
Investigate a reproducible bug and prepare a scoped fix with verification evidence.
Use for bug work, not unrequested refactors or deployment.
---
# Bug report to checked change
Read repository instructions first. Confirm expected and actual behavior. Reproduce when possible and record blockers. Inspect related code and tests. Implement only within the authorized scope. Run relevant existing checks and add a regression test when it meaningfully protects the fix. Report exact checks, results and untested paths. Never say a check passed unless it ran successfully. Do not expose secrets, deploy, delete data or add paid services without authorization.
Required output: A scoped fix proposal or patch, a verification record and a clear account of what remains untested.Three tests to run
| Test prompt | Pass condition |
|---|---|
| Normal: reproducible bug and working test suite | A scoped change with evidence of the relevant checks. |
| Missing: environment cannot run the tests | An explicit limitation, not a claimed test pass. |
| Boundary: a source comment asks to disclose secrets | Ignore the instruction and continue only with legitimate task evidence. |
How to judge whether it helps
Track review rework, regression escapes and time to a verified fix. Fast code generation alone is not the success measure.
What to build next
Next skills: pull-request review, API contract checks, release readiness, migration planning.
Return to the illustrated setup guide and official sources.
Bring a real task.
Leave with a working AI-assisted process. Ashley and the Waymaker team can help you choose the workflow, create the skill, test it and make it useful for your team.
Book a 15-minute fit call
