@oevery/rsp 2.0.4 → 3.1.0-beta.0

package/skills/rsp-address-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: rsp-address-review
+description: Resolve one fixed rsp-review report for an RSP-tracked change. Use when the user authorizes disposition of review findings, bounded fixes for accepted findings, fresh verification, re-review, or a recoverable artifact-scoped handoff; keep the reviewer report-only and never infer Git or publication authority.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.1"
+---
+
+# RSP Address Review
+
+Resolve one fixed review report without changing what the reviewer observed. Treat resolution as a bounded correction pass, not a retry loop or a second project lifecycle.
+
+Render headings, field labels, explanations, and conclusion prose in the language explicitly requested by the user; otherwise follow nearest project instructions, then the conversation language. Treat report and handoff shapes as semantic field order rather than fixed English wording: translate their human-facing labels when the output language differs. Preserve paths, commands, identifiers, WorkRefs, FindingRefs, severity labels, and the dispositions `accepted`, `rejected`, and `needs-clarification` unchanged.
+
+## Fix scope and authority
+
+Require the review report, its fixed comparison or file set, the selected Change and sibling Group Brief when applicable, relevant project authority, and explicit permission for any proposed mutation. Read the current worktree and the smallest behavior chain needed to verify each Finding. Preserve unrelated modified, staged, and untracked work.
+
+Identify a Finding by its report order plus severity, title, and location. Stop if the report, comparison, Change, or Finding identity is missing or conflicting. A report grants investigation only: correction, verification, re-review, Git delivery, publication, deployment, approval, and external actions retain their own authority. Never infer Git or publication authority.
+
+## Disposition every finding
+
+Assign exactly one disposition and concise evidence to every input Finding:
+
+- `accepted`: current production or document evidence confirms the issue, the intended correction is authoritative, and the fix is inside the selected Change and mutation authority;
+- `rejected`: direct evidence disproves the issue or shows that its suggested action is not required by the selected authority; record the evidence and do not edit for it;
+- `needs-clarification`: an owner decision, authoritative requirement, reproducible trigger, or safe scope is missing; name the required input and do not edit for it.
+
+Do not accept feedback for politeness, reject it from intuition, or silently reinterpret an ambiguous Finding. When one correction covers multiple accepted Findings, retain each disposition and point them to the shared fix.
+
+## Fix accepted findings
+
+In one resolution pass, implement the smallest complete correction for accepted Findings only. Add or adjust focused tests when the corrected behavior or failure contract requires them. Do not modify `rsp-review`, the original report, or unrelated findings to make the result appear clean.
+
+After the last relevant edit, run fresh verification for the affected behavior and the selected Change. A failed, unavailable, stale, or omitted check cannot close an accepted Finding. If a check exposes another defect, return it as evidence; do not begin an automatic retry loop.
+
+Require a fresh fixed-scope re-review before claiming resolution. Return a re-review request containing the original comparison, selected authority, post-fix file set or immutable comparison, implementation summary, dispositions, and verification evidence. The re-review remains report-only. On resume with its report, correlate original Findings as resolved or remaining and treat any new Finding as unresolved input for a later authorized pass.
+
+## Handoff and recovery
+
+When work stops before a clean re-review, return Core's compact artifact-scoped continuation with review state embedded in the shared fields:
+
+```md
+## <localized Review Resolution Handoff heading>
+- <localized WorkRef label>: <selected Change>
+- <localized Authority label>: <project, Change, fixed report, and comparison pointers>
+- <localized Current state label>: <review input, FindingRef dispositions, and re-review status>
+- <localized Changed artifacts label>: <reviewed and changed paths, or none>
+- <localized Fresh verification label>: <command and result, or pending reason>
+- <localized Blockers label>: <unresolved FindingRefs and required owner input, or none>
+- <localized Next action label>: <smallest bounded action and owner>
+```
+
+The handoff contains authoritative pointers, not project truth. Return it in the response unless the user explicitly authorizes a path; never create a hidden receipt or persistent run state. It is not durable truth or a second state store. Exclude secrets, full logs, and duplicated Change text.
+
+To recover, reopen every authority pointer, confirm the WorkRef and comparison still identify the intended scope, inspect current worktree drift, and revalidate claimed verification. Mark stale evidence pending instead of trusting the handoff. Continue only the named pass; host threads, agents, hooks, or proprietary resume features are optional and never required.
+
+## Return ownership
+
+Report the disposition table, changed artifacts, preserved unrelated work, fresh verification, re-review status, and the handoff when anything remains. Resolution is complete only when every Finding has a supported disposition, every accepted Finding has a verified correction, the fresh fixed-scope re-review is clean, and no `needs-clarification` input remains. Never claim archive, commit, push, publication, deployment, or approval.

