Release Completion Checklist: 9 Mandatory Items Before Claiming Task Done

Before claiming a release task complete in the reverse-skill repository, you must execute all nine verification items defined in docs/RELEASE-CHECKLIST.md, including changelog updates, version tagging, CI validation, and metadata synchronization across bootstrap manifests and routing configurations.

The reverse-skill project enforces a strict protocol to ensure semantic versioning accuracy and documentation consistency before any release can be declared finished. Every completion checklist item is codified in the source-controlled docs/RELEASE-CHECKLIST.md file, with specific line references dictating exactly what constitutes "done." This guide breaks down the nine mandatory items with the exact file paths and automation commands required to satisfy the repository's release verification gate.

Documentation and Version Updates (Items 1–4)

Verify CHANGELOG.md Categories

According to line 7 of docs/RELEASE-CHECKLIST.md, you must verify that CHANGELOG.md contains a complete Unreleased section with entries categorized under Added, Fixed, Security, and Removed. Missing categories will block the release.

Convert to Versioned Heading

As specified at line 8, transform the ## [Unreleased] heading into a versioned format: ## [x.y.z] — YYYY-MM-DD. You must also update the compare link in the changelog, replacing ...HEAD with the new tag reference to ensure proper diff generation.

Synchronize the VERSION File

Line 9 mandates updating the VERSION file at the repository root to match the new x.y.z release number. This single-source string is consumed by CI pipelines for artifact naming and version validation.

Create Milestone Release Notes

Per line 10, you must add a dedicated release note file at docs/RELEASE_NOTES_v<x.y.z>.md (for example, docs/RELEASE_NOTES_v1.0.0.md). This file hosts detailed migration guides and breaking change announcements.

Git Tagging and Continuous Integration (Items 5–6)

Tag and Push the Release

Line 11 requires creating an annotated Git tag matching the version string (git tag v<x.y.z>) and explicitly pushing it to the remote repository with git push --tags. This action triggers the automated release pipeline and version verification jobs.

Validate All CI Jobs

Before claiming task done, line 12 stipulates that all CI jobs must report green status. Specifically verify that the routing baseline, coherence checks, pin-gate validation, and version-check jobs complete successfully.

Metadata Synchronization (Items 7–9)

Bootstrap Capability Sync

If bootstrap capabilities changed during the release cycle, lines 16–18 require synchronizing the ability list across three files: RULES.md, RULES_zh.md, and skills/SKILL.md. The source of truth for this data is skills/scripts/bootstrap-manifest.json; edits must flow from this JSON file to the markdown documents.

Field-Journal Index Updates

When adding new field-journal entries, line 17 mandates updating skills/field-journal/_index.md in three specific places: the category listing, the high-frequency pattern section, and the entity inverted index.

Routing Rule Configuration

For routing rule modifications, line 18 specifies that you must edit only skills/config/routing.json. Generated documentation must stay in sync with this file, but manual edits to derived docs are prohibited and will fail the routing baseline check.

Automated Execution Commands

The following bash commands automate the core completion checklist items:

# 1️⃣ Update CHANGELOG and VERSION

sed -i "s/## \[Unreleased\]/## [1.2.3] — $(date +%Y-%m-%d)/" CHANGELOG.md

sed -i "s/...HEAD/...v1.2.3/g" CHANGELOG.md
echo "1.2.3" > VERSION

# 2️⃣ Create release notes from template

cp docs/RELEASE_NOTES_template.md docs/RELEASE_NOTES_v1.2.3.md

# 3️⃣ Commit, tag, and push

git add CHANGELOG.md VERSION docs/RELEASE_NOTES_v1.2.3.md
git commit -m "Release v1.2.3"
git tag v1.2.3
git push --tags

# 4️⃣ Verify CI status (check GitHub Actions)

# Ensure: routing baseline, coherence, pin-gate, version-check are green

Summary

• The docs/RELEASE-CHECKLIST.md file defines nine mandatory completion checklist items that must be satisfied before claiming a release task done.
• Documentation updates include finalizing CHANGELOG.md categories, converting the Unreleased heading to a versioned format, updating the VERSION file, and creating docs/RELEASE_NOTES_v<x.y.z>.md.
• Git operations require tagging the commit with git tag v<x.y.z> and pushing tags to trigger the CI validation suite.
• CI verification must confirm green status for routing baseline, coherence, pin-gate, and version-check jobs before proceeding.
• Metadata synchronization covers bootstrap manifests (skills/scripts/bootstrap-manifest.json), field-journal indices (skills/field-journal/_index.md), and routing rules (skills/config/routing.json).

Frequently Asked Questions

What happens if I skip the metadata synchronization steps?

Skipping the bootstrap, field-journal, or routing synchronization results in inconsistent documentation across RULES.md, RULES_zh.md, and skills/SKILL.md. The CI version-check job will fail if the skills/scripts/bootstrap-manifest.json source of truth does not match the generated ability lists in the markdown files.

Can I edit routing rules in multiple files?

No. According to line 18 of docs/RELEASE-CHECKLIST.md, routing rule changes must be made exclusively in skills/config/routing.json. Editing generated documentation files directly violates the protocol and will cause the routing baseline CI job to fail.

Which CI jobs must pass before I can claim the task done?

As specified at line 12, you must verify green status for four specific jobs: the routing baseline check, coherence validation, pin-gate verification, and the version-check job. All four must complete successfully before the release can be declared complete.

Where is the version number stored for CI consumption?

The repository stores the canonical version string in the VERSION file at the repository root. This file must match the Git tag and the version heading in CHANGELOG.md exactly, as it serves as the single source of truth for automated pipelines and artifact generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}