stellar-dev-skill-issue-solver

name

stellar-dev-skill-issue-solver

description

Work through the issues assigned to the user on the stellar/stellar-dev-skill repo (the AI-skills repo behind skills.stellar.org): find the open issues assigned to them, pick one (or go oldest-first), understand what it asks, create a branch, implement a best-effort fix following the repo's conventions — skill content, site code, or catalog cards — verify it (Raven fact-checks, compile checks, pnpm build), commit, and automatically open a PR that links the issue and flags any assumptions — then hand the new PR to the stellar-dev-skill-pr-review skill for review. Use whenever the user asks you to work on / solve / fix / clear the issues assigned to them on stellar-dev-skill, or turn a specific stellar-dev-skill issue into a PR. This is the write-and-open-PR counterpart to stellar-dev-skill-pr-review (which only reviews existing PRs). Do NOT use for reviewing/merging PRs, for stellar/stellar-docs (that's stellar-docs-issue-solver), or for issues that need a product/design decision rather than a change you can implement.

Solving a stellar-dev-skill issue → PR

You turn an assigned issue on stellar/stellar-dev-skill into an opened pull request. This is the counterpart to stellar-dev-skill-pr-review: that one reviews PRs; this one creates them. The repo holds AI agent skills (skills/*/SKILL.md plus supporting markdown) and a Next.js catalog site (site/, pnpm, static export) published at https://skills.stellar.org.

Two principles govern everything here:

• Best-effort, but honest. When an issue is underspecified, make your best reasonable attempt rather than stalling — but state every assumption you made, loudly, in the PR body, so a human can catch a wrong guess. Skill content is ground truth for other people's agents; a confidently-wrong line is worse than an explicit "I assumed X — please confirm."
• You can open, but you can't bless. You'll auto-open the PR, but you are its author, so you don't approve or merge your own work. Your job ends at a well-verified, clearly-described PR.

What you need

• gh CLI authenticated with push access to stellar/stellar-dev-skill (gh auth status). Git configured with the user's identity.

• The Raven MCP — use it extensively, on both ends: to research correct Stellar behavior before you write a word, and to fact-check every factual line after you've drafted it. If it isn't connected, it's one command:

  claude mcp add --transport http stellar-raven "https://raven.stellar.buzz/mcp"
  

  Without Raven, don't assert facts you can't verify — write only the structural/ editorial part and flag the factual gap prominently in the PR.

• pnpm + Node 22 to verify the site builds (CI runs pnpm 10.15.1).

• Rust/cargo and the stellar CLI when your change includes contract or CLI code — compile what you write against the real crates before you commit it.

Workflow

Run scripts/issue_context.sh to list assigned issues or dump one issue's full context and a suggested branch name — it wraps the gh calls below.

1. Find the assigned issues

gh issue list --repo stellar/stellar-dev-skill --assignee "@me" --state open \
  --json number,title,labels,updatedAt \
  --jq '.[] | "#\(.number)  \(.title)  [\([.labels[].name]|join(","))]"'

Show the user a short list. Work the one they name, or oldest-first, one issue at a time — finish and report on one before starting the next.

2. Understand the issue — and classify the change

scripts/issue_context.sh <ISSUE_NUMBER>     # title, body, comments, labels, branch suggestion

Read the body and every comment, then decide honestly whether this is a change you can implement, and of which class:

• Skill content (skills/**) — stale APIs, wrong flags, renamed methods, missing gotchas, restructures. The bread and butter. Proceed.
• Site code (site/**) — TypeScript/Next.js fixes. Proceed if scoped.
• Cards (site/src/data/skills.ts) — adding/fixing catalog entries. Community skills go in ECOSYSTEM_CARDS; official in-repo skills in SKILL_CARD_SOURCES. Proceed, but vet any third-party links you add.
• No — it needs a listing-bar or product decision, a whole new skill without provided source material, depends on unreleased protocol/SDK surface, or is too vague even for a flagged best-effort. Don't fabricate a PR; report it as needing a human and move on.

Read the conventions before writing: the root README.md, site/CLAUDE.md for site work, and neighboring skills/*/SKILL.md files for skill structure.

3. Branch

Clone (or reuse a clone) and branch off fresh main. Match the repo's observed naming: short kebab-case, verb-led, e.g. fix-dapp-wallets-kit-v2, add-stellarlight-community-skill.

git clone https://github.com/stellar/stellar-dev-skill.git /tmp/stellar-dev-skill 2>/dev/null || \
  (cd /tmp/stellar-dev-skill && git fetch origin && git checkout main && git pull)
cd /tmp/stellar-dev-skill
git checkout -b <verb>-<slug> origin/main

Branching in the main repo (not a fork) matters: fork PRs get no preview deployment, and yours will.

4. Implement, minimally and in-convention

Make the smallest change that resolves the issue. Match the surrounding style and don't drift outside the issue's scope.

Research first, fact-check after — with Raven. Before writing any factual assertion (CLI flags and defaults, SDK method/type names, endpoints, protocol behavior and versions, fee/limit values, contract semantics, SEP details), look the answer up in Raven rather than recalling it. After drafting, run the finished lines back through Raven to confirm nothing drifted. If Raven can't confirm something, write around it and flag it in the PR rather than guessing.

Compile what you write. If your change includes code — Rust snippets, SDK calls, CLI invocations — scaffold a scratch project in a temp dir and build the exact code you're committing against the real crates/packages/CLI. Skill readers will paste this code; it has to actually work.

Verify the site still builds (always for site/** and cards; recommended even for pure skill content, since the site ingests skills/ at build time and regenerates llms.txt):

cd site && pnpm install --frozen-lockfile && pnpm lint && pnpm lint:ts && pnpm build

5. Commit and auto-open the PR

Commit with a message that links the issue so it auto-closes on merge, then push and open the PR automatically:

git add -A
git commit -m "<concise summary> (closes #<ISSUE_NUMBER>)"
git push -u origin HEAD
gh pr create --repo stellar/stellar-dev-skill --base main \
  --title "<concise summary>" \
  --body "$(cat <<'BODY'
Closes #<ISSUE_NUMBER>

## What this does
<1–3 sentences on the change and why it resolves the issue>

## Assumptions / needs confirmation
<every guess you made where the issue was underspecified — or "none">

## Verification
<what you verified: Raven confirmations, compile checks, pnpm build result — and what still needs review>
BODY
)"

Keep the Assumptions / needs confirmation section even when short — it's how best-effort stays safe. If there were none, say "none."

6. Hand off to review, then report

You don't review your own PR. Trigger the stellar-dev-skill-pr-review skill on the PR you just opened — it will run the class-appropriate checks (preview build, llms.txt diff, its own Raven pass) and post what it verified as a PR comment for the human reviewer. It won't merge (you're the author); it leaves the PR tested and ready for someone else to approve.

Then give a very short report (2–4 lines): which issue, the branch/PR you opened, one line on the change, and anything flagged for confirmation. State which issue is next; when none remain, say so and stop.

Report examples

Opened:

#60 "MPP skill has stale APIs" — opened PR #71 on branch fix-mpp-stale-apis. Replaced the five renamed methods, Raven confirmed the new signatures, site build green. No assumptions needed. Review skill ran; preview verified. Next: #52.

Couldn't solve:

#36 "add more community skill cards" — skipped, no PR. Which projects meet the listing bar is a maintainer call, not something I should decide. Flagging for you. Next: #51.

Guardrails

• Only open a PR when there's a real, verified change. If best-effort yields nothing solid, report the issue as needing a human instead of opening an empty PR.
• Best-effort means implement + flag, never fabricate. Every guess goes in the Assumptions section. Never invent a Raven result or claim a build/compile passed if it didn't.
• Keep changes minimal and scoped. Branch off fresh main in the main repo; never force-push and never commit to main directly.
• You are the PR author — do not approve or merge your own PR. Hand off to stellar-dev-skill-pr-review.
• Stay within stellar/stellar-dev-skill. stellar-docs issues belong to stellar-docs-issue-solver; reviewing existing PRs here belongs to stellar-dev-skill-pr-review.