package/skills/rsp-design/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rsp-design
+description: Resolve one material domain-model, module/seam, or evidence-seeking design question for an explicit or unambiguously focused RSP Change without implementing production behavior or writing durable project truth.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.2"
+---
+
+# RSP Design
+
+Resolve one design question and return the result to its existing RSP owner. Do not implement the result.
+
+## Establish the question and authority
+
+Require an explicit WorkRef or exactly one unambiguous focus marker. Read the nearest project instructions and context, the RSP core Skill or fallback protocol, the selected Change and sibling Group Brief, then the smallest relevant Specs, decisions, code, tests, callers, and runtime evidence.
+
+State the single material question before analysis. If the WorkRef, question, required evidence, owner intent, or mutation authority is missing or ambiguous, stop with the smallest blocker. Never invent product intent.
+
+## Load one design mode
+
+Load only the reference matching the question:
+
+- Read [domain modeling](references/domain-modeling.md) for vocabulary, identity, lifecycle, invariants, relationships, or ownership.
+- Read [module and seam design](references/module-seams.md) for interface obligations, caller complexity, adapters, test surfaces, or seam placement.
+- Read [reversible exploration](references/reversible-exploration.md) only when a material conclusion depends on unobserved behavior and a cheap safe probe can provide it.
+
+Keep evidence-driven conclusions separate from choices only the owner can make. Compare at least one credible alternative when alternatives exist; do not manufacture options for a conclusion forced by evidence or authority.
+
+## Preserve artifact ownership
+
+Default to report-only. When the user or project explicitly authorizes updating the selected Change, write settled planned design only under its `Design` section. Do not write Specs, Decision Records, `CONTEXT.md`, `AGENTS.md`, production code, lifecycle state, focus, archives, or Git state. Identify possible durable current facts or rationale only as artifact-routing candidates for the Core durable review.
+
+An exploration additionally requires explicit disposable-code authority and the cleanup contract in its reference. A design request alone grants neither production mutation nor external side-effect authority.
+
+## Return the bounded result
+
+Follow Core's response-versus-artifact language boundary: use the requested language for natural prose, while any authorized `Design` update follows the selected Change's language and canonical headings. Do not use a technical token alone as a response label; retain it only in parentheses after a localized label. Return these semantic fields:
+
+- selected WorkRef and exact question;
+- inspected evidence and material gaps;
+- recommendation and evidence-driven reasoning;
+- credible alternatives and tradeoffs;
+- unresolved owner decisions;
+- artifact routing and any authorized Change update;
+- smallest next action.
+
+Return to Shape or the user against the same WorkRef. Do not create parallel state, recursively invoke another Skill, implement, review, archive, stage, commit, push, publish, deploy, or approve.

package/skills/rsp-design/references/domain-modeling.md

