Replace re-anchoring prose with early-completion delegation pattern (Fixes #121)

[LeanAndMean]

Summary

• Replace the post-delegation re-anchoring prose in pr-review-fix.md with an early-completion pattern that marks Step 3 complete before the Skill invocation, using the task list state as the re-anchoring signal
• Rename Step 3 to "Delegate review fixes to feature-dev" so early-completion semantics are self-evident from the task name
• Switch delegated phase naming from "Phase N:" to "Step N.M:" for hierarchical parent-child visibility in the flat task list
• Update CLAUDE.md task-tracking conventions to document the new delegation step completion pattern, replacing the old re-anchoring spec

Test plan

• Run /mach10:pr-review-fix on a PR with at least one review finding and verify all 5 steps (0-4) show completed
• Verify the /mach10:push next-step suggestion is output after feature-dev delegation completes
• Verify delegated phases use "Step 3.N:" naming in the task list

Fixes #121

---

Generated with Claude Code

[LeanAndMean]

PR Review: Replace re-anchoring prose with early-completion delegation pattern

Critical Issues (2 found)

F1: CLAUDE.md "Delegation step completion" and "Skill and subagent delegations" overgeneralize to all Skill delegations

The new "Delegation step completion" bullet states a blanket rule: "When a tracked step delegates to a Skill (via the Skill tool), mark the step complete before the Skill invocation." The "Skill and subagent delegations" bullet states: "For Skill delegations, the Skill creates hierarchical sub-tasks ("Step N.M:") representing its internal phases." Both are written as universal truths about all Skill delegations, but they only apply to phase-structured delegations (like feature-dev). commands/pr-review.md Step 2 delegates to /pr-review-toolkit:review-pr via the Skill tool and marks Step 2 complete after the delegation returns -- contradicting the blanket rule. The pr-review-toolkit delegation also does not create hierarchical sub-tasks.

The old "Post-delegation re-anchoring" bullet was more carefully scoped with the parenthetical "Long-running Skill calls (especially /feature-dev:feature-dev)" and the "Delegation phase tracking" bullet already carves out an exception for fan-out/fan-in patterns. The new bullets need similar qualifying clauses.

Files: CLAUDE.md lines 107-109
Sources: per code-reviewer, per code-simplifier

F2: CLAUDE.md states "no prose needed" but pr-review-fix.md adds explanatory prose

The "Delegation step completion" bullet in CLAUDE.md explicitly states "the task list state is the re-anchoring signal, no prose needed." However, pr-review-fix.md line 107 contains: "Step 3's responsibility is preparing and launching the delegation -- completion indicates the handoff happened, not that the fixes are done. The task list state (Step 3 complete, Step 4 pending) is the re-anchoring signal for when the Skill returns." This is a direct contradiction -- the convention says no prose is needed, but the sole implementation of the convention includes two sentences of explanatory prose.

Files: CLAUDE.md line 109, commands/pr-review-fix.md line 107
Sources: per comment-analyzer

Important Issues (3 found)

F3: Step 3 marks complete before any preparation happens

In pr-review-fix.md, the instruction sequence is: "Mark Step 3 in progress." followed immediately by "Mark Step 3 complete." with no intervening work. The explanatory text says "completion indicates the handoff happened" but at the point where completion is marked, the handoff has not happened -- the Skill tool invocation comes later. If the Skill invocation fails, Step 3 would show as completed even though the delegation never launched.

Files: commands/pr-review-fix.md lines 105-109
Sources: per code-reviewer, per comment-analyzer

F4: Significant duplication of "Step N.M:" naming convention across four CLAUDE.md bullets

The "Step N.M:" naming convention and delegation rationale are restated across "State transitions" (exception clause), "Skill and subagent delegations" (sub-task description), "Delegation step completion" (full naming explanation), and "Delegation phase tracking" (naming with dual-purpose note). The old "Post-delegation re-anchoring" bullet was self-contained. The replacement scatters the same concepts across four bullets, increasing maintenance burden and risk of divergence when one is updated but others are not.

Files: CLAUDE.md lines 107-110
Sources: per comment-analyzer, per code-simplifier

F5: "At least one sub-task must be created" requirement has no enforcement in the command file

The CLAUDE.md "Delegation step completion" bullet states "At least one sub-task must be created" but pr-review-fix.md Step 3 does not include any instruction verifying or requiring this. The Skill invocation blockquote says "Create a task for each phase" which implies sub-tasks but never states a minimum.

Files: CLAUDE.md line 109, commands/pr-review-fix.md lines 109-127
Sources: per code-simplifier

Suggestions (4 found)

S1: Remove the explanatory sentences from pr-review-fix.md line 107, leaving just "Mark Step 3 complete." The convention document owns the rationale; command files in this repo are terse step-by-step instructions.
Sources: per comment-analyzer, per code-simplifier

S2: Simplify the "State transitions" bullet by replacing the multi-sentence delegation exception with a brief cross-reference to "Delegation step completion" (e.g., "Exception: delegation steps follow the early-completion pattern described in Delegation step completion below."). This keeps the bullet focused on the general rule.
Sources: per comment-analyzer, per code-simplifier

S3: Consider merging "Delegation step completion" and "Delegation phase tracking" into a single "Delegation conventions" bullet to reduce duplication of the "Step N.M:" naming convention.
Sources: per code-simplifier

S4: Move the forward-looking note about issue-implement.md and pr-ci-fix.md from the "Delegation step completion" bullet to the issue or sync note where the relationship is already documented. This keeps normative convention bullets focused on current behavior.
Sources: per code-simplifier

Strengths

• Feature completeness: PR fully implements all 4 acceptance criteria and both stages of the implementation plan for issue 121 (per feature-completeness-checker -- no gaps found)
• Step 3 rename from "Fix review findings via feature-dev" to "Delegate review fixes to feature-dev" is well-chosen -- makes the handoff nature immediately clear from the task name
• Phase naming change from "Phase N:" to "Step N.M:" correctly implements hierarchical parent-child visibility in the flat task list
• Task-tracking instruction sync note updated correctly from "Phase N:" to "Step N.M:"
• Clean removal of old re-anchoring prose from Step 4 -- no orphan references remain
• Version bump (1.24.0 to 1.24.1) appropriate for a convention change

---

Automated review by Claude Opus 4.6 using pr-review-toolkit (code-reviewer, comment-analyzer, code-simplifier) and mach10 (feature-completeness-checker)

[LeanAndMean]

Independent Assessment

Assessing findings from the review comment.

Finding Classifications

F1: CLAUDE.md overgeneralizes early-completion to all Skill delegations

Classification: Genuine issue

Verified. CLAUDE.md line 109 says "When a tracked step delegates to a Skill (via the Skill tool), mark the step complete before the Skill invocation" -- a blanket rule. Line 108 says "For Skill delegations, the Skill creates hierarchical sub-tasks" -- also blanket. But commands/pr-review.md Step 2 delegates to pr-review-toolkit via the Skill tool and marks complete after the delegation returns (line 72), contradicting both rules. The "State transitions" exception partially scopes it ("when a step's sole purpose is to prepare and launch a Skill delegation"), but "Delegation step completion" opens without that qualifier.

F2: CLAUDE.md states "no prose needed" but pr-review-fix.md adds explanatory prose

Classification: Genuine issue

Verified. CLAUDE.md line 109 states "the task list state is the re-anchoring signal, no prose needed." Yet pr-review-fix.md line 107 adds two sentences of explanatory prose. There is a reasonable reading that "no prose needed" refers to runtime output while the command prose is authoring-time documentation, but the wording is ambiguous and the command prose reads like a runtime instruction.

F3: Step 3 marks complete before any preparation happens

Classification: False positive

This is the intended design, not a bug. The CLAUDE.md convention explicitly prescribes this pattern: early completion for delegation steps. The preparation work (gathering context, selecting findings) happens in Steps 1 and 2. Step 3 is named "Delegate review fixes to feature-dev" -- its purpose is the handoff, not execution. The Skill invocation context is assembled from data already collected.

F4: Significant duplication of "Step N.M:" naming across four bullets

Classification: Nitpick

Verified that the convention appears in four bullets, but each serves a different purpose (when to complete, ownership, the pattern, how to instruct). Convention documentation often repeats key details at each point of use. Claude models benefit from redundancy over cross-references.

F5: "At least one sub-task must be created" has no enforcement

Classification: False positive

The Skill invocation (line 111) instructs: "Create a task for each phase of the 7-phase development plan." The 7-phase plan guarantees well more than one sub-task. The convention's "at least one" is a minimum bar for the general case; this command exceeds it.

S1: Remove explanatory sentences from pr-review-fix.md line 107

Classification: Connected to F2 -- if F2 is addressed, S1 is the natural fix approach.

S2: Simplify "State transitions" with cross-reference

Classification: Nitpick -- inline context is preferable for linear model consumption.

S3: Merge "Delegation step completion" and "Delegation phase tracking"

Classification: Nitpick -- separation is intentional (early completion can exist without phase tracking).

S4: Move forward-looking note about issue-implement.md and pr-ci-fix.md

Classification: Deferred -- judgment call on documentation placement, out of scope for this PR.

Staged Implementation Plan

Required Stages

Stage 1: Scope the early-completion convention to phase-structured delegations (F1)

• Files: CLAUDE.md (lines 107-109)
• In "State transitions" (line 107): qualify the exception to phase-structured delegations
• In "Delegation step completion" (line 109): add qualifier like "When a tracked step delegates to a phase-structured Skill" and clarify that fan-out/fan-in patterns use standard complete-after-return
• In "Skill and subagent delegations" (line 108): qualify sub-task statement

Stage 2: Reconcile "no prose needed" with pr-review-fix.md text (F2, S1)

• Files: CLAUDE.md (line 109), commands/pr-review-fix.md (line 107)
• Either soften CLAUDE.md to "no re-anchoring prose is required in subsequent steps" and keep pr-review-fix.md, or keep CLAUDE.md strict and trim pr-review-fix.md to just "Mark Step 3 complete."

Optional Stages

Stage 3: Reduce duplication in naming convention references (F4, S2, S3)

• Files: CLAUDE.md (lines 107-110)
• Consolidate "Step N.M:" format definition and cross-reference from other bullets

Summary

Classification	Count	Findings
Genuine	2	F1, F2
False positive	2	F3, F5
Nitpick	1	F4
Deferred	1	S4

---

Independent assessment by Claude Opus 4.6

[LeanAndMean]

Progress update

Commit 33f7854 addresses review findings F1 and F2, and applies the early-completion delegation pattern to pr-review.md:

• F1 fix: Removed the fan-out/fan-in opt-out from CLAUDE.md "Delegation phase tracking" bullet. All Skill delegations now require sub-tasks -- skills with explicit phases create a task per phase, skills without pre-defined phases use best judgment on granularity (minimum one sub-task).
• F2 fix: Removed explanatory prose from pr-review-fix.md line 107, leaving just "Mark Step 3 complete."
• pr-review.md Step 2: Renamed to "Delegate PR review to pr-review-toolkit", moved completion marker before Skill invocation, added sub-task creation instruction in the Skill invocation blockquote.
• CLAUDE.md sync note: Added pr-review alongside pr-review-fix in the Task-tracking instruction sync note for delegation blockquotes.

[LeanAndMean]

Progress Update

Commit: 8e33b2e — Add post-delegation continuation cue to prevent workflow stall

What happened

During the /mach10:pr-review run on this PR, the early-completion pattern caused a regression: after the Skill delegation returned (with output from 5 parallel review agents), the model stalled instead of continuing to Step 3. The old "Mark Step 2 complete" line after the Skill invocation had served as a continuation signal — removing it left no instruction for the model to encounter after the Skill returned.

What changed

• Added "After the delegation returns, proceed to Step N." continuation cue after the Skill invocation block in both pr-review.md and pr-review-fix.md
• Updated CLAUDE.md "Delegation step completion" convention to require a continuation cue instead of claiming "no prose needed"

This is a minimal one-line cue — not re-anchoring prose. It doesn't re-establish context about what happened; it simply tells the model what to do next.