pal-e-docs

SOP: Post-Merge Documentation Update

sop-post-merge-docs Sop

sop active
Project

SOP: Post-Merge Documentation Update

After every PR merge, Betty Sue walks up the traceability chain and updates each level. An item cannot move to done on the board until docs are current. This is the gate between "merged" and "done."

The Rule

Merged does not mean done. Done means docs are current.
The board item stays in needs_approval or wherever it was until Betty Sue confirms docs are updated. Only then does it move to done.

The Traceability Chain

Every board item traces to parent notes. After merge, walk up the chain:

Checklist

  • Close the Forgejo issue — if not auto-closed by "Closes #N" in commit message. Verify it's closed.
  • Verify deploy succeeded — For CI-enabled repos (pal-e-platform), check that the Woodpecker pipeline completed successfully after merge. If the apply step failed, do NOT proceed with doc updates — the work is not done. Follow sop-ci-pipeline-recovery.
  • Update the phase note — set status to completed. Add Forgejo Issue number if it was TBD. Note the PR number and any deliverables or insights. The update_note hook automatically propagates this status change to the corresponding board item column — no manual board move needed.
  • Update the plan note — if this was the last phase, consider marking the plan completed. Otherwise, update the phase summary line (e.g., "Phases 1-4 complete, Phase 5 pending").
  • Update the project page — add the issue to the Issues table (status: resolved). Update the Status section if hook/skill/capability counts changed. Update the Roadmap table if plan progress changed.
  • Sync the project board — call sync_board(board_slug) on the relevant project board. This reconciles all phase items (new phases get board items, status changes align columns, closed Forgejo issues move to done). Then verify the merged item is in done.
  • Update memory — if this work changed the current state of the platform or captured a lesson learned.
  • Create nit-bundle issue — if QA approved with nits, create a single typed Forgejo issue (### Type\nNit-Bundle) on the relevant repo using template-issue-nit-bundle. Bundle all nits from the PR into one issue. The issue auto-syncs to the project board's backlog via sync_board. Add a one-line reference in the plan Epilogue: "Nits from PR #X tracked in {repo} #{issue}" — the Epilogue is provenance, not the tracking mechanism. See glossary for the canonical nit definition.
  • Capture discovered scope — any bugs, deferred items, or future work identified during implementation. Create typed Forgejo issues (Bug, Feature, or Spike) on the relevant repo. They auto-sync to the project board backlog.
  • Cross-pillar impact check — If this PR changes agent-facing behavior (CI pipeline, hooks, enforcement, API schema), create a typed Forgejo issue for the target pillar's repo. Reference the merged PR. See convention-cross-pillar-triggers.

What Gets Skipped (and Shouldn't)

Common failures when this SOP isn't followed:
  • Phase note still says "not-started" after the phase shipped
  • Project page Issues table is stale — doesn't show the latest issues/PRs
  • Plan says "Phase 2 next_up" when Phase 2 is actually complete
  • Board shows "in_progress" for items that already merged
  • Board items missing for new phases (sync_board not called)
  • Memory file references outdated state
  • QA-discovered scope never gets captured as TODOs

Enforcement

Layer Mechanism Strength
<strong>Hook</strong> <code>remind-update-docs.sh</code> — PostToolUse on merge, blocks until <code>/update-docs</code> is run Blocking directive (fires automatically)
<strong>Skill</strong> <code>/update-docs</code> — executable checklist Betty Sue follows Structured recipe
<strong>SOP</strong> This document — defines what "docs updated" means Reference
  • pr-lifecycle — Stage 8 (Post-Merge Cleanup) references this SOP
  • agent-workflow — Step 12 (Update docs + move to Done)
  • skill-update-docs — the executable skill
  • sop-board-workflow — board column semantics and sync cadence