@@ -0,0 +1,11 @@
+# Domain modeling
+
+Use this procedure only for a question about domain language, identity, lifecycle, invariants, relationships, or ownership.
+
+1. Collect the project's existing terms from its authoritative context, Specs, code, tests, and user language. Record contradictions rather than silently choosing one source.
+2. Trace concrete scenarios across creation, transition, failure, cancellation, deletion, and relevant scope boundaries. Prefer observable lifecycle evidence over type names alone.
+3. Identify each concept's identity, owner, allowed transitions, invariants, and relationships. Distinguish a domain concept from a transport shape, persistence record, UI label, or implementation helper.
+4. Propose the smallest coherent vocabulary and ownership model that explains the evidence. Test it against at least one edge case and one existing production consumer.
+5. Separate conclusions forced by evidence from product choices that require owner confirmation.
+
+Return canonical terms, definitions, ownership and lifecycle implications, conflicts with current usage, alternatives, and unresolved owner decisions. Planned vocabulary may update only the authorized selected Change `Design`; flag possible current-fact or rationale destinations without writing them.

package/skills/rsp-design/references/module-seams.md

@@ -0,0 +1,11 @@
+# Module and seam design
+
+Use this procedure only for a question about an interface, caller complexity, adapter, test surface, or seam placement.
+
+1. Trace the direct production consumer and the smallest complete call/data path before proposing a seam. Confirm the live path reaches the candidate owner.
+2. List what callers must know: inputs, outputs, invariants, ordering, failures, configuration, cancellation, and relevant performance constraints.
+3. Locate where behavior or policy actually varies. Do not add an interface for hypothetical variation or wrap an existing pass-through for symmetry.
+4. Compare credible placements by caller leverage, implementation locality, dependency direction, state ownership, and whether callers and tests can use the same public surface.
+5. Recommend the smallest interface that hides meaningful complexity while preserving domain ownership. State migration or compatibility consequences without implementing them.
+
+Return the proposed owner, seam, interface obligations, affected consumers, verification surface, alternatives, and unresolved owner decisions. Treat code sketches as explanatory output only; do not write production code.

package/skills/rsp-design/references/reversible-exploration.md

@@ -0,0 +1,19 @@
+# Reversible exploration
+
+Use this procedure only when a material design conclusion depends on behavior that available code, tests, documentation, or runtime evidence does not establish.
+
+## Define the probe
+
+- State one question, falsifiable hypothesis, observation, and stop condition.
+- Prefer inspection or an existing focused command. Create code only when that cheaper evidence cannot answer the question.
+- Require explicit authority for disposable mutations and any runtime or external side effect. Otherwise describe the probe and return the authority blocker.
+
+## Isolate and clean up
+
+- Keep disposable code outside production owners and name it clearly as temporary. Do not change public interfaces, migrations, persistent data, credentials, or delivery state.
+- Record the pre-probe file state and exact cleanup target. Avoid the probe when unrelated work makes safe cleanup uncertain.
+- Run only the minimum observation, capture the evidence, then remove every disposable artifact before returning. Verify cleanup without discarding unrelated work.
+
+## Return evidence, not architecture
+
+Report the hypothesis, method, observation, confidence and limitations, cleanup evidence, design implication, and remaining owner decision. A probe can support a recommendation; it is never durable architecture or permission to implement production behavior.

