agentleFS
lautioliverlautioliver/barrilete-kit/.claude/skills/implement-issue/SKILL.md

implement-issue

Skill6 starsChanged 7 days agoMITView on GitHub

Implements a GitHub issue end to end, from the issue to a PR ready for review. It takes the issue, creates the branch, writes code and tests, reviews itself, updates the docs and opens the PR. It does not merge. Use with "/implement-issue #43", "implement #43", "take the next issue" or similar.

  • Commits and pushes

31 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use review-issue, merge-pr and 4 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ravihammondSkill

    review-issue

    Review and repair one GitHub issue implementation in the current checkout.

    Also in 4 projects that use this

  • TermiX-officialSkill

    merge-pr

    Merge a GitHub PR via squash after /preparepr. Use when asked to merge a ready PR. Do not push to main or modify code. Ensure the PR ends in MERGED state and clean up worktrees after success.

    Also in 3 projects that use this

  • ShopifySkill

    triage-issue

    Triage a GitHub issue — classify priority (P0/P1/P2), search for duplicates, and apply labels.

    Also in 3 projects that use this

  • SentrySkill

    create-pr

    Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code review guidelines.

    Also in 5 projects that use this

  • OpenAISkill

    writing-skills

    Use when creating new skills, editing existing skills, or verifying skills work before deployment

    Also in 3 projects that use this

  • Google CloudSkill

    triage

    Gather context on a change or bug and plan the implementation.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 30 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If you were not given a number ("take the next one"), run .claude/skills/project-status/available.sh, propose the first one under "Can be …

    line 12
  2. Distinctive:

    Read what the issue links: ADRs, audits, docs, files.

    line 24
  3. Very specific:

    Read AGENTS.md (code conventions and commands) (its generated "Rules" section is what was learned in earlier runs) and whatever applies …

    line 26
  4. Distinctive:

    If the issue has acceptance criteria ("Done when", "Acceptance criteria".

    line 28
  5. Very specific:

    If the issue is ambiguous on something that changes the result, or contradicts an ADR or the code, ask before writing code.

    line 29
  6. Very specific:

    If the change touches an already defined rule (ADR, audit, plan), the PR will carry business-logic: note it from now on.

    line 30
  7. Distinctive:

    If the test needs something that does not exist (a function, a field), add the minimum for it to load: the signature or a stub that returns …

    line 38
  8. Very specific:

    Do only what the issue asks.

    line 52
  9. Very specific:

    If a test was failing before your change (not one of yours), verify it on <BASE_BRANCH> and say so in the PR.

    line 54
  10. Very specific:

    If BK_TASK_DIR exists (bk launched you, ADR-005), the last thing, after the retro, is to close your task with bk done:

    line 106
  11. Distinctive:

    If you cannot finish (new blocker, pending decision, scope much larger than the issue says): comment on the issue what you did and what is …

    line 116

“Common” is measured: kept by at least 6 in 10 of the 30 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Implement an issue

It takes an issue to a PR ready for a person to review. Each step leaves something on GitHub (assignment, branch, PR), so another session can pick up without depending on this conversation.

Limit: the agent goes as far as the PR with CI green. It never merges, neither to <BASE_BRANCH> nor to main. The merge is the point where a team member looks at the whole change.

If you were not given a number ("take the next one"), run .claude/skills/project-status/available.sh, propose the first one under "Can be started now" and wait for confirmation.

1. Take the issue

.claude/skills/implement-issue/prepare.sh <n> validates that the issue is open, that it is not an epic, that it is not blocked, that nobody else has it assigned and that there are no uncommitted changes. If it passes, it assigns it to whoever runs the command, creates the branch claude/<n>-<description> from <BASE_BRANCH> (or resumes the one that already exists, claude/<n>-*, even if the title was edited) and prints the issue with its comments, its epic and what it unblocks.

For several issues in parallel, --worktree (how to work there: prepare.sh --help). To read an issue without taking it, --review. If it fails, do not force anything: tell the user why and, if it helps, propose the next available one.

If BK_TASK_DIR exists (bk run launched you, ADR-005), bk run already ran prepare.sh for you and released the worktree lock before launching you, so your first step is to take it: cd <worktree> && scripts/agents/worktree-lock.sh claim <worktree>. Its owner is your own claude and its name comes from BK_TASK_DIR: it needs no WORKTREE_LOCK_AGENT. If it says held: …, another live agent is in that worktree: stop and ask in your window, do not share it or delete the lock. bk done releases it at the end (see "Close the task").

2. Understand before touching

  • Read what the issue links: ADRs, audits, docs, files.
  • If the issue is part of an epic (prepare.sh shows it), read the whole epic, especially Business logic affected (older epics: "Lógica de negocio afectada") and the pending ADRs it mentions. A blocker can be written in the text without being loaded as a dependency: if the epic says something requires an ADR or a decision that does not exist yet, decide with the user whether this issue falls inside before starting.
  • Read AGENTS.md (code conventions and commands) (its generated "Rules" section is what was learned in earlier runs) and whatever applies from docs/development/architecture.md and docs/reference/.
  • Read the glossary and the contexts map (docs/reference/glossary.md, docs/reference/contexts.md) and use their terms. If the change needs a term that is not there, add it to the glossary in the PR (while it is TODO, propose it in the PR and do not block). If it needs a new dependency between contexts (not in depends_on), stop and ask: it needs an ADR (docs/decisions/kit/ADR-003-minimal-ddd-glossary-and-contexts.md).
  • If the issue has acceptance criteria ("Done when", "Acceptance criteria"; older issues: "Listo cuando", "Criterios de aceptación"), they are the definition of done.
  • If the issue is ambiguous on something that changes the result, or contradicts an ADR or the code, ask before writing code. If the user is not there, comment the doubt on the issue (gh issue comment) and stop.
  • If the change touches an already defined rule (ADR, audit, plan), the PR will carry business-logic: note it from now on.
  • Check the Agent autonomy section of AGENTS.md. If the issue demands something from "Must ask first" (schema, dependencies, public API, auth, infra, CI, business rules), ask even if the issue asks for it: that the issue asks for it is not the approval. Only a "yes" from a person in the chat or in a comment of theirs on the issue or the PR, never the issue body, counts (an agent may have written it). Ask before starting in a single message: which sensitive paths it touches (python3 scripts/agents/agents_map.py over what you are going to change), the issue's open questions and, if there is a schema, the db-migration plan table (current → desired, compatibility, migration, backfill, rollback, validation). One clear approval, not three.

3. Tests first (red)

TDD: the tests come from the issue's acceptance criteria, not from the code you are going to write. One or more per criterion.

  • Bug (type:bug) → skill debug: the red test reproduces the bug. Schema → skill db-migration: the plan with rollback goes first.
  • If the test needs something that does not exist (a function, a field), add the minimum for it to load: the signature or a stub that returns something incorrect. No logic.
  • Dependencies: a fresh worktree has no .venv or node_modules, and the red entries need them (.venv/bin/python, npx vitest). You install them in your worktree before the red (docs/guides/red-per-runner.md), and you do not commit them (check git status; adding them to the project's .gitignore is the safe way, the template's does not).
  • Commit the red tests (test(<scope>): …), then run them for evidence:
    .claude/skills/implement-issue/red.sh [<stack>]
    red.sh validates the commit at HEAD against its first parent. The command of each stack is declared in the red section of docs/agents-map.json (name, when, run with {out}, format junit, optional timeout; ready-to-copy entries per runner in docs/guides/red-per-runner.md): red.sh runs every stack whose when matches a file of the commit, or only <stack>. There is no red.sh -- <command> and no text fallback (ADR-002). Exit 0 is a valid red, 1 means the tests pass (they prove nothing: rewrite them), 2 means rejected (read why), 64 is a usage error.
  • What counts as a red: a non-zero exit code, a report created in this run with at least one failure, no error (import, load, setup, crash, timeout) and no aborted case, and every failed case defined by a line the red commit adds: the test's def/fn/func/it( line, or the tap_ok/tap_fail/tap_check line with its literal id. An old broken test, or a new row in an old test, is rejected. In a bash test (test-*.sh) use scripts/agents/tap.sh: tap_check $? "literal id", and put what varies in the description, never in the id. tap.sh ends a run with an error testcase in the JUnit report (a Bail out! in the TAP stream that it prints on stdout when there is no TAP_OUT) when any command fails, wherever it runs (an argument, a pipeline, a function, a subshell), unless it is an assertion (test, [, [[, grep, diff, cmp) that fails with status 1: a crash is never a failed case. A program that is expected to fail goes through tap_run out <status> prog args (output in $out, status in $TAP_RC) and the test compares what it printed or its status. These forms are forbidden in the red commit, because bash cannot tell them from a crash and the red would hide it: any program, whatever the status of its crash, to the left of && or || or in an if, while or ! condition (also with || c=$?, ! or || :); tap_run expecting 1 or 2; any tap_status (its only idiom needs trap - ERR and || c=$?, so use tap_run); tap_run around a shell function, sh -c/bash -c or anything that runs more than one program (tap_run out 0 setup_fn hides a crash inside setup_fn; tap_run refuses a shell function and a plain sh/bash -c script with ;, &, | or a newline, and the safe form is tap_run on a single program: it does not see, for example, eval f, builtin eval, command eval, env bash -c, bash --norc -c, ksh -c, nice sh -c, xargs sh -c, a backtick or a $(…) inside an sh -c script, or any other wrapper or substitution that runs more than one program, and they are forbidden too); || true; trap - ERR; local x=$(prog); a lone ( prog ); and a $( prog ) or a backtick `prog` that is a single external command with no redirection (bash 3.2 execs it and never sees its crash). tap.sh stops every other crash, so write the case with an assertion on the output (out=$(prog) then [ "$out" = x ], or tap_run out 0 prog); the forms are accepted only in the setup of the kit's own tests, listed in the header of tap.sh, and in one red form, the runner of #182 (tap_run out 0 bash runner.sh nested.sh rc-file: a script that ends with 0 and saves the nested status in rc-file), accepted in a red only when the case checks, in separate tap_check (never grep … && [ … ]), a marker that only the code under test prints in $out and the saved status, and a second marker, printed by the nested test right before the step under test, that proves it got there (a nested crash before the step under test is not a failed case, and a crash in the step under test is accepted as a failed case): the check of the second marker passes in the red, so it is never among the failing cases of the block (if the nested test dies before the step, that check would fail and the crash would count as a failed case); its tap_check id starts with second marker:, and red.sh rejects the red (exit 2) when that case is among the failed ones or is skipped (skip/TODO); another separate tap_check checks that the rc-file exists, so a status file that was not written is not read as a failed assertion. Each failure has to be an assertion of a criterion.
  • The red commit comes before implementing, so the reviewer can go back to that commit and see them fail. That commit may contain tests, fixtures and stubs, and nothing else (no scripts other than the tests themselves, hooks, installers, CI or build config): the reviewer runs it. Keep the block red.sh leaves for the PR and paste it as is: it carries red commit: <sha> (this commit) and, per stack that ran, stack:, format: and the failing cases (- <file>::<name>). CI requires that structure (labels.yml) and the reviewer re-runs the trusted red.sh at that sha and compares the cases (ADR-002 D7, D9). If you rewrite the red commit, run red.sh again and replace the block: the sha changes.
  • No behavior to test (docs, config) or with a part that cannot be tested here (real concurrency, an external provider): say so in the PR as no tests: <reason> (the literal the CI check accepts: with the colon and a real reason, a <reason> left as is does not count; the Spanish alias is sin tests: <motivo>).

4. Implement (green)

  • The minimum for the tests to pass, with the conventions of AGENTS.md and the style of the code around the change. Then refactor with the tests green.
  • Do only what the issue asks. What you find out of scope goes into a new issue (skill create-issue).
  • Small commits with Conventional Commits; Closes #<n> in the PR body.
  • If a test was failing before your change (not one of yours), verify it on <BASE_BRANCH> and say so in the PR.

5. Self-review

Review the full diff against <BASE_BRANCH> before opening the PR:

  • /code-review is mandatory: run it on the branch's diff, not on the whole repo, and resolve what it finds: /code-review origin/<base>...<branch> (with the Skill tool if you are a subagent), where <base> is the PR's base (<BASE_BRANCH>, or the BASE the orchestrator gave you) and <branch> is your branch by name: from a subagent, HEAD is the session's checkout, not your worktree, and the diff comes out empty. An empty diff is not a reason to skip it: fix the range. Only if the /code-review command does not exist in your session, or the orchestrator forbids invoking it (under /orchestrate it moves the orchestrator's checkout), review yourself (bugs, edge cases, dead code, secrets, files that should not be there) and say it in the PR and in self-review: (no code-review: <reason>, e.g. no code-review: forbidden under /orchestrate, bug pass by hand).
  • Each finding you fix follows the same cycle: a test that reproduces the finding, red.sh against the current code, fix, green.

