Leanspec PR Lifecycle

leanspec-pr-lifecycle

Everything that happens after git push on a lean-spec PR. Covers spec-issue linking, CI triage, review-comment discipline, webhook subscription, and the manual ticking of Plan items / CHANGELOG entries on merge.

This is lean-spec's analogue of onsager-pr-lifecycle / duhem-pr-lifecycle. The discipline is the same.

Tool discipline

• No gh CLI for issue/PR manipulation, no hub, no direct GitHub API. Always use mcp__github__*. The gh CLI is fine for CI workflow inspection (gh run list, gh run view) — see leanspec-development "CI/CD"; it's just not the tool for spec-label updates or PR body edits.
• Scope is restricted to codervisor/leanspec for this skill.
• Don't open PRs unless the user explicitly asks. Creating one is a one-way door in this project's workflow.

Spec-issue linking (mandatory)

Every PR must either:

1. Link to a spec issue in its body via Closes #N / Fixes #N / Resolves #N (slice complete) or Part of #N / Refs #N (scaffolding), OR
2. Carry the trivial label (typo, doc-only, one-line obvious fix).

If neither, the PR is out of process. Comment on the PR asking the author to add a spec link — creating one via issue-spec if none exists — or apply the trivial label.

Which keyword to use

GitHub closes issues on merge when the PR body contains one of: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved — followed by #N.

Pick the keyword based on what this PR actually delivers:

Part of / Refs are not auto-close keywords — they just cross-link in the UI. Use them for scaffolding so the spec stays open for the real slice.

Edit the PR body via mcp__github__update_pull_request (don't open a new PR just to fix the link). Put the linking line at the top of the body.

Multi-issue PRs — enumerate every closure

If a single PR delivers acceptance for more than one issue, write one Closes keyword per issue:

Closes #27, Closes #30, Closes #33

GitHub only honors auto-close on each #N individually; Closes #27, #30, #33 closes #27 and leaves #30/#33 open.

The ## Delivers subsection

For Part of #N PRs (and ideally all PRs), include a ## Delivers subsection in the body listing the exact Plan items this PR ticks. Copy the item text verbatim from the spec's ## Plan, but mark each as - [x]. Use this list to tick the parent spec's checkboxes after merge — see "Issue progress" below.

Example PR body:

Closes #142

## Delivers
- [x] Implement `GithubProvider::list_specs` in `rust/leanspec-core/src/providers/github.rs`
- [x] Add `--provider=github` flag to `leanspec init`
- [x] Update `locales/en.json` and `locales/zh-CN.json` with provider-picker copy

## Provider impact
- Types added: `ProviderKind::Github`, `GithubProviderConfig`
- Trait changes: none (implements existing `Provider` trait)
- Breaking change? no

## Summary
First slice of the github provider. List-only; CRUD lands in a follow-up.

## Provider impact in the PR body

If the linked spec is labeled provider-impact, the PR body must include a ## Provider impact subsection (it's fine to copy the spec's own subsection verbatim). This makes provider changes visible in the PR diff itself, not just on the linked issue, so reviewers don't have to context-switch.

If Breaking change? yes, the PR must also touch CHANGELOG.md under the next [Unreleased] heading. Comment on the PR if either is missing.

Issue progress

Spec issues use only their open/closed state — no status labels. Lifecycle moves:

• PR merged with Closes #N → issue auto-closes (GitHub).
• PR merged with Part of #N → spec stays open; tick the delivered Plan items on the parent manually (see below).
• PR closed unmerged → spec issue stays open as-is.

When a PR is merged with Part of #N (parent stays open):

1. Read the merged PR's ## Delivers subsection.
2. For each item, find the matching - [ ] line in the parent spec's ## Plan section and flip it to - [x].
3. Edit the spec body via mcp__github__issue_write.

When a PR is merged with Closes #N:

1. GitHub auto-closes the spec.
2. If the spec is part of a tracker (umbrella) issue, see the "Tracker refresh" section below.
3. If the spec was labeled provider-impact with Breaking change? yes, confirm a CHANGELOG entry landed; if not, file a follow-up PR adding it.

Tracker refresh

Some issues are umbrella trackers that reference several sub-issues as a checklist — identified by a [Tracking] title prefix, a tracking label, or a ## Progress section whose items are - [ ] #N lines. When a PR closes a sub-issue, the tracker does not update itself.

After merge, for each auto-closed or explicitly-closed issue:

1. Search for umbrella trackers that reference it: mcp__github__search_issues with repo:codervisor/leanspec #N in:body is:issue is:open.
2. For each match, read the tracker body. If there's a matching - [ ] ... #N ... line in a Progress / Plan section, flip it to - [x].
3. Post one tracker comment summarizing the delta, not one per issue: "PR #<pr> landed #N1, #N2, #N3; ticked in Progress."
4. If after the tick every sub-issue is closed, note that the tracker itself is now a candidate for closure — don't close it unilaterally, just flag it.

CI triage

CI on this repo runs from .github/workflows/. The relevant workflows are listed in leanspec-development "CI/CD"; the patterns below are what fails most often: