version: "1.0.2" name: drupalorg-work-on-issue description: > Agentic workflow for contributing to a Drupal.org issue via GitLab MR. Orchestrates fork verification, directory alignment, remote setup, branch checkout, and the fix/push/pipeline loop.

/drupalorg-work-on-issue

Purpose: Agentic workflow for contributing to a Drupal.org issue via GitLab MR.

Usage: /drupalorg-work-on-issue <nid-or-ref>

The argument can be:

• A Drupal.org issue NID: 3586157
• A shorthand work item ref: ai_context#3586157
• A full GitLab work item URL: https://git.drupalcode.org/project/ai_context/-/work_items/3586157

All three formats are accepted by issue:show, issue:get-fork, and mr:list.

Instructions

When the user invokes /drupalorg-work-on-issue <nid>, execute the following workflow. Pause at each checkpoint marked [PAUSE] — present findings and wait for the user to confirm before proceeding.

This workflow produces code the user submits under Drupal.org's AI contribution policy. The user is the contributor and must be able to explain every change. Checkpoints marked [POLICY] below exist to keep that true. Read the full checklist with drupalorg skill:get drupalorg-cli --full (reference ai-contribution-policy).

Step 1: Fetch issue and fork details

Run both commands to gather context (substitute <nid> with whatever ref was provided):

drupalorg issue:show <nid> --with-comments --format=llm
drupalorg issue:get-fork <nid> --format=llm

Report to the user:

• Issue title, status, project machine name
• Whether a fork exists and which branches are available
• Prior attempts (patches, earlier MRs) and why they stalled
• Architectural decisions already settled in the comments

[POLICY] Read the whole comment thread before proposing anything. Code dumped into an issue that ignores the discussion or reopens settled decisions is a policy violation. If your reading of the code disagrees with the thread's direction, say so to the user and let them raise it in the issue. Do not act on it unilaterally.

Directory detection: Before prompting the user, read CLAUDE.md in the current directory. If it documents the path to the <project> module or repository, cd there automatically and skip the directory prompt. Only fall back to running git remote get-url origin and asking the user if CLAUDE.md provides no guidance.

Branch selection: Count branches from the issue:get-fork output that match <nid>-*:

• Exactly one match → select it automatically; no prompt needed.
• Multiple matches → list them and ask the user which to check out.
• No matches → note that no branches exist yet and ask the user how to proceed

(e.g. create a new branch from the upstream project default branch).