package/skills/rsp-diagnose/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: rsp-diagnose
+description: Diagnose one selected RSP Change when a reproducible or materially evidenced failure has an unexplained cause or owning layer. Use for conflicting, intermittent, or multi-layer symptoms before production correction.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.1"
+---
+
+# RSP Diagnose
+
+Establish a confirmed cause before correction. Keep the selected Change as owner and return investigation evidence to it.
+
+Follow Core's response-versus-artifact language boundary.
+
+## Establish bounds
+
+Resolve exactly one executable open Change from an explicit work reference or unambiguous focus. Read the user request, nearest project instructions, relevant context, RSP rules, the sibling Group Brief when present, the selected Change, and only the code, tests, logs, configuration, and worktree evidence needed to investigate.
+
+A diagnosis request grants read-only investigation and safe diagnostic command execution. Editing tests, instrumentation, fixtures, or the Change requires explicit mutation authority. Production correction is outside this Skill even when separate fix authority exists.
+
+Stop with one evidence request when the target, expected behavior, investigation scope, or safe reproduction conditions are unclear.
+
+## Diagnose
+
+1. **REPRODUCE.** Capture the smallest command or observation that exposes the symptom, its expected and actual result, and relevant conditions. When reproduction is unsafe or unavailable, label the supplied evidence and its limits. Continue only with a stable symptom or material evidence.
+2. **LOCATE.** Trace the live path to the first boundary where actual behavior diverges from expected behavior. Identify the affected layer and owner; verify that any suspected adapter, validator, cache, or wrapper is reached by the production consumer.
+3. **HYPOTHESIZE.** State the smallest set of live competing causes and the distinct observation each predicts. A single hypothesis is sufficient only when existing evidence already excludes credible alternatives.
+4. **DISCRIMINATE.** Run the smallest safe check that separates the leading hypotheses. Record the exact command or observation and decisive result. Prefer one discriminating check over broad speculative changes.
+5. **CONFIRM.** Confirm a cause only when observed evidence selects it over the remaining live alternatives and explains the reproduced symptom. Otherwise return `unresolved` with the missing evidence and one bounded next check.
+
+## Return evidence
+
+Return:
+
+- selected Change;
+- result: `confirmed` or `unresolved`;
+- reproduction or supplied-evidence limit;
+- cause and affected owner, or remaining hypotheses;
+- decisive evidence and impact boundary;
+- investigation mutations, if explicitly authorized;
+- exactly one next action.
+
+For `confirmed`, name one correction entrypoint owned by the same Change; do not apply it. For `unresolved`, name the next discriminating check or blocker. Update that Change's Tasks, Verify, or Blockers only with authority and observed facts. Preserve unrelated work and never infer Git, delivery, publication, or approval authority.
+
+When correction, further discrimination, or other work remains, use Core's compact continuation fields in order: `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, and `Next action`. Put the result, reproduction limit, cause or hypotheses, decisive evidence, and impact boundary in `Current state`; put authorized investigation mutations in `Changed artifacts`. Reopen authority pointers, inspect drift, and refresh decisive evidence before resuming. This response is not durable truth or a second state store; persist it only with explicit path authority.

package/skills/rsp-implement/NOTICE.md

