fix(merge-retrospective): clarify stub update+close path for a zero-repair cycle

[tvna]

Summary

Clarifies skills/merge-retrospective/SKILL.md so a zero-repair cycle against an already-existing post-merge-auto-retro stub explicitly updates the stub with the Zero-repair fast-close body and then applies the same confirm-then-close rule as a freshly-filed zero-repair issue.

Facts

Step 0's stub-handling bullet previously said only that Step 5 would replace the stub body with "Step 5's full Repairs content," never naming Step 5's second path (the Zero-repair fast-close single-paragraph body). Step 5's own Zero-repair fast-close bullet, and the Worked example's closing prose, both used the word "file" without saying it also covers updating an existing stub. See git diff 507010e~1 507010e -- skills/merge-retrospective/SKILL.md.

A follow-up commit (a1f23b4d) fixed a body-length regression this diff itself introduced (500 -> 516 lines, over the deterministic-shape checker's 500-line cap) by trimming wording and removing a pre-existing duplicated sentence ("Proposing a gate is proposing, not implementing" appeared twice); re-verified at exactly 500 lines with gitapex_check_skill_shape.py passing 40/40.

Assumptions

None -- this is a documentation/instruction clarification only; no script or gate logic changed. gitapex_check_retro_gate_resolved.py's is_gate_less already excludes a zero-repair-marked issue from the carry-forward backlog regardless of this fix.

Risk / blast radius

Low: text-only change to one skill's procedure steps and worked example. No script, hook, or CI workflow logic is touched.

Rollback

git revert the merge commit if this wording turns out to be wrong.

Verification

Acceptance Criteria Map from issue #1406, restated:

Criterion	Proof method	Result
A zero-repair cycle against an existing stub gets the stub updated with the zero-repair body	Manual read-through of Step 0's stub-handling bullet	Bullet now names both replacement-body shapes and states which applies
A zero-repair cycle against an existing stub is closed once confirmed, same as a freshly-created zero-repair issue	Manual read-through of Step 5's Zero-repair fast-close bullet	Bullet now states the confirm-then-close rule applies identically whether the issue is fresh or an existing stub
Existing worked examples and Step 7 verification text stay consistent with the clarified wording	Manual read-through of the full SKILL.md diff	Worked example prose generalized to match; Step 7 already used issue_write-agnostic wording, no change needed

Also ran (not part of the original ACM, added when the body-length regression surfaced): python3 skills/evaluating-skill-quality/scripts/gitapex_check_skill_shape.py --allowed-root skills skills/merge-retrospective -> 40/40 PASS; gitapex_scan_execution_requirements_drift.py skills/merge-retrospective -> 2 pre-existing drift errors, confirmed identical on the pre-change commit via git stash.

Checklist

• Tests pass locally (no code/tests affected; text-only skill doc change; deterministic shape checker re-run and passing)
• Docs updated if behavior changed (this PR is the doc update)
• Issue number cited in every commit
• ## Skill audit evidence section below discloses both required audits
• Kept-edit-log Transfer check disclosure -- not applicable, no evals/*/split.md edit-log entry added
• Stop-boundary/branch fixture coverage -- no new Stop-boundary bullets or named dispatch branches added, only existing-branch wording clarified

Skill audit evidence

• battle-testing-a-skill: FAIL -- pre-existing structural gaps in skills/merge-retrospective/, not introduced by this diff (three independent isolated-dispatch trials confirmed this diff's own Step 0/Step 5/Worked-example changes introduce no new vulnerability): (1) dim.12 -- no supply-chain/installation-time integrity-verification language for the bundled gitapex_check_retro_gate_resolved.py script; (2) dim.14 -- evals/merge-retrospective/tasks/ (20 fixtures, confirmed to exist at the repo-root evals/ convention) covers classification-accuracy/quality regression only, none inject hostile or obfuscated text; (3) dim.15 -- no multi-turn escalation fixture exists in that same directory; (4) dim.16 -- no explicit mention of base64/homoglyph/HTML-comment/zero-width-character obfuscation countermeasures. A follow-up task has been queued to close these four gaps; not fixed in this PR as it is a substantially larger, pre-existing-scope change.
• evaluating-skill-quality: WELL-FORMED-NOT-MATURE -- deterministic shape check 40/40 PASS (gitapex_check_skill_shape.py, including body-length after the a1f23b4d fix). Two pre-existing maturity gaps carried forward, neither introduced by this diff: Progressive disclosure (dim.5, gap-major) -- the ~110-line Worked example is not split into references/; Conciseness (dim.2, gap-major) -- minor residual duplication (label-application wording repeated between the Labels section and Step 5's own bullet). gitapex_scan_execution_requirements_drift.py's 2 drift errors (tools.write undeclared) are pre-existing, confirmed identical via git stash against the pre-change commit.

Merge gate: independent review

Not pre-filled; drafting-a-pr-to-merge's own Step 8 records this once its independent review completes.

Related Issue

Closes #1406

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ea862f2-e21c-45fb-91db-bdfc34e10c75

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.57%. Comparing base (0130865) to head (a1f23b4).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1416   +/-   ##
=======================================
  Coverage   99.57%   99.57%           
=======================================
  Files         125      125           
  Lines       22364    22364           
  Branches     2748     2748           
=======================================
  Hits        22268    22268           
  Misses         96       96           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tvna]

Heads-up on a citation conflict: issue #1406 was reframed at 2026-08-29T17:50:03Z (about one minute before this PR was opened) from its original narrow scope ("close an existing stub after a zero-repair cycle") into a much larger fix for the merge-retrospective carried-forward-gate backlog problem. The issue now carries a 6-row Acceptance Criteria Map; this PR's own body still quotes the pre-reframe, 3-row version.

This PR's own fix (Step 0/Step 5 stub-handling wording) remains a valid, narrower piece of work -- the reframed issue's own Decision 3 / ACM row 1 explicitly subsumes this same concern as part of a larger Step 5 rewrite that is about to land on branch claude/gitapex-pr-1395-f1t7w4. But this PR's Closes #1406 citation would close the reframed issue on merge while 5 of its 6 current ACM rows remain unimplemented.

Suggest changing Closes #1406 to Refs #1406 before merging, so the issue stays open for the remaining work, and expect a merge conflict against the same skills/merge-retrospective/SKILL.md Step 0/Step 5 section once the larger fix's PR opens -- whichever of the two merges first, the other should rebase.

Full context: #1406 and docs/superpowers/specs/2026-08-29-flat-gate-proposal-issues-design.md on branch claude/gitapex-pr-1395-f1t7w4.

---

Generated by Claude Code