stellar-docs-issue-solver

name

stellar-docs-issue-solver

description

Work through the issues assigned to the user on the stellar/stellar-docs repo: find the open issues assigned to them, pick one (or go oldest-first), understand what it asks, create a branch, implement a best-effort docs fix following the repo's conventions, verify it, commit, and automatically open a PR that links the issue and flags any assumptions — then hand the new PR to the stellar-docs-pr-review skill for preview testing. Use whenever the user asks you to work on / solve / fix / clear the issues assigned to them on stellar-docs, "take a look at my issues," or turn a specific stellar-docs issue into a PR. This is the write-and-open-PR counterpart to stellar-docs-pr-review (which only reviews existing PRs). Do NOT use for reviewing/merging PRs (use stellar-docs-pr-review), for non-stellar-docs repos, or for issues that require a product/design decision rather than a docs change.

Solving a stellar-docs issue → PR

You turn an assigned issue on stellar/stellar-docs into an opened pull request. This is the counterpart to the stellar-docs-pr-review skill: that one reviews PRs; this one creates them. The repo is a Docusaurus v3 site (MDX content, _category_.json files, config/*.sidebar.ts) published at https://developers.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. A confidently-wrong docs change 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 cannot approve or merge your own work (branch protection needs a review from someone else). Your job ends at a well-tested, clearly-described PR.

What you need

• gh CLI authenticated with push access to stellar/stellar-docs (gh auth status).
• Git configured with the user's identity (commits are attributed to them).
• The Raven MCP (Stellar's build-on-Stellar knowledge tool) — use it extensively, on both ends of the work: to research the correct Stellar behavior before you write a word, and again to fact-check every factual line after you've drafted it. Treat Raven as the source of truth for anything about Stellar/Soroban/SDKs/CLI/network behavior. If Raven isn't connected, don't assert facts you can't verify — write only the structural/editorial part and flag the factual gap prominently in the PR.
• Node/npm if you want to build the site locally before opening (recommended for non-trivial changes; see step 4).

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-docs --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 through the list, one issue at a time — finish and report on one before starting the next.

2. Understand the issue

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

Read the body and every comment. Identify the concrete, testable outcome the issue wants. Decide honestly whether this is a docs change you can implement:

• Yes — content fix, restructure, frontmatter/pagination/sidebar change, broken link, clarification, new page from provided material. Proceed.
• No — it needs a product/design decision, depends on an unreleased feature, is a bug in code rather than docs, or is too vague even for a flagged best-effort. Don't fabricate a PR. Report it as needing a human and move on.

Also read the repo's own conventions before writing anything:

gh api repos/stellar/stellar-docs/contents/.github/copilot-instructions.md --jq '.content' | base64 -d
# also check CONTRIBUTING.md and how neighboring pages/frontmatter are structured

3. Branch

Clone (or reuse a clone) and branch off the default branch. Match the repo's naming — observed convention is <type>/<short-slug>-<issue#>, e.g. chore/fix-anchors-page-2181. Types seen: fix, chore, docs, feat.

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

4. Implement, minimally and in-convention

Make the smallest change that resolves the issue. Match the surrounding style — frontmatter keys (title, sidebar_position, pagination_next/pagination_prev), _category_.json label/position, admonitions, code-block languages, relative links. Don't reformat untouched content or drift outside the issue's scope.

Fact-check relentlessly with Raven. Before writing any factual assertion (CLI flags and defaults, SDK method/type names, endpoints, network passphrases, protocol/fee values, contract semantics, SEP details), look the answer up in Raven rather than recalling it — then, after drafting, run the finished lines back through Raven to confirm nothing drifted. The docs you write become the thing others trust, so a plausible-sounding guess is a real hazard. If Raven can't confirm something, write around it and flag it in the PR rather than guessing.

Verify before opening. For anything beyond a trivial typo, build the site so you catch broken MDX/links:

npm ci && npm run build     # Docusaurus build fails on broken links / bad MDX

If a local build isn't practical, say so in your report and lean on the CI preview build that the PR will generate (the review skill tests that).

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 (the user chose fully-auto opening):

git add -A
git commit -m "<type>: <concise summary> (closes #<ISSUE_NUMBER>)"
git push -u origin HEAD
gh pr create --repo stellar/stellar-docs --base main \
  --title "<type>: <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
<list every guess you made where the issue was underspecified — or "none">

## Testing
<what you verified locally (build passed? links ok?) and what still needs preview checking>
BODY
)"

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

6. Hand off to review, then report

You can't review your own PR, so trigger the stellar-docs-pr-review skill on the PR you just opened to run the preview-build checks (pagination, sidebar labels, breadcrumbs, parity) and post what it verified as a PR comment for the human reviewer. It will not 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) before the next issue: which issue, the branch/PR you opened, one line on the change, and anything you flagged for confirmation. State which issue you're moving to next; when none remain, say so and stop.

Report examples

Opened:

#2181 "anchors frontpage pagination" — opened PR #2661 on branch chore/fix-anchors-page-2181. Added pagination_next to the section frontmatter pointing at the Admin Guide; local build passed. No assumptions needed. Ran the review skill — preview verified, left a comment for a second reviewer. Next: #2205.

Couldn't solve:

#2205 "rethink the SDK landing page IA" — skipped, no PR. This needs an information-architecture decision (which SDKs lead, how to group them) that I shouldn't guess at. Flagging for you. Next: #2210.

Guardrails

• Only open a PR when there's a real, verified docs 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 PR's "Assumptions" section. Never invent a Raven result or claim a build passed if it didn't.
• Keep changes minimal and scoped to the issue. Branch off fresh main; 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 review.
• Stay within stellar/stellar-docs. Reviewing/merging existing PRs is the stellar-docs-pr-review skill's job, not this one.