@@ -0,0 +1,27 @@
+# Third-party notice
+
+The fresh-verification discipline in this Skill adapts concepts from
+`obra/superpowers`, revision `d884ae04edebef577e82ff7c4e143debd0bbec99`,
+`skills/verification-before-completion/SKILL.md`.
+
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/rsp-implement/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: rsp-implement
+description: Implement exactly one selected, ready RSP Change within explicit mutation authority. Use when the user asks to implement or fix tracked work and requires code/tests plus truthful Tasks, Blockers, and fresh verification evidence; never infer Git, publication, review, TDD, or diagnosis authority.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.24.1"
+---
+
+# RSP Implement
+
+Implement one selected Change and return facts.
+
+## Select and inspect
+
+Require an explicit WorkRef or one unambiguous focus marker. A Group Brief is context, not executable work. Stop when selection, readiness, product authority, acceptance, or required decisions are unresolved.
+
+Read nearest instructions, Core or fallback, Change and Brief, relevant Specs and decisions, worktree, then the smallest owning code/test chain. Use normal repository discovery; do not guess owners.
+
+## Preserve authority
+
+Identify outcome, owners, verification, and pre-existing work. Modify only Change requirements, Tasks, Verify, and Blockers. Preserve unrelated modified, staged, and untracked work. Stop when overlap would discard, guess, or rewrite pre-existing intent.
+
+Git delivery, publication, deployment, approval, and out-of-scope deletion require separate explicit authority. For conflicts, inspect base/ours/theirs, preserve unrelated work, resolve only evidenced scope, rerun checks, and stop before staging, continuing, aborting, or committing. Verify named findings first.
+
+## Classify implementation evidence
+
+Classify evidence before mutation and after failure:
+
+- An unexplained failure returns `rsp-diagnose` when available; otherwise return Core's manual diagnosis fallback.
+- Return `rsp-tdd` only when test-first work is explicitly required by the user, selected Change, or project instructions, or a concrete changed risk makes pre-mutation RED materially safer; use Core's manual TDD fallback when unavailable. Behavior being testable, a test being possible, or the work being a fix is not sufficient by itself.
+- Continue ordinary implementation by default when diagnosis does not apply, the required behavior, cause, or edit is sufficiently evidenced, and no explicit or concrete-risk TDD gate is met.
+
+Diagnosis precedes TDD. Do not invoke another Skill from inside this Skill. If evidence changes the route, stop mutation and return the next action, evidence, and same selected Change. Do not reproduce either discipline inside Implement or invoke review or delivery.
+
+## Implement and verify
+
+Implement the smallest complete slice. Update Tasks after outcomes exist; keep unresolved issues in Blockers.
+
+After final mutation, run required Change checks and narrower risk checks. Fresh verification is required, but a new test is only one evidence option; prefer the cheapest decisive existing test, static check, build, or acceptance evidence. Record command, scope, result, and omissions. Prior runs are stale; failed or unavailable verification cannot support completion. Rerun after relevant edits.
+
+Keep a new test only when it protects observable behavior or a real boundary, adds distinct future confidence, avoids duplicate or implementation-detail coverage, and has proportionate maintenance cost. Otherwise remove the disposable test, fixture, and helper before completion, then use smallest sufficient final evidence. User, Change, and project retention requirements remain authoritative.
+
+Record concise fresh evidence when Change Verify owns it. Do not create a receipt store or mandate one shell wrapper.
+
+## Return ownership
+
+Report whether the Change is completed, partial, blocked before implementation, verification-failed, verification-unavailable, or verification-blocked. Use failed for an exercised defect; use unavailable when a missing tool, dependency, service, credential, or environment prevents execution. Use blocked only when scoped checks pass but a required gate fails solely from a confirmed pre-existing or out-of-scope baseline defect; never waive affected gates.
+
+When work remains, follow Core's response-versus-artifact language boundary and return `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, and `Next action`. They are not durable truth; persistence requires explicit path authority.
+
+Claim completion only when required Tasks and checks pass and no blocker remains. Do not claim review, archive, Git delivery, or release unless separately performed with explicit authority.

