pal-e-docs

Re-Review: Update 13 SOPs/conventions for kanban-over-plans

review-397-2026-03-26-v2 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review of board item #397 (Forgejo issue claude-custom#169). Prior review found two issues: missed template-issue parent and weak verification method. Both were addressed in Comment 3. This re-review validates those fixes and runs a fresh blast radius check.

Prior Review Issues

  • [x] template-issue added as note #13 in Comment 3 — RESOLVED
  • [x] Verification criterion changed from get_note_toc to get_section in Comment 3 — RESOLVED

Template Completeness

  • [x] Type — present (Feature, with note about Task workaround)
  • [x] Lineage — present (standalone, discovered during audit)
  • [x] Repo — present (claude-custom tracking repo, actual work via MCP)
  • [x] User Story — present (Betty Sue PM perspective)
  • [x] Context — present (references convention-kanban-over-plans)
  • [x] File Targets — present (13 pal-e-docs notes listed)
  • [x] Acceptance Criteria — present (updated across body + comments 1 and 3)
  • [x] Test Expectations — present (read each note, verify no plan/phase references)
  • [x] Constraints — present (surgical edits, no historical rewrites)
  • [x] Checklist — present
  • [x] Related — present (project, story, arch, convention links)

File Targets

  • [x] template-plan — verified exists, status currently "active", needs "deprecated"
  • [x] template-phase — verified exists, status currently "active", needs "deprecated"
  • [x] template-ticket — verified exists, traceability triangle shows "Phase (note_slug)" as third leg, example section uses phase item_type
  • [x] template-issue-feature — verified exists, has Lineage section in Forgejo template
  • [x] template-issue-bug — verified exists, has Forgejo issue template section
  • [x] template-issue-spike — verified exists, has Forgejo issue template section
  • [x] agent-workflow — verified exists, "Two Work Paths" section has Path 1: plan → phases → issues
  • [x] agent-spawn-conventions — verified exists, "Two Work Paths" table has plan path, "Required in Every Spawn Prompt" says "Plan slug OR Forgejo issue URL"
  • [x] convention-todo-lifecycle — verified exists, Lifecycle table stage 3a references "Plan path"
  • [x] sop-board-workflow — verified exists, item lifecycle table has plan and phase item_types
  • [x] glossary — verified exists, Scoping Pipeline shows "Project → Plan → Phase → Forgejo Issue → Agent → PR"
  • [x] skill-review-ticket — verified exists, Inputs section references "Plan context — optional phase note slug for plan-driven items"
  • [x] template-issue — verified exists, Forgejo template has "### Plan" (not Lineage), traceability chain says "Project → Plan → Phase → Forgejo Issue → PR", "How Betty Sue Tracks Issues" references plan phases

Repo Placement

OK. Issue is filed on claude-custom as a tracking repo. Actual work is pal-e-docs MCP updates — no code files involved. This is correctly identified as a Task (non-code work).

Dependencies

  • convention-kanban-over-plans — the source convention. Already active. No blocker.
  • Board item #395 (claude-custom#167, "Upgrade story: label to hard-block + Task type routing") — this ticket is typed as Feature because Task type doesn't exist yet. Not a blocker, just a workaround noted in the issue.
  • Board item #396 (claude-custom#168, "Remove plan/phase hooks from enforcement layer") — related kanban cleanup. No dependency in either direction; can be done in parallel.
  • Board item #398 (claude-custom#170, "Board hygiene — label unlabeled items") — also kanban cleanup. No dependency.

Acceptance Criteria

Verifiable. Each criterion maps to a specific note and a specific change. The updated verification method (get_section instead of get_note_toc) from Comment 3 is adequate — it confirms actual content removal, not just heading existence. An executing agent can verify every criterion.

Blast Radius

One active template missed from scope:
  • template-pr-body — its Related Notes section contains plan-slug — the plan phase this implements. This is an active template that agents reference on every PR. It must be updated to remove the plan-slug line or replace it with Forgejo issue reference only. This is the same class of issue as the template-issue parent miss found in the first review.
Borderline notes (not recommended for scope):
  • template-project-page — Section Order item 5 says "updated after phase completions." However, this template was already overhauled on 2026-03-24 specifically for kanban-over-plans. The phrase is vestigial in a changelog context. Low priority — could be a nit in the execution PR.
  • template-milestone — lifecycle section references "Plan completed." Milestones may still reference plans historically. Low priority.
  • sop-pr-rejection-recovery — has a plan traceability reference in its lineage header. Archival context, not active guidance.

Traceability

  • story:pm-scope — Betty Sue PM workflow. Valid.
  • arch:kanban — kanban architecture component. Valid.
  • scope:unplanned — discovered during audit. Valid.
  • Project: pal-e-agency. Valid.

Recommendation

Add template-pr-body as note #14 to the scope. Its Related Notes section explicitly references plan-slug — the plan phase this implements and must be updated to reference Forgejo issue URLs instead. This brings the total to 14 notes.
All other findings are minor and can be captured as nits during execution. The prior two issues from the first review are fully resolved.