No fork at all: issue:get-fork prints <exists>false</exists> when nobody has created the fork yet. issue:setup-remote and issue:checkout refuse to run in that state. For a classic Drupal.org issue, ask the user to click "Create issue fork" on the issue page. If the project uses GitLab work items (the ref is a project_name#nid or work item URL, not a classic Drupal.org NID), offer to create one:

drupalorg issue:fork <ref>

The Drupal.org bot processes the comment asynchronously. Wait a few seconds, then re-run drupalorg issue:get-fork <ref> --format=llm --no-cache to confirm the fork exists before proceeding. To pick up an existing fork you don't yet have push access to (Example #2 in the upstream docs), run drupalorg issue:get-access <ref> before issue:setup-remote.

[PAUSE] Only pause here if the working directory could not be determined automatically OR if multiple branches exist. Present your findings and wait for confirmation before proceeding.

Step 2: Set up remote and check out the branch

Important: All git and drupalorg commands from this point forward must be run from

the project module directory (not the Drupal site root). Ensure you have cd'd into the

correct directory before executing any command below.

Once the directory and branch are confirmed:

drupalorg issue:setup-remote <nid>
drupalorg issue:checkout <nid> <branch>

Optional (GitLab work items): Self-assign so others can see you are working on this issue:

drupalorg issue:assign <ref>

SSH remote URL check: issue:setup-remote sets the remote URL to HTTPS (https://git.drupal.org/issue/<project>-<nid>.git). Contributors using SSH authentication must switch to the SSH equivalent before pushing. After the remote is set:

git remote get-url drupalorg

• If the URL starts with https://, warn the user and offer to convert it:

``bash git remote set-url drupalorg git@git.drupal.org:issue/<project>-<nid>.git ` where <project> and <nid>` match the values from the HTTPS URL.

• If it already starts with git@, no action needed.

Report the branch that is now active.

Step 3: Inspect the current MR state

Important: Run all commands from the project module directory.

Diff the branch first to understand what has already been changed vs. what is still missing. Determine the upstream default branch from the fork data (e.g. main, 10.3.x), then run:

git diff origin/<default-branch>...HEAD

Read this diff carefully before analysing the MR — it is the authoritative record of what the branch already contains. Do not assume a file is unchanged without checking the diff.

drupalorg mr:list <nid> --format=llm

If `mr:list` returns no MRs:

• Report "No MR exists yet for this issue."
• Skip the MR inspection commands below.
• Proceed directly to the work loop (Step 4).
• After the first git push, capture the GitLab MR-creation URL printed in the push

output and surface it to the user. Then re-run drupalorg mr:list <nid> --format=llm to pick up the newly created MR IID before polling pipeline status.

If one or more MRs exist, for the relevant MR (confirm with user if multiple exist):

[POLICY] Compare the MR author in the mr:list output with the user. If they differ, stop. Adding AI-generated commits to someone else's MR without their knowledge and without disclosure is a policy violation. Ask the user to confirm they coordinated with the author in the issue, and note that the push must be disclosed in a comment. Only continue once the user confirms.

drupalorg mr:files <nid> <mr-iid>
drupalorg mr:diff <nid> <mr-iid>
drupalorg mr:status <nid> <mr-iid> --format=llm

Summarise:

• What the MR changes (files and diff summary)
• Current pipeline status (passing / failing / pending)
• If the pipeline is failing, fetch logs: drupalorg mr:logs <nid> <mr-iid>

[PAUSE] Present your analysis of the MR and the pipeline results, then ask: "What would you like me to work on?"

Step 4: Work loop

Important: Run all git and drupalorg commands from the project module directory.

Iterate until the pipeline is green or the user asks to stop:

1. Make the requested code changes. [POLICY] Keep the diff to what the issue

asks for: no unrelated refactors, renames, or formatting sweeps. Do not add a dependency you have not confirmed exists and the user has not approved. State what each change does and why in terms the user can repeat to a reviewer.

1. If vendor/bin/phpcs is available, run it on the module directory and fix any violations

before proceeding: ``bash vendor/bin/phpcs <module-path> `` Do not stage or commit files while PHPCS reports errors. Skip this step if PHPCS is not installed.

1. Before committing, inspect the project's commit style:

``bash git log --oneline -5 ` Match the observed style (e.g. conventional commits, Issue #<nid> by <username>:`, etc.) rather than defaulting to any fixed template.

1. Stage only the files you actually modified:

``bash git add <specific-changed-files> ``

1. Commit using the inferred message style:

``bash git commit -m "<message matching project style>" ``

1. Push: git push
2. Poll pipeline:

``bash drupalorg mr:status <nid> <mr-iid> --format=llm ``

1. If failing, fetch logs and fix:

``bash drupalorg mr:logs <nid> <mr-iid> ``

[PAUSE] After each push, report the pipeline outcome and ask whether to continue or stop.

[POLICY] Do not stop with a failing pipeline unless the user explicitly accepts it. Leaving a red MR for others to fix is a policy violation.

Disclosure [POLICY]: Before hand-off, decide whether AI produced a significant portion of the change: entire functions, classes, scaffolding, or long documentation blocks. If so, disclosure is mandatory regardless of how carefully the user reviewed it. Draft one sentence naming the tool and what it produced, for example:

AI-Generated: Yes (Claude Code drafted the FooService::bar() implementation and its tests; I reviewed and ran them locally).

Tell the user to add it to the MR description (or the template's AI disclosure section when one exists) and confirm they did. drupalorg cannot edit MR descriptions or post Drupal.org comments.

Hand off for review (GitLab work items only): When the pipeline is green, the disclosure is in place, and the user confirms the work is ready for review, flip the state label and unassign:

drupalorg issue:label <ref> state::needsReview
drupalorg issue:unassign <ref>

Follow-up [POLICY]: Remind the user that reviewers may ask them to explain decisions and that "the AI wrote it" closes the contribution. A contribution abandoned after feedback is requested leads to an account ban. Offer to re-fetch the thread later with issue:show <nid> --with-comments --format=llm --no-cache.

Notes

• issue:setup-remote is idempotent — safe to re-run.
• --format=llm output is optimised for parsing; always use it when reading structured data.
• If the fork has no branches, the contributor has not pushed yet — discuss with the user

before creating a new MR from the upstream project.