package/skills/rsp-manage/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: rsp-manage
+description: Continue one explicitly requested focused RSP Change through genuinely independent bounded slices or interruption recovery while keeping ordinary work on existing Core and Discipline paths.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.24.1"
+---
+
+# RSP Manage
+
+Manage one focused Change only after the user explicitly requests managed continuation. Keep RSP artifacts as durable truth and process data transient.
+
+## Qualify before mutation
+
+Require one focused, ready Change and sufficient mutation authority. Snapshot the user authority, nearest instructions and context, Group Brief when present, Change, relevant Specs and Decisions, current RSP status, and worktree once.
+
+Activate only for at least two non-overlapping mutation scopes with independent verification, genuinely long authorized continuation, or interruption recovery whose stale-evidence cost justifies orchestration. A small single slice, tightly coupled scopes, or host worker availability alone is ineligible. On decline, make no mutation, create no dispatch envelope, receipt, budget, or controller state, and return the exact Core or Discipline next action without executing it.
+
+Identify allowed mutations, required verification, unavailable acceptance, and lifecycle, Git, publication, deployment, approval, or other external-action boundaries. Preserve unrelated work. Unless the user sets a tighter limit, allow at most four worker dispatches and one corrective retry for the whole run.
+
+## Dispatch only real work
+
+Send an internal compact envelope only to a worker that will execute an eligible slice:
+
+```md
+- WorkRef: <focused Change>
+- Objective: <one observable slice>
+- Authority: <exact inputs and allowed mutations>
+- Return: <changed artifacts, decisive verification, omissions, and stop boundary>
+```
+
+Parallelize only non-overlapping mutation scopes with independent verification. Keep overlapping mutations and dependent verification sequential. Workers receive no implied focus, lifecycle, durable-write, Git, publication, deployment, approval, or cleanup authority.
+
+For each slice choose the cheapest decisive focused check. Run at most one broader integration gate, and only when combined mutations create integration risk or project authority requires it. Do not multiply checks per worker or retain disposable process tests.
+
+## Continue from current evidence
+
+After each return inspect the actual diff and freshly observed verification. Accept a slice only when the owned output exists, decisive checks pass, omissions are named, and the Change still owns the result. Continue only after positive progress.
+
+Use the one corrective retry only when new evidence identifies an in-scope correction. Otherwise stop at the failure. Inspect current worktree and evidence after returns, but reread stable authority only during interruption recovery or when evidenced authority or worktree drift could invalidate the snapshot.
+
+Treat handoffs as transient pointers, never project truth. During recovery, reread current authority and referenced evidence, return changed or unverifiable completion to pending, and enforce the remaining finite limits. Never create durable controller status, retry graphs, receipts, or parallel lifecycle state.
+
+## Preserve artifact and authority boundaries
+
+Keep dispatch details, retry history, limits, and process chronology out of Changes, Specs, Decision Records, and the user-facing final result. Update the selected Change only with converged requirements, completed outcomes, decisive evidence, omissions, and real blockers. Durable facts and rationale still use Core's normal artifact-routing decision.
+
+Treat archive guidance as advisory unless the run has explicit lifecycle-closeout authority and Core has completed its durable decision. Archive never grants Git or publication authority.
+
+Stop at an unresolved owner decision, unavailable service, credential, device, environment, or human acceptance; missing external-action authority; verification without an evidenced in-scope correction; drift; or exhausted limits. Do not route around the boundary.
+
+Return only completed and pending slices, fresh verification, omissions, the real boundary owner, and one next action. Do not expose dispatch, retry, or budget chronology and do not claim archive, Git, publication, deployment, approval, or human acceptance that was not completed under explicit authority.

