[mattmenefee]

Summary

• Adds a Development Workflow section to the user-wide CLAUDE.md, under Workflow, listing the stages every change other than a trivial one goes through: a plan saved as <branch>-PLAN.md; the build, with the Task Completion Checklist and /commit; a draft pull request assigned to me, labeled wip where the repository has that label; a review; the walkthrough, fixing only the groups I select; another review only if warranted, with /handoff once a round closes; and a stop until I start the project's /ship-it, or at "ready to merge" where there is none
• The review stage picks the reviewer by what changed: the project's /local-review for code, /doc-review for documentation, or else agents writing <branch>-REVIEW.md with /doc-review's header. *-REVIEW*.md joins Workflow's working-document list
• Drops the Committing Changes bullet suggesting /doc-review, which the review stage now covers
• Teaches every working-document list the *-REVIEW*.md name: /reflow's skip list, .markdownlintignore, /doc-review's scope filter, /rebase's stale-file listing and the artifact lists in /handoff and /resume-handoff, so an ad hoc review report is never refilled, linted or reviewed as documentation and is tracked like the other working files

Test plan

• markdownlint with the repository's config passes on every changed Markdown file
• /reflow's unfilled-blocks detector reports nothing on the changed lines
• bash home/.claude/skills/reflow/scripts/test-unfilled-blocks.sh passes, including a new case that fails against the old pattern set; ShellCheck is clean on it
• A root *-REVIEW.md with a lint error fails markdownlint under the old .markdownlintignore and is skipped under the new one
• gh pr create --label wip in a repository without the label exits 1 and opens no pull request, which is why the wip label is conditional (checked in a disposable repository, since deleted)
• CI green on the head commit, 208f12d (from gh pr view --json statusCheckRollup: every lint check succeeded)

[mattmenefee]

Doc Review (claude-DOC-REVIEW.md) — all findings fixed

9 fixed, 1 observation · 6 groups closed · reviewed and collated by Opus 5.5

Redacted before posting: none

Click to expand full details

Document Review: CLAUDE.md

Scope	The documents changed on branch document-development-workflow against main (merge-base ea056b8)
Branch	document-development-workflow
Reviewed	2026-10-24
Reviewed by	Opus 5.5 (claude-opus-5-5)
Collated by	Opus 5.5 (claude-opus-5-5)

Documents

Document	Commit
home/.claude/CLAUDE.md	a5daa3d (fixes amended into the rebased 037ac9c, first reviewed at c6ca73e)

Review History

2026-10-24 — Initial review by Opus 5.5 (claude-opus-5-5)

First review of the new Development Workflow section. F1–F9 opened at ❓ and F10 noted as an observation. No handed-back check was run: F6's would create a pull request on GitHub, and the cross-project grep under F2 and F6 cannot run from this repository.

F7 was ruled (b), every change except trivial ones, with its edit pending in G1. F6's handed-back check ran in a disposable private repository and confirmed the finding.

The branch was rebased onto main (patch unchanged, c6ca73e → 037ac9c). All six groups were then worked: F1–F9 are ✅ Fixed in the working tree, with the user choosing the alternative in F2, F3 and F9 and adding "only if warranted" to item 6. Lint and the /reflow detector are clean on the result.

Overall Assessment

The new Development Workflow section had the right shape, but several of its seven stages could not be followed as written. All of that is now fixed. The section covers every change but a trivial one (F7, ruled (b)). Item 4 picks /local-review or /doc-review by kind of change and names a fallback report, and item 5 fixes only the groups the user selects. Item 3's wip label no longer blocks opening a pull request where the label is missing, and item 7 defers to the existing /ship-it rule. Items 1, 2 and 6 now name the plan file, the checklist, /commit and /handoff. Every group is closed and no actionable finding is open; F10 remains an optional observation.

Consistency

F1 🟡 Medium Priority - Step 7 restates the /ship-it rule from Workflow in a narrower and self-contradictory form ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, item 7 (lines 66-67), against Workflow (lines 45-47)
• Issue — Workflow already says: "A command that changes or publishes shared state, such as a project's /ship-it, runs only when I start it." Item 7 repeats this as "like any command that publishes". That drops "changes … shared state", so a reader comparing the two could take item 7 as the narrower, later rule. The instruction also contradicts itself: "Run /ship-it once I start it" tells the agent to run something the user starts. In this repository the agent cannot invoke it anyway: .claude/skills/ship-it/SKILL.md sets disable-model-invocation: true. /ship-it is also a per-project command, and item 7 gives no end point for a project that has none, where line 12's "stop at 'ready to merge'" applies instead.
• Suggestion — "Stop and wait for me to start the project's /ship-it (see Workflow); where there is none, stop at 'ready to merge'"
• Recommendation — Implement: removes the self-contradiction and a second, divergent copy of an existing rule.
• Status — ✅ Fixed: item 7 now reads "Stop and wait for me to start the project's /ship-it (see Workflow); where there is none, stop at "ready to merge""