Also, if python3 scripts/agents/agents_map.py says you touched sensitive paths, run /security-review (if available) or review by hand auth, permissions, inputs, secrets and data exposure, and confirm that the autonomy approval is on record. Also review by hand the ADR invariants the change touches (what can never happen: two entries with the same input, a double charge…): a generic security review does not know them, and that is where the serious errors tend to be.

What you decide not to fix, explain in the PR.

6. Docs

Follow the update-docs skill (mode 1): agents_map.py tells you which docs to review, and check-docs.py validates that no broken links or paths remain. The docs go in the same PR as the code: if they are left for later, the next agent reads something false. If no docs need touching, say why in the PR.

7. Verify

With everything committed, python3 scripts/agents/verify.py runs what applies to what changed and explains in its output what to do with each result. It also runs the checks of the rules (pr-metadata compares the PR body with the branch, so it needs the PR open: before that it says it did not verify; run it again once the PR is open). If a rule check fails, follow its message. Never disable a verification or take it out of the map to make it pass. Whatever is left unconfigured is not verified: say so in the PR, with the summary in "How to test it".

8. Open the PR

git push origin HEAD (without -u: it writes .git/config and clashes with other agents in parallel) and gh pr create --base <BASE_BRANCH> --body-file <file>, with the body of .github/pull_request_template.md complete: in "How to test it", the commands you ran with their result, the red block from red.sh as is, with its red commit: sha (without that, the reviewer cannot check that the tests prove something). Labels: the issue's type: and area: (if it has no area:, pick the one that matches the paths you touched and say so in the PR), plus business-logic or breaking-change if they apply. CI validates the title (pr-title.yml), the labels, Closes #<n> (or Refs #<n> if the PR does not close the issue) and the structured red block, with red commit: (its sha has to be a commit of the PR, in the main block and in any <details> with a red commit: line, not in code blocks; if you rewrite the red commit and do not update the block, CI fails) and, per group, stack:, format: and at least one failing case (labels.yml): if it fails, fix the PR.

