docs(skills): add the epic-closeout skill - #170
Conversation
Promotes the orchestrator epic close-out sequence from a document living
inside the first epic that will close into a project-level, user-invocable
skill taking a `slug`.
Two live epics would otherwise depend on a mechanism document inside a
closed-and-archived tree, and each would carry its own copy of the sequence.
Preserves the mechanism/state split: the skill states the rule, the epic's
ledger supplies the instance. Nothing epic-specific is recorded here.
The rules the ad-hoc work paid for, carried across verbatim:
- consume means archive, never delete (`archive/lessons-consumed/{id}.md`),
persist-then-remove, so an interrupted pass loses at most one lesson
- a discard is archived too, with its rationale
- archive the corrected text of a superseded lesson, not the original
- the lessons corpus is global to the repository, not per-epic
- an assertion of re-homing is not a re-homing — verify it in the target tree
- the bundle index is the durable dedup base; rows flip UNSENT -> sent in the
same action as the send; round numbering restarts at 1 per epic
- prefer a cover note about a class over N disconnected rows
The skill disposes only — it never calls `close`.
Documentation-only footprint (.claude/** alone), so the pre-commit gate does
not apply per CLAUDE.md.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016zTCGAUEzEbQowHT6yfMjP
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @cuioss-oliver, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
PR Reviewer Guide 🔍(Review updated until commit c3d413b)
|
|
Warning Review limit reached
Next review available in: 51 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository: cuioss/coderabbit/.coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis change adds a new ChangesEpic closeout skill
Estimated code review effort: 3 (Moderate) | ~20 minutes 🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
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. Comment |
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: cuioss/coderabbit/.coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ce7f5be1-14cc-48ed-8aa3-74b32e4371d1
📒 Files selected for processing (1)
.claude/skills/epic-closeout/SKILL.md
…the drain CodeRabbit review on PR #170. - The line "Every step operates on that tree" was wrong: steps 3, 5, 6, 7 and 8 write outside the epic tree. State that, and read the scope from the step. - The write-boundary paragraph omitted step 8 from the ledger-write list; it is a successor-ledger write like 6 and 7. - The close-out state document is now required rather than "if it has one", with an explicit bootstrap: compile it from the epic's own artifacts and have the operator confirm it before step 1 writes anything. Without it every step runs on recollection. - New precondition: only one close-out at a time. The corpus is global, so two concurrent drains can dispose of the same lesson twice; the step 3 ordering makes a re-run safe, not a concurrent run. - The same-action flip rule now says plainly that it is not a claim of atomicity, and names the dedup pass as what catches an interruption. - Dropped the cross-skill See-also file path; the shape precedent it made is already stated in the body. Documentation-only footprint (.claude/** alone). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016zTCGAUEzEbQowHT6yfMjP
|
/review |
1 participant
What this is
Promotes the orchestrator epic close-out sequence out of the one epic it was written in and into
a project-level, user-invocable skill at
.claude/skills/epic-closeout/SKILL.md, taking aslug.One file added, nothing else touched. Footprint is
.claude/skills/epic-closeout/SKILL.mdalone.Why a skill rather than a document per epic
The source is
.plan/local/orchestrator/api-sheriff-roadmap/epic-closeout.md, which lives in thefirst epic that will close. Two live epics (
api-sheriff-0-2-0,api-sheriff-0-3-0) wouldotherwise depend on a mechanism document inside a closed-and-archived tree, and each would carry its
own copy of the sequence.
The split it preserves
Same split as
status.json(authority) vs. a generated START-HERE block (rendering). The skill namesno epic, no round number, no defect id and no lesson id.
The rules carried across
archive/lessons-consumed/{lesson-id}.md, a fourthsibling to
bundle-handoffs/,plans-shipped/,plans-struck/; persist-then-remove, so aninterrupted pass loses at most the lesson in flight and a re-run is a no-op.
identical in every epic.
structural cause (the write boundary) stated so it reads as a mechanism, not sloppiness.
flip
UNSENT→ sent in the same action as the send; round numbering restarts at 1 perepic, with the epic's name distinguishing carriers.
Plus two things the skill states plainly: it disposes and never calls
close, and it is notrunnable by accident (explicit slug, no plan in flight, operator asked, state document read first).
One correction to the source
epic-closeout.mdshows the removal asmanage-lessons remove --lesson-id {id}. That invocation isrejected:
--reasonand--coverage-verdictare required, andcompletely_coveredadditionallyrequires
--covering-clauseand--covering-input. The skill carries the full form.Gate
Documentation-only, gate not run. Per
CLAUDE.md§ Pre-Commit Process as it now stands(
ae52984), the exemption is by file class and mixed commits are explicitly not exempt. This commitadds exactly one file under
.claude/**— no*.java, nopom.xml, nosrc/**, no workflow, noDockerfile — so it cannot change build output.
Concurrency with PLAN-48
PLAN-48 owns
.claude/skills/release/SKILL.md,.github/workflows/release.yml,doc/development/release-process.adocandCLAUDE.md. None of them is touched here — the onlyreference to PLAN-48's surface is a See also line pointing at the release skill as a shape
precedent. Disjoint footprints.
Requested follow-up — reduce
epic-closeout.mdto state onlyOutside my write boundary (
.plan/local/orchestrator/**is the orchestrator's tree), so this isreported rather than applied. This is the same boundary that produces rule 5 above; it bites here too.
Target:
.plan/local/orchestrator/api-sheriff-roadmap/epic-closeout.md, rewritten to thisepic's state, opening with a pointer to
.claude/skills/epic-closeout/SKILL.mdfor the how.Keep (state):
archive/bundle-handoffs/plan-marshall-bundle-findings-round-7.md);round 8 is next, compiled 2026-08-03 and UNSENT. The row count in the document is stale:
it says 26, and
bundle-handoff-index.mdnow carries 27(round 8 item N)rows. Either restateit as 27 or, better, drop the number and say read the count from the index — a second copy of a
count is a second thing to go stale.
21 vs 16, and 24 as a recurrence of the standing
--delete-branchclause.recurrence (PLAN-42, PLAN-45); (31)
q_gate_validation: oncevsplan_without_asking: true;(25) empty
documentation.skills_by_profile.module_testing; (16) no sanctioned execution path forthe main-branch
deploy-snapshotcheck; (49)ci pr mergereportsmerged: truefor an enqueue.[OK]self-review are all a mechanismreporting a clean result it never computed.
2026-08-05-10-001was corrected on2026-08-05 after its root cause was refuted, so its corrected text is what gets archived.
"RE-HOMED … TRACK IT THERE, NOT HERE"; (37) is the discharged precedent (asserted-but-unwritten
for a day, enacted 2026-08-05).
coderabbit-oss-rate-limit-blocks-mergecorrected 2026-08-05, its"budget re-triggers" advice wrong.
api-sheriff-0-2-0(re-run Trivy immediatelybefore dispatch; rebuild the scan target from the tree under test; bump
.github/project.ymlcurrent-version; assert GHCRvisibility == "public"viagh api; never--delete-branch). State, because it is the record of one cut — the skill's step 8 states onlythe rule that such knowledge is harvested into the successor.
close; item 5 (memory) mayrun at any point.
Drop (now in the skill):
and its rationale, discards-archived-with-rationale, corrected-text-not-original.
permanent pre-2026-07-29 dedup gap as a rule (the epic keeps the concrete gap as state).
four entries owing verification).
each successor, including per-epic round-1 numbering and the corpus-is-global argument.
Net:
epic-closeout.mdgoes from ~179 lines of mixed mechanism and state to roughly a third of that,all state, headed by one pointer to the skill.
Not done, deliberately
The close-out itself has not been run. Authoring the mechanism was the job; the first execution
is the orchestrator's, after PLAN-48 lands.
🤖 Generated with Claude Code
https://claude.ai/code/session_016zTCGAUEzEbQowHT6yfMjP
Summary by CodeRabbit