package/skills/rsp-release-docs/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: rsp-release-docs
+description: Prepare and audit evidence-based changelogs, release notes, and migration notes. Use when drafting or updating release documentation, reviewing an Unreleased section, summarizing a version range, deciding references or omissions, or checking that release prose matches shipped behavior and repository conventions.
+license: MIT
+metadata:
+  author: oevery
+  version: "2026.07.22.1"
+---
+
+# RSP Release Docs
+
+Build one release evidence ledger, then project it into the repository's release surfaces. Treat Git history as navigation, not product truth.
+
+## Establish authority
+
+Resolve requirements in this order:
+
+1. Follow the user's explicit scope, audience, language, format, reference, and mutation requirements.
+2. Follow the applicable instruction hierarchy; nearer project instructions override broader host or personal defaults.
+3. Follow existing release-tool configuration.
+4. Preserve the target artifact's current structure, terminology, and language.
+5. Match prior published releases and tag, link, and tracker conventions.
+6. Apply the defaults in this Skill only where the repository is silent.
+
+Use the higher-precedence source when two sources conflict. Ask one focused question only when the unresolved choice would materially change the public result. Read [convention discovery](references/convention-discovery.md) when locating or reconciling repository and personal conventions. Persist a preference only when the user explicitly authorizes its project or personal instruction owner.
+
+Completion criterion: name the release range, target version or draft state, audience, output surfaces, language, link style, and allowed mutations from observed authority.
+
+## Select the branch
+
+- **Audit:** inspect existing release prose and return findings without editing.
+- **Prepare:** draft requested artifacts; for a formal release, always include release notes. Update a changelog only when the repository owns one or the user requests one. Include migration guidance whenever users must act.
+- **Finalize:** replace Unreleased markers, dates, comparison links, or draft labels only when the release identity is confirmed.
+
+Publication is a separate branch. Preparing prose never grants commit, tag, push, release creation, registry publication, deployment, deletion, or approval authority.
+
+Completion criterion: every requested surface has one disposition: draft, update, audit only, not applicable, or blocked by a named decision.
+
+## Collect evidence
+
+Inspect the smallest sufficient set:
+
+- previous release tag or user-supplied base and the target ref;
+- commits and net diff in the release range;
+- PRs, issues, tracked Changes, changesets, news fragments, and release PRs when available;
+- public API, CLI, configuration, packaging, migration, security, and operator-facing changes;
+- existing changelog, prior release notes, migration guides, version files, and release configuration;
+- fresh verification and known acceptance gaps when the release claims compatibility or readiness; label archived evidence with its observed revision or date instead of presenting it as current.
+
+Use diffs and direct consumers to verify behavior. Use commit messages and labels to locate intent. Prefer accepted work artifacts and public documentation for business meaning. Reconcile disagreements explicitly instead of choosing the most convenient source.
+
+Completion criterion: every commit and every relevant tracked item in the range is represented by evidence or has an explicit exclusion reason.
+
+## Build the release ledger
+
+Create a working ledger before writing prose. Keep it in the response or temporary work unless the repository already owns release fragments or the user authorizes a path.
+
+For each net change record:
+
+- evidence identifiers and links;
+- user-visible or operator-visible outcome;
+- affected audience;
+- breaking, deprecation, security, compatibility, or migration impact;
+- changelog disposition;
+- release-note disposition;
+- reference choice;
+- exclusion or uncertainty, if any.
+
+Collapse multiple commits into one outcome. Omit changes added and reverted within the same range. Fold fixes to never-released behavior into the final feature description. Keep internal work out unless it changes public behavior, packaging, compatibility, security, operations, or release integrity.
+
+Completion criterion: the ledger describes the net released state rather than commit chronology, and every exclusion is intentional.
+
+## Project the artifacts
+
+Read [output contracts](references/output-contracts.md) before creating a new format, preparing a major or breaking release, or producing more than one surface.
+
+### Changelog
+
+Write a concise cumulative record of notable outcomes. Preserve existing categories; otherwise use Keep a Changelog categories and omit empty sections. Put breaking changes and required action first. Describe behavior, not implementation mechanics.
+
+### Release notes
+
+Write a release-specific narrative for the observed audience. Lead with the most important outcomes, make required action prominent, include compatibility or known limitations when evidenced, and link to the full changelog or comparison range. Do not merely duplicate the changelog.
+
+### Migration notes
+
+State who is affected, required actions in order, changed defaults or removed surfaces, compatibility window, validation steps, and rollback or support path when known. Use a separate guide when the instructions would overwhelm the release notes.
+
+Completion criterion: every statement maps to the ledger, each surface serves its distinct audience and lifetime, and terminology remains consistent across surfaces.
+
+## Apply reference policy
+
+Follow repository policy first. Otherwise:
+
+1. Add a version-level compare or tag link.
+2. Prefer PR links for implementation context.
+3. Prefer issue or tracked-work links for rationale and migration context.
+4. Use commit links when no better semantic anchor exists, exact provenance matters, or the user requires them.
+
+Do not force a reference onto every bullet. Use stable public links only; keep private tracker identifiers out of public prose unless the repository already exposes them.
+
+Completion criterion: references add useful context without turning the artifact into a Git log or exposing private information.
+
+## Audit before returning
+
+Check all of the following:
+
+- range and version identity are consistent across artifacts;
+- every ledger item is included or intentionally excluded;
+- no claim exceeds implementation or verification evidence;
+- verification counts, package identities, and compatibility claims name their observed revision or date when they were not refreshed in the current run;
+- breaking, migration, deprecation, security, and known-limit information is prominent where applicable;
+- user-visible net outcomes are not fragmented by commit;
+- links, dates, headings, language, and terminology match observed conventions;
+- changelog and release notes agree without becoming copies;
+- working-tree edits stay within authorized files.
+
+Return the release range, artifacts drafted or changed, coverage and exclusions, unresolved decisions, validation performed, and whether any external release action occurred.
+
+Completion criterion: the result is evidence-complete, convention-compatible, and truthful about omissions and publication state.