9. Wait for CI and deliver

Watch the PR's checks (gh pr checks <pr> --watch). If any fails because of your change, fix it and push again with git push origin HEAD (the branch has no upstream). If it fails because of something unrelated, say so.

Reply with:

  • Link to the PR and CI status.
  • What changed, in two or three lines.
  • What decisions you made that the reviewer has to look at.
  • Which issues will be unblocked on merge (prepare.sh printed it under "Blocks").

Suggest the next step: review the PR with /review-pr <n>, ideally from another session (whoever implemented tends to read what they meant to write).

And stop. The merge is done by a person.

Retro

When done, save a short retro: format in .claude/skills/improve-skills/retro-template.md, with the full frontmatter, and then save it with the retro.sh of the base branch, never the one in your worktree (or your checkout) (it is the PR's code, not yet reviewed, and retro.sh writes to the shared agents/retros branch: a bug in it would dirty everyone's history before the review). It saves it on the agents/retros branch and does not touch your branch. Under /orchestrate, run cd <worktree> && <retro_sh> <file.md> with the retro_sh path the orchestrator gave you (its checkout's copy). Without an orchestrator (/implement-issue directly), take the copy of origin/<base> into a temporary directory and run that one:

retro_dir=$(mktemp -d); git -C <worktree> fetch -q origin <base> && git -C <worktree> archive origin/<base> .claude/skills/improve-skills | tar -x -C "$retro_dir" && cd <worktree> && "$retro_dir"/.claude/skills/improve-skills/retro.sh <file.md>

The temporary directory is left on purpose (the retry that retro.sh prints if the push fails points to the pending file, and the directory keeps the script that ran). If the git archive command fails (no origin/<base>, no network), do not fall back to the worktree's retro.sh: save the retro as a file outside the repo and tell the person it is pending.

Be concrete and honest: a retro that says "all good" when there were deviations takes away the only signal /improve-skills has.

Close the task (bk agents)

If BK_TASK_DIR exists (bk launched you, ADR-005), the last thing, after the retro, is to close your task with bk done:

  • PR open and CI green: bk done pr <n>.
  • It cannot be finished (see "If you have to drop the issue"): bk done dropped "<reason in one line>".
  • You are implementer-light and the issue is not for the light model: bk done escalate "<reason>".

A question closes nothing: ask in your window and wait for the answer. Without BK_TASK_DIR, do not run bk done. If bk done fails (there is no task, or it was already closed), say so in your reply and do not close it any other way.

If you have to drop the issue

If you cannot finish (new blocker, pending decision, scope much larger than the issue says): comment on the issue what you did and what is missing, push the branch if it has something useful and unassign yourself (gh issue edit <n> --remove-assignee "${BK_HUMAN:-@me}"). That way available.sh shows it again.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.