From patinaproject-skills
Drive one same-repository GitHub issue to an evidence-backed production-ready PR outcome. Use when the user invokes `/develop-issue #123`, `/develop-issue https://github.com/<owner>/<repo>/issues/123`, or asks to develop exactly one issue end to end.
How this skill is triggered — by the user, by Claude, or both
Slash command
/patinaproject-skills:develop-issueThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Invoke with exactly one same-repository GitHub issue reference:
Invoke with exactly one same-repository GitHub issue reference:
/develop-issue #123
/develop-issue https://github.com/<owner>/<repo>/issues/123
This skill is a goal-directed controller. It coordinates existing workflow skills, preserves their contracts and repository guardrails, and never merges a pull request.
Production-ready implementation, all visible PR checks passing, and all local review findings plus PR review comments addressed.
Treat production-ready as an evidence-backed readiness case, not a guarantee of zero risk. Do not make unsupported certainty claims such as absolute certainty or similar wording.
goal-met: production-readiness evidence supports goal-met; all required
exit gates are satisfied and all visible required and optional PR checks pass.human-blocked: progress requires human judgment, external access, product
or design decisions, permissions, secrets, conflicting direction, or valid
work outside the issue.Do not report goal-met while unresolved human-owned blockers remain.
Before branch setup or implementation, confirm these installed skills are available in the agent environment:
new-branchtdddiagnosereview-codefinish-prIf any are missing, halt before implementation. Report the missing skill names and install guidance:
npm_config_ignore_scripts=true npx skills@latest add patinaproject/skills --skill new-branch --skill review-code --skill finish-pr -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@tdd -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@diagnose -y
The tdd, diagnose, write-a-skill, zoom-out, and prototype install
hints intentionally track their source catalog's default branch. Consumers who
need a frozen install can add #<git-ref> to those sources.
Conditional routes are not blanket prerequisites. Check that the named skill is available only when the issue triggers that route; halt with the missing skill name and install guidance only for a triggered missing route.
Install guidance for triggered conditional routes:
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@write-a-skill -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@zoom-out -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@prototype -y
write-a-skill when the issue changes an installable skill
package surface: skill entry instructions, frontmatter or description,
workflow contract text, examples, reference material, or bundled helper
scripts. For skill-package changes that include executable helper scripts,
run write-a-skill before tdd, then use tdd for executable behavior.zoom-out for ad-hoc, read-only discovery when the agent cannot yet
explain the relevant modules, callers, and domain vocabulary. It may run in a
background explorer when the host supports that, but the main workflow must
consume the result before choosing an implementation route.prototype only when the issue explicitly asks for throwaway exploration,
state-model sanity checks, UI direction exploration, or equivalent prototype
work. Delete or absorb prototype output before local review unless the issue
explicitly asks to commit prototype artifacts.Do not add normal /develop-issue routes for upstream planning, triage,
architecture review, handoff, or conversation-mode skills unless the issue
explicitly asks for them.
#<number>, or same-repository GitHub issue
URL.gh
repository.Pause for a human when the issue lacks actionable acceptance criteria, conflicts with repository rules, requires a design decision, depends on external access, or otherwise needs judgment not recorded in the issue.
review-code findings are fixed or dispositioned.finish-pr
are fixed or dispositioned.finish-pr, all currently visible required and optional PR checks pass
for goal-met.human-blocked final report; do not report goal-met while any visible PR
check is still failing.For this skill, all visible PR checks include required and optional checks.
new-branch: issue-linked branch setup. Branch setup is an automatic
precondition before implementation or publishing work begins. The worktree is
"correctly prepared" only when the current branch name encodes the target
issue number per the <issue>-<slug> convention new-branch produces — not
merely when the branch differs from the default branch. Skip new-branch only
when that issue-linked check passes for the target issue. When the current
branch is non-default but not issue-linked (for example a host- or
tool-generated name like claude/<slug>), run new-branch to establish the
issue-linked branch instead of treating it as prepared. If a host-provided
branch cannot or should not be renamed to the issue-linked name, surface that
deviation in the report rather than developing the issue silently on a
non-issue-linked branch.tdd: clear behavior implementation and behavior-level tests.diagnose: unclear root cause, missing reproduction, flaky behavior, or
performance regressions.review-code: fresh-context local branch-diff review.finish-pr: commit, push, PR creation or update, PR checks, PR feedback
loops, and ready-to-merge reporting.write-a-skill: installable skill package surface changes.zoom-out: read-only discovery when the agent cannot yet explain relevant
modules, workflows, or vocabulary.prototype: only explicit throwaway exploration requests.Read AGENTS.md and CLAUDE.md if present, plus any docs they import.
Validate the single same-repository issue reference and required child skills.
Mark the issue as started before branch setup. This "I am starting work"
step has two independent actions: self-assignment and GitHub Project status.
Run each on a best-effort basis; neither blocks real work, and neither
causes a human-blocked halt.
Self-assignment:
assignees field (for example
gh issue view <number> --json assignees). Assign only when that list is
empty.gh-authenticated user with a single issue-level call,
gh issue edit <number> --add-assignee @me, run once. Resolve "myself" to
@me; never hardcode a username, so the skill stays reusable across every
consumer.@me or anyone else —
do nothing. Do not add @me as an additional assignee.new-branch, which stays a pure local-branch tool.GitHub Project status:
projectItems data). For each existing GitHub Project item:
In progress is offered as an exact option and update that
project item to In progress.In progress option, or project-item
inspection or updates fail due to permissions.Satisfy the branch setup precondition: verify the current branch is the
issue-linked branch for the target issue (its name encodes the issue number
per the <issue>-<slug> convention new-branch produces). Skip new-branch
only when that check passes; otherwise — including when the worktree starts
on a non-default but non-issue-linked branch — run new-branch to establish
the issue-linked branch, or surface the deviation when a host-provided branch
cannot or should not be renamed.
Apply triggered conditional routes from the Conditional Routes section.
Choose the next capability by naming the current gap between actual state and the terminal goal.
Do not treat implementation, diagnosis, local review, or publishing as a fixed mandatory sequence. Invoke the capability that removes the current blocker or readiness gap.
Run repository-documented verification before local review and before final publishing readiness decisions.
Check for reviewable local changes: committed branch diff from the default-branch merge base, staged changes, unstaged changes, or untracked files.
When reviewable local changes exist, invoke review-code and inherit its
full contract. Explicit use of develop-issue is sufficient approval for
this required local review gate: dispatch the fresh read-only reviewer
without asking for another user confirmation. Preserve the review-code
boundary exactly: no same-thread fallback and no file edits, staging,
commits, pushes, PR comments, review-thread mutation, or other worktree
mutation. Halt if fresh reviewer dispatch is unavailable or if review-code
reports a halt condition.
Route local review findings through the Review Finding Router.
Use finish-pr for commit, push, PR creation or update, visible check
observation, PR feedback loops, and ready-to-merge reporting. Invoke
finish-pr only after local verification and review-code are clean,
skipped because no reviewable local changes exist, or every local finding
has a recorded ready-for-agent, ready-for-human, or wontfix
disposition.
Loop until the terminal goal is met or a human-owned blocker prevents further progress.
During long-running or resumable execution, keep compact checkpoint state using
the final-report vocabulary: issue reference and URL, branch name, terminal
state, meaningful changes, readiness, blockers, and next action. Resume from
that state and continue until a terminal workflow state is reached:
production-readiness evidence supports goal-met or there is a documented
human-blocked stop.
Classify findings into exactly one of these outcomes:
| Outcome | Use When | Next Action |
|---|---|---|
ready-for-agent | The expected behavior is clear or evidence can be gathered locally | Route clear behavior changes to tdd; route unclear root cause, missing reproduction, flaky behavior, or performance regression to diagnose |
ready-for-human | The finding needs judgment, external access, manual testing, design input, missing information, changed scope, product decisions, permissions, conflicting direction, or valid work outside the issue | Stop the loop and report the blocker with evidence checked |
wontfix | The finding is stale, incorrect, conflicts with repository rules, or is intentionally rejected | Explain politely in the report; add concise code comments only when future reviewers would otherwise re-raise the same concern |
There is no needs-info state in v1. Insufficient information maps to
ready-for-human.
Progress updates, resumable checkpoints, and final handoffs should report what changed, whether the work is ready or blocked, and what the human should do next. Keep verification evidence internally for decisions. Report verification details when they failed, skipped, interrupted, changed readiness, explain a blocker, identify residual risk, or create a human next action.
Leave out command inventories, pass counts, green check names, child-skill gate lists, routine head SHAs, and project-status details that do not affect what the human needs to know. Translate child-skill output into outcome, readiness, blocker, and next-action language. Progress updates should name the current checkpoint and next action without repeating check lists. When verification is interrupted, mention it only when the interruption changes readiness or asks the human to decide something.
When the workflow stops, write for a human first, not as a process log. Lead with the outcome. Keep the default report short, direct, and human-readable, and surface only details that change what the reader needs to understand or do.
Include:
goal-met or human-blocked.review-code result, or that it was skipped because no reviewable
local changes existed, only when it changes reviewer confidence or next
action.wontfix explanations, if any.finish-pr runs.Keep visible and specific:
Remove or minimize:
When child skills return detailed readiness evidence, translate child skill
reports into the final-report vocabulary above. Do not forward child-skill gate
inventories. Do not repeat finish-pr readiness gates such as clean worktree,
head SHA equality, merge state, check inventory, or review-thread count when
they all passed; collapse them into the verification line unless a failed gate
changes what the human should do next.
Example for issue 190:
Done: [#190](https://github.com/patinaproject/skills/issues/190) is implemented
on [PR #197](https://github.com/patinaproject/skills/pull/197)
([branch `190-human-focused-final-output`](https://github.com/patinaproject/skills/tree/190-human-focused-final-output)).
Changed:
- `develop-issue` final reports now lead with outcome and meaningful changes.
- Routine verification is collapsed unless something failed, skipped, or needs
human attention.
Verified: routine checks passed.
Needs human attention: none before review.
Avoid final output shaped like a process transcript:
Implemented issue #190.
Verification:
- develop-issue workflow test passed.
- markdownlint passed.
- type-check passed.
- commit hook passed.
- PR check Test Gate passed.
- PR check code-review passed.
- PR is MERGEABLE and CLEAN.
Child skills invoked: new-branch, write-a-skill, tdd, review-code, finish-pr.
No unrelated dirty files except local config. Goal marked complete.
Use the bad shape only as an anti-example; do not mirror its structure.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub patinaproject/skills --plugin patinaproject-skills