pal-e-docs

Review: Audit post-merge SOP for board-driven workflow

review-506-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Issue type is Task. Per template-issue, Task type replaces File Targets with a Scope section. This issue has BOTH a Scope AND File Targets section, which is fine -- extra specificity for a documentation ticket. Checking against template-issue (Task variant):
  • [x] Type -- Task
  • [x] Scope -- present, detailed, 7 specific sub-issues enumerated
  • [x] File Targets -- present (bonus for Task type), identifies two pal-e-docs notes
  • [x] Acceptance Criteria -- 8 criteria, all checkboxable
  • [x] Constraints -- present, appropriate (surgical edits, doc-only)
  • [x] Related -- present, 6 references all relevant
  • [ ] Lineage -- MISSING (template requires it)
  • [ ] Repo -- MISSING (template requires it; this ticket targets pal-e-docs notes AND a claude-custom file)
  • [ ] User Story -- MISSING (acceptable for Task type per convention, but template still shows it)
  • [ ] Test Expectations -- MISSING (acceptable for doc-only ticket)
  • [ ] Checklist -- MISSING (PR opened / Tests pass / No unrelated changes)

Traceability

  • [x] story:pm-scope label -- PM scope management story. Correct: this is about Betty Sue's post-merge workflow.
  • [x] arch:note-system label -- Correct: modifying SOP and skill notes in the note system.
  • [x] Forgejo issue -- forgejo_admin/claude-custom#190, open. Valid.
  • [x] track:agency label -- Correct: pal-e-agency track.
  • [x] type:feature label -- Acceptable: this is an enhancement to existing SOP, though type:task would match the issue Type header better.

File Targets

  • [x] sop-post-merge-docs -- verified: pal-e-docs note exists, contains the 10-step checklist with all 7 stale references confirmed (phase note, plan note, Issues table, Roadmap, plan Epilogue, no validation column, stale traceability chain).
  • [x] skill-update-docs -- verified: pal-e-docs note exists, contains 9-step list with matching stale references (phase note step 3, plan note step 4, Issues/Roadmap/TODOs tables in step 5, todo-* slug in step 8, stale MCP tool references: get_sprint_board, move_sprint_item).
  • [ ] commands/update-docs.md -- MISSING from File Targets. This is the actual command file that agents execute (in claude-custom repo). It contains the same stale references: Step 3 (phase note), Step 4 (plan note), Step 5 (Issues table), Step 9 ("plan's Epilogue section"), Gather Context section asks for "Phase slug" and "Plan slug". If only the two pal-e-docs notes are updated, agents will continue executing the stale command file.

Repo Placement

ISSUE: The Forgejo issue is filed on claude-custom but the File Targets only list pal-e-docs notes. The issue body says "No code changes -- this is a documentation-only ticket" and constraints say "all doc changes via mcp__pal-e-docs__* tools." However, commands/update-docs.md IS a code file in claude-custom that must also be updated. This is actually correct repo placement (claude-custom owns the command file), but the scope omits it and the Constraints section incorrectly claims no code changes.

Dependencies

  • Board item #487 (Update template-board, template-ticket, template-project-page) -- DONE. No blocker.
  • Board item #397 (Update 11 SOPs/conventions for kanban-over-plans) -- DONE. The broad kanban-over-plans sweep is complete; this ticket is the surgical follow-up for the post-merge SOP specifically.
  • Board item #505 (Bug: post-merge hook false alarm on squash merge) -- DONE. Hook reliability is resolved.
  • Board item #478 (Spike: Note type system audit) -- IN PROGRESS. Not a hard dependency, but new note types (review, validation) may affect how the SOP references them. Low risk.
  • No undocumented blocking dependencies found.

Acceptance Criteria

8 acceptance criteria. Assessment:
  • AC 1: "SOP handles both plan-driven and board-driven post-merge flows" -- STALE per decision. The issue's Resolved section says "Fully deprecate plan-driven path." This AC contradicts the decision. Should be: "SOP handles board-driven post-merge flow only; all plan/phase references removed."
  • AC 2: "Steps reference current template-project-page sections" -- Testable. Agent can read template-project-page and verify.
  • AC 3: "Validation column step included" -- Testable. Agent can grep for "validation" in updated SOP.
  • AC 4: "MCP restart step included" -- Testable.
  • AC 5: "Nit-bundle references updated" -- Testable.
  • AC 6: "No references to deprecated concepts" -- Testable via grep.
  • AC 7: "the-traceability-chain section updated" -- Testable.
  • AC 8: "skill-update-docs SKILL.md updated" -- Testable, but INCOMPLETE: does not mention commands/update-docs.md.
Missing AC: "commands/update-docs.md updated to match corrected SOP steps" -- the actual executing command file.

Blast Radius

  • commands/update-docs.md in claude-custom -- the primary executing artifact, not listed in scope. Contains all the same stale references.
  • hooks/remind-update-docs.sh -- references sop-post-merge-docs but only name, no stale content. No change needed.
  • skills/review-ticket/SKILL.md -- references "plan Epilogue" and "plan note" in passing. Low priority, not in scope of this ticket.
  • skill-update-docs pal-e-docs note has stale MCP tool references (get_sprint_board, move_sprint_item) that should be updated to current tools (list_board_items, update_board_item). Not mentioned in scope.

Decomposition

File count: 3 targets (2 pal-e-docs notes + 1 repo file), single repo (claude-custom) + pal-e-docs MCP. AC count: 8 (should be 10 with missing ones). Estimated agent time: ~4-5 minutes for surgical block-level edits across 3 artifacts. Borderline but fits a single agent pass if scope is tightened. No decomposition needed.

Recommendation

  • [BODY] AC 1 contradicts the Resolved decision. Change from "handles both plan-driven and board-driven" to "fully deprecates plan-driven path; SOP handles board-driven workflow only."
  • [BODY] Add commands/update-docs.md to File Targets: "the actual command file agents execute (must be updated in lockstep with the SOP note)."
  • [BODY] Add AC 9: "commands/update-docs.md updated to match corrected SOP -- no phase/plan slug in Gather Context, no Step 3/4 for phase/plan, Step 5 references current project page sections, Step 9 removes Epilogue reference."
  • [BODY] Add AC 10: "skill-update-docs MCP tool table updated (replace stale get_sprint_board/move_sprint_item with list_board_items/update_board_item)."
  • [BODY] Add Lineage header: "Standalone -- discovered during PR #226 post-merge."
  • [BODY] Add Repo header: "forgejo_admin/claude-custom (command file) + pal-e-docs notes (SOP + skill)."
  • [BODY] Update Constraints: remove "No code changes" claim -- commands/update-docs.md IS a code change in claude-custom.
  • [LABEL] Consider adding type:task label to match the issue Type header (currently type:feature). Minor nit.