F2 🟡 Medium Priority - Step 4 sets no file name or location for an ad hoc review report ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, item 4 (lines 61-62)
• Issue — "Write a report shaped like the one /doc-review produces" says nothing about where the report goes or what it is called, and step 7 depends on both. This repository's /ship-it (.claude/skills/ship-it/SKILL.md, Step 6) posts only root-level files matching *local-review*.md or *-REVIEW*.md whose header has a Branch row naming the current branch. It asks about any review without one. A report saved under another name or without that row is silently left out of the published record. "The expert subagents" also uses a definite article for a set that is never defined (home/.claude/agents/ holds seven agents).
• Suggestion — Add: "save it in the project root as <branch>-REVIEW.md, with /doc-review's header table, Branch row included"
• Recommendation — Implement: without a name and header, /ship-it does not post the report.
• Verification — unverified: not checkable from this repository. Whether another project's /ship-it accepts a <branch>-REVIEW.md has to be checked in that project with grep -n -e 'REVIEW' -e 'wip' .claude/commands/ship-it.md.
• Status — ✅ Fixed: item 4 has the fallback review save its report in the project root as <branch>-REVIEW.md, with /doc-review's header table, Branch row included, and *-REVIEW*.md joins Workflow's working-document list (chosen over the name alone and over <branch>-DOC-REVIEW.md, which collides with /doc-review's own file)

F3 🟢 Low Priority - "Consider using /doc-review" under Committing Changes now conflicts with a mandatory review stage ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Committing Changes, second bullet (line 160), against Development Workflow, item 4
• Issue — The new section makes review a required stage for every change. The older bullet still treats /doc-review as optional ("Consider using …") and only for significant documentation. One file now gives two answers to whether a review is optional.
• Suggestion — Drop the Committing Changes bullet, or reword it to "For documentation changes, the review in Development Workflow's item 4 is /doc-review".
• Recommendation — Implement: a one-line removal that settles the conflict.

Accuracy

• Status — ✅ Fixed: dropped the Committing Changes bullet (chosen over rewording it as a pointer), so item 4 is the one place that sends documentation to /doc-review

F4 🟠 High Priority - Step 4 sends code changes to /doc-review, which reviews only documents ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, item 4 (lines 61-62)
• Issue — The section is user-wide, so it applies to every change in every project. But /doc-review reviews only documents. Its Scope section (home/.claude/commands/doc-review.md, "Keep the documents among the changed files") keeps only .md, .mdx, .markdown, .txt, .rst, .adoc and .pdf files, and "A scope with no documents in it stops the run". For a code change, the first option in item 4 therefore reviews nothing, or only the docs that came with the code. The section also never mentions /local-review, the code-review command that /doc-review itself names as "available in project repositories". In a project that has /local-review, item 4 points the agent away from it. The fallback, "the expert subagents", names no agents and no file, so the agent cannot follow it as written (see F2).
• Suggestion — Pick the reviewer by what changed: "Review the changes: the project's /local-review for code where one exists, and /doc-review for documentation. Otherwise, have the relevant agents from ~/.claude/agents/ review them and write a report shaped like /doc-review's."
• Recommendation — Implement: as written, the default review step does nothing for most changes, and the agent gets no sign that the review was skipped.
• Status — ✅ Fixed: item 4 picks the project's /local-review for code and /doc-review for documentation, falling back to the relevant agents from ~/.claude/agents/

F5 🟠 High Priority - Step 5 has the agent fix groups the user never selected, which contradicts /doc-review's walkthrough ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, item 5 (lines 63-64)
• Issue — Item 5 says to walk through the findings "as /doc-review's walkthrough does, then fix the finding groups recommended for implementation". The walkthrough it cites works differently. Phase 3 of Walkthrough and Finding Selection (home/.claude/commands/doc-review.md) proposes an order and asks which group to start with. "Nothing else selects", even a reply like "proceed". A group the user does not choose "stays as it is, since not choosing is not a ruling". Item 5 turns the reviewer's recommendation into authority to edit, which /doc-review rules out ("the recommendation is advice"). The wording is also off: a recommendation belongs to a finding, not a group. A group can hold a ⚖️ Decision, or dependents waiting on one, so "groups recommended for implementation" does not pick out a well-defined set.
• Suggestion — "Walk me through the findings as /doc-review's walkthrough does, then fix the groups I select, in the order we agree"
• Recommendation — Implement: a cross-document contradiction that leads the agent to edit without a ruling. That is exactly what the walkthrough exists to prevent.
• Status — ✅ Fixed: item 5 now fixes "the groups I select, in the order we agree"

F6 🟡 Medium Priority - The wip label exists in this repository, but the user-wide step assumes it exists everywhere ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, item 3 (line 60)
• Issue — This repository has a wip label (gh label list --search wip shows it), and its /ship-it removes it (.claude/skills/ship-it/SKILL.md, Step 7: gh pr edit --remove-label wip). The file is user-wide, though, and other repositories may have no such label. gh pr create --label wip is expected to fail when the label is missing, which would stop the draft pull request from being opened. In a project whose /ship-it does not remove wip, nothing in the workflow takes the label off before merge.
• Suggestion — "Open a draft pull request assigned to me, labeled wip where the repository has that label"
• Recommendation — Implement: a one-clause fix that keeps item 3 from failing in repositories that lack the label.
• Verification — confirmed: gh pr create --draft --label wip --title t --body b, run in a disposable private repository with only GitHub's default labels, exited 1 with "could not add label: 'wip' not found" and created no pull request. Whether another project's /ship-it removes the label is not checkable from this repository; check it there with grep -n -e 'REVIEW' -e 'wip' .claude/commands/ship-it.md.

Clarity and Structure

• Status — ✅ Fixed: item 3 labels the draft wip only "where the repository has that label"

F7 ⚖️ Decision - Which changes go through the seven-stage workflow ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, lead-in (line 56)
• Issue — "Take a change through these stages" has no limit, so read literally it covers a typo fix, a dependency bump or a one-line configuration change. That means a plan, a draft pull request, a review and a walkthrough for each. Line 10 already routes every change through a branch and pull request. The new section adds a plan and a review on top, and the file never says when they can be skipped.
• Options
  • (a) Every change, as written. Uniform and simple to follow, but small changes get a full plan and review cycle, and the agent will either do it or break the rule.
  • (b) Every change except trivial ones, with an example of each. For instance, "a typo or a one-line configuration fix skips the plan and review". This keeps the process where it pays off, but the agent has to judge what counts as trivial.
  • (c) Only when I ask for it, or for a change spanning several files. Lightest, but the workflow stops being the default.
• Recommended — (b), because the review and walkthrough stages cost the most on exactly the changes where they find least, and one concrete example makes the agent's judgment predictable.
• Status — ✅ Fixed — ruled (b): the lead-in now covers "every change other than a trivial one", and "a typo or a one-line configuration fix" skips the plan and the review stages

F8 🟢 Low Priority - The stages skip committing, the Task Completion Checklist and pushing ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, items 2-3 (lines 59-60)
• Issue — Item 2 is "Build" and item 3 opens a pull request. Running linters and relevant specs (Task Completion Checklist), committing with /commit (Committing Changes) and pushing all fall between them, unmentioned. An agent following the list in order could open the pull request before linting or testing. Item 6 also leaves open who decides on another review round. And line 46's "Run /handoff … when a review round closes" never appears where that round closes.
• Suggestion — Extend item 2: "Build according to the plan, run the Task Completion Checklist and commit with /commit". Change item 6 to "Offer to run the reviews again; run /handoff once a review round closes".
• Recommendation — Implement: two in-place edits that make the list followable in order without cross-reading.
• Status — ✅ Fixed: item 2 runs the Task Completion Checklist and commits with /commit; item 6 now reads "Offer to run the reviews again only if warranted; run /handoff once a review round closes" ("only if warranted" added at the user's request)

F9 🟢 Low Priority - "Create a plan" does not say where the plan lives ✅ Fixed

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow, item 1 (line 58)
• Issue — Item 1 could mean plan mode, a message in the chat or a file. Elsewhere the file treats plans as working documents (*PLAN.md, line 17), and this repository's /ship-it posts an untracked *-PLAN.md or PLAN.md from the root. A plan kept only in the conversation is lost at a context break and never reaches the pull request.
• Suggestion — "Create a plan and save it in the project root as <branch>-PLAN.md, untracked"
• Recommendation — Implement: one clause, and it connects item 1 to the artifact /ship-it already expects.

Observations

• Status — ✅ Fixed: item 1 saves the plan in the project root as <branch>-PLAN.md, with tracking left to Workflow's working-document rule (chosen over adding "untracked" and over a bare PLAN.md)

F10 💡 Observation (optional action) - Two numbering styles for ordered lists in one file

• Document — home/.claude/CLAUDE.md
• Location — Development Workflow (lines 58-67), against Task Completion Checklist and Serena MCP Server
• Issue — The new list numbers every item 1., while the two existing ordered lists in the file use 1., 2.. markdownlint's MD029 default (one_or_ordered) accepts both, and /ship-it uses the 1. style. Optional action: renumber the older two lists to 1. the next time either is edited, so the file uses one style.

Consolidated Summary

Finding	Type	Category	Description	Document	Location	Recommendation	Group	Status
F1	🟡 Medium	Consistency	Step 7 restates the /ship-it rule narrower and self-contradictory	home/.claude/CLAUDE.md	Development Workflow, item 7	Implement	G5	✅
F2	🟡 Medium	Consistency	Step 4 sets no file name or location for an ad hoc review report	home/.claude/CLAUDE.md	Development Workflow, item 4	Implement	G3	✅
F3	🟢 Low	Consistency	Committing Changes' optional /doc-review conflicts with a mandatory review stage	home/.claude/CLAUDE.md	Committing Changes, second bullet	Implement	G1	✅
F4	🟠 High	Accuracy	Step 4 sends code changes to /doc-review, which reviews only documents	home/.claude/CLAUDE.md	Development Workflow, item 4	Implement	G3	✅
F5	🟠 High	Accuracy	Step 5 fixes groups the user never selected, contradicting /doc-review's walkthrough	home/.claude/CLAUDE.md	Development Workflow, item 5	Implement	G2	✅
F6	🟡 Medium	Accuracy	The user-wide step assumes a wip label in every repository	home/.claude/CLAUDE.md	Development Workflow, item 3	Implement	G4	✅
F7	⚖️ Decision	Clarity and Structure	Which changes go through the seven-stage workflow	home/.claude/CLAUDE.md	Development Workflow, lead-in	Options (b)	G1	✅
F8	🟢 Low	Clarity and Structure	The stages skip committing, the Task Completion Checklist and pushing	home/.claude/CLAUDE.md	Development Workflow, items 2-3	Implement	G6	✅
F9	🟢 Low	Clarity and Structure	"Create a plan" does not say where the plan lives	home/.claude/CLAUDE.md	Development Workflow, item 1	Implement	G6	✅
F10	💡 Observation	Formatting	Two numbering styles for ordered lists in one file	home/.claude/CLAUDE.md	Development Workflow	—	—	—

Pre-Merge Checklist

G1 ✅ — Settle which changes the workflow covers

Closed: F7's ruling (b) and F3's dropped bullet are both in.

• ✅ F7 - Which changes go through the seven-stage workflow (changed to (b): every change but a trivial one)
• ✅ F3 - Drop or reword the Committing Changes /doc-review bullet

G2 ✅ — Have the walkthrough fix only the groups the user selects

Closed: item 5 now fixes only the groups the user selects.

• ✅ F5 - Fix the groups the user selects, in the agreed order, not those recommended for implementation

G3 ✅ — Make the review step work for every kind of change

Closed: item 4 now picks the reviewer by kind of change and names the fallback report.

• ✅ F4 - Pick /local-review for code and /doc-review for documentation, with named agents as the fallback
• ✅ F2 - Save the ad hoc report as <branch>-REVIEW.md in the project root with /doc-review's header

G4 ✅ — Apply the wip label only where it exists

Closed: item 3 applies wip only where the label exists.

• ✅ F6 - Label the draft wip only where the repository has that label

G5 ✅ — Defer item 7 to the existing /ship-it rule

Closed: item 7 defers to Workflow's /ship-it rule.

• ✅ F1 - Wait for the user to start the project's /ship-it, or stop at "ready to merge" where there is none

G6 ✅ — Fill the steps and artifacts the stages leave out

Closed: items 1, 2 and 6 now name the plan file, the checklist, /commit and /handoff.

• ✅ F8 - Add the Task Completion Checklist, /commit and /handoff to items 2 and 6
• ✅ F9 - Save the plan as <branch>-PLAN.md in the project root

Not recommended for this revision

None: every actionable finding other than F7 is recommended Implement.

[mattmenefee]

Handoff notes — 12 decisions, 5 insights, 2 dead ends, 0 open questions

Handoff updated 2026-10-24, captured by Opus 5.5 (claude-opus-5-5); the working-tree state it described is superseded by the merge.

Click to expand full details

Decisions & Rationale

• Every change except a trivial one takes the full workflow (the user's call, review finding F7, option b of three). A typo or a one-line configuration fix skips the plan and the review stages; rejected were "every change" (heavy on tiny changes) and "only on request" (the workflow stops being the default)
• Item 4 picks the reviewer by kind of change (finding F4, recommended Implement, worked when the user selected all groups): /doc-review drops every non-document file and stops when none is left, so it cannot review code; /local-review takes code where a project has it
• The ad hoc review report is <branch>-REVIEW.md, and *-REVIEW*.md joins the working-document list (the user's call, F2). <branch>-DOC-REVIEW.md was rejected because /doc-review writes exactly that name for a multi-document run on the branch, so the two would merge
• The Committing Changes bullet "Consider using /doc-review…" was dropped rather than reworded (the user's call, F3): item 4 is now the single place that sends documentation to /doc-review
• The plan is <branch>-PLAN.md, with tracking left to the working-document rule (the user's call, F9): adding "untracked" would contradict the rule "Commit one only where the project's /ship-it expects it"
• Item 6 offers another review round "only if warranted" (the user's wording, given mid-fix)
• Item 5 fixes only the groups the user selects (F5): /doc-review's walkthrough never edits on a recommendation alone
• wip is applied only where the label exists (F6, confirmed by a check the user approved): see Insights
• The review fixes were amended into the first commit, and every working-document list was taught *-REVIEW*.md in one second commit (the user's calls): one commit documents the workflow, the other updates the tooling for the name it introduced
• /reflow ran before the review (agent's judgment): line-break changes shift the line numbers a review cites
• This pull request merges before Lint the Python scripts and test teams-copy in CI #180 (the user's call), so Lint the Python scripts and test teams-copy in CI #180 rebases onto it rather than the reverse
• The remaining 100-column reflow of the /reflow scripts went to Lint the Python scripts and test teams-copy in CI #180 (the user's call), which brings Ruff and its .ruff.toml; it was told to leave the lines this pull request changes so the rebase stays clean

Insights & Learnings

• gh pr create --draft --label wip in a repository without a wip label exits 1 with could not add label: 'wip' not found and creates no pull request (checked in a disposable private repository, since deleted)
• Homesick links each skill directory as one symlink, so a new skill directory such as rebase stays invisible to Claude Code until yes n | homesick link dotfiles runs; files added inside an already-linked directory need no relink. A session picks up a newly linked skill without restarting
• Homesick links whatever sits under home/, tracked or not, so an untracked .DS_Store there shows up as a link candidate; the yes n form declines it
• The live skills come from whatever branch the castle checkout has checked out, not from the worktree being worked in, so a script's file mode or a skill's text can differ between the two
• A git file-mode fix shows in git show --summary but not as a content diff: the blob is unchanged, the executable bit lives in the tree entry

Dead Ends

• Running ~/.claude/skills/doc-review/scripts/header.sh by path failed with exit 126 ("permission denied") because it was tracked as 100644; bash header.sh worked. Fixed on convert-commands-to-skills as 748420b
• A first wait-merged.sh was started by hand, before the /rebase skill was linked; it was stopped and the wait re-run through the Skill tool, so PR Add a /rebase skill that rebases, verifies and pushes under a lease #173's "invoked as a skill" box describes a real skill invocation

References

• PR Document the development workflow in the user-wide CLAUDE.md #181 — Document the development workflow in the user-wide CLAUDE.md #181 — this pull request
• PR Lint the Python scripts and test teams-copy in CI #180 — Lint the Python scripts and test teams-copy in CI #180 — merges after this one; carries the rest of the /reflow scripts' reflow
• PR Tick /ship-it's CI item from the head commit's status rollup #176 — Tick /ship-it's CI item from the head commit's status rollup #176 — this branch was rebased onto it
• PR Add a /rebase skill that rebases, verifies and pushes under a lease #173 — Add a /rebase skill that rebases, verifies and pushes under a lease #173 — added /rebase; its test plan cites this branch's rebase
• 748420b — on convert-commands-to-skills, makes doc-review/scripts/header.sh executable