docs(skills): bundle docs into the code PR (single-PR finalization)#625
Conversation
Changes the /impl-execute finalization model from a post-merge second docs-only PR to running finalization on the feature branch BEFORE merge, so the folder move + state.md + dashboard/roadmap regen ride in the same PR as the code they describe. Why: docs-only PRs skip pr.yml (paths-ignore), so under the new main branch protection they can't be gated on the test suite and (once test jobs are required) would deadlock. Bundling docs into the code PR removes that class of PR, keeps docs from drifting from code, and is a prerequisite to requiring the real test jobs as branch-protection checks. - impl-execute SKILL.md Step 8: finalize pre-merge on the feature branch; reference the PR number (not the post-merge squash SHA); regen dashboards in the code PR; keep a docs/finalize fallback only for already-merged / genuinely-docs-only cases. Updated the two-PR note, Step 9, ad-hoc note. - CLAUDE.md: added the 'docs land with their code' convention. Signed-off-by: SoundMindsAI <eric.starr@soundminds.ai>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the development workflow documentation in .claude/skills/impl-execute/SKILL.md and CLAUDE.md to transition from a two-PR model to a single-PR model, ensuring that all documentation and finalization steps are bundled directly into the code PR before merging. The reviewer provided a valid improvement to explicitly include sub-step 9 (closing the tracking issue) in the list of sub-steps that still apply during ad-hoc mode.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Sub-step 9 (close tracking issue) was omitted from both the skipped and still-applies lists in the ad-hoc note; an ad-hoc bug/chore may have a tracking issue, so it belongs in still-applies. Accepted from Gemini. Signed-off-by: SoundMindsAI <eric.starr@soundminds.ai>
Review adjudication (Gemini Code Assist)
Applied (1) / Rejected (0) / Deferred (0). |
1 participant
Summary
Changes the
/impl-executefinalization model from a post-merge second docs-only PR to running finalization on the feature branch before merge, so a feature's folder move +state.mdentry + dashboard/roadmap regen ride in the same PR as the code they describe.Why now
Docs-only PRs skip
pr.yml(itspaths-ignorefilter), so under the newmainbranch protection they can't be gated on the test suite — and once the real test jobs become required checks, a docs-only PR would deadlock (required checks never report). Bundling docs into the code PR removes that entire class of PR, keeps docs from drifting out of sync with code, and is the prerequisite for addingbackend (unit),frontend,static-checks, and (after PR #624)backend (contract + integration)as required status checks.Changes
.claude/skills/impl-execute/SKILL.mdStep 8: finalize pre-merge on the feature branch; reference the PR number not the post-merge squash SHA (which doesn't exist until merge —git logis canonical); regenerate dashboards/roadmap in the code PR so the freshness gate validates them; updated the two-PR note, Step 9 (post-merge cleanup), and the ad-hoc note. Adocs/finalize-*branch + follow-up PR remains only as the fallback for already-merged / genuinely-docs-only cases.CLAUDE.md: added the "docs land with their code — single-PR finalization" convention so it's authoritative repo-wide.Test plan
test_claude_md_sections.pypasses (CLAUDE.md structure intact)🤖 Generated with Claude Code