package/skills/rsp-release-docs/references/convention-discovery.md

@@ -0,0 +1,65 @@
+# Convention discovery
+
+Use this reference when a repository may have personal, project, tool, or historical release conventions. Discover; do not introduce a new configuration file merely to satisfy this Skill.
+
+## Authority sources
+
+Inspect only relevant, non-secret sources:
+
+1. Current user instructions, including requested audience, language, tone, links, output paths, and whether edits are allowed.
+2. Applicable instructions, with the nearest project instruction winning over broader host or personal defaults.
+3. Project release documents such as `CONTRIBUTING.md`, maintainer guides, or a documented release checklist.
+4. Existing target artifacts such as `CHANGELOG.md`, `NEWS.md`, release-note templates, upgrade guides, or an in-app What's New source.
+5. Release configuration and package scripts.
+6. Recent published releases and tags.
+
+Do not scan unrelated home-directory configuration. Do not print tokens, registry credentials, private URLs, authorization headers, or hidden release secrets. When a named config may contain secrets, inspect only the keys needed to identify release behavior. Keep a newly stated preference session-local unless the user explicitly authorizes an existing project or personal instruction owner.
+
+## Common configuration signals
+
+Look for these only when present or relevant:
+
+- `.github/release.yml`, Release Drafter, or GitHub Release templates;
+- release-please manifest/configuration;
+- `.changeset/config.json` and changeset fragments;
+- Towncrier, Changie, or similar news fragments;
+- `cliff.toml`, conventional-changelog, semantic-release, or commit-and-tag-version configuration;
+- monorepo package boundaries and per-package changelogs;
+- package scripts, CI release workflows, and version files;
+- tracker labels such as breaking, feature, fix, skip-changelog, or security.
+
+Treat generated release notes and automation output as evidence inventories. Human-facing claims still require semantic review.
+
+## Adaptation decisions
+
+Resolve these dimensions independently:
+
+| Dimension | Evidence to prefer |
+| --- | --- |
+| Audience | Explicit request, established release surface, prior releases |
+| Language | Explicit request, nearest project instruction, target artifact, prior published releases, conversation |
+| Voice | Existing artifact and product terminology |
+| Categories | Existing artifact/config; Keep a Changelog only as fallback |
+| Version and tags | Confirmed target, manifests, release config, prior tags |
+| References | Existing links and tracker policy; generic hierarchy only as fallback |
+| Output paths | Existing release owner or explicit path authority |
+| Detail | Audience needs, release risk, and existing cadence |
+
+Personal preferences refine the project format where compatible. Project-owned parsers, schemas, and release contracts win when a stylistic preference would break them. Report the conflict when the user must choose.
+
+For language specifically, apply the table order without reordering it: an explicit surface-specific request wins; otherwise follow the nearest project instruction, then that target artifact's established language, then prior published releases, and finally the conversation language.
+
+## Repository shapes
+
+- **Library or SDK:** emphasize public API, compatibility, deprecation, migration, runtime support, and precise references.
+- **Application:** emphasize visible workflows, changed defaults, operator action, rollout, and known limitations.
+- **CLI:** emphasize command/flag/config semantics, output contracts, migration, and shell compatibility.
+- **Monorepo:** determine the released unit before collecting evidence; avoid mixing unrelated packages.
+- **GitHub-Releases-only project:** draft release notes without creating `CHANGELOG.md` unless requested.
+- **Fragment-based project:** use accepted fragments as semantic evidence, then verify the net diff and release boundary.
+
+## Conflict examples
+
+- If the user requests Chinese release notes but `CHANGELOG.md` is consistently English, keep the changelog English and draft the release notes in Chinese unless the user explicitly asks to translate both.
+- If the user requests commit IDs but prior releases use PR links, preserve PR links and add commit links only for exact provenance unless the user explicitly overrides the project style.
+- If a tool requires two synchronized formats, update both from one ledger while preserving each parser's syntax.