refactor: update post-merge command for board-driven workflow #207

Merged

forgejo_admin merged 1 commit from 190-audit-post-merge-sop into main 2026-03-28 11:56:34 +00:00

Conversation 2 Commits 1 Files changed 1 +59 -50

forgejo_admin commented 2026-03-28 11:52:02 +00:00

Contributor

Copy link

Summary

Fully deprecates the plan/phase-driven path in commands/update-docs.md per convention-kanban-over-plans. Replaces stale plan/phase steps with MCP restart check and production validation steps, fixes project page references to current template sections, and rewrites the traceability chain for board-driven flow.

Changes

• commands/update-docs.md -- rewritten from 10 plan-era steps to 10 board-driven steps:
  • Removed Steps 3-4 (phase note update, plan note update) -- plans are deprecated
  • Removed phase-slug and plan-slug from Gather Context
  • Added Step 3: MCP Restart Check for schema-changing merges
  • Updated Step 4 (Project Page): references Status + Milestones sections (not stale "Issues table" / "Roadmap")
  • Updated Step 4: uses get_section + update_block for surgical edits (not update_note)
  • Split old Step 7 into Step 6 (move to validation column) and Step 7 (production validation before done)
  • Updated Step 9 (Nit-bundle): nits go to board backlog, not plan Epilogue
  • Replaced Traceability Chain section: Forgejo Issue -> PR -> Board Item -> Project Page with label-based traceability (story:, arch:, type:)
  • Updated completion summary template to match new step numbering

Test Plan

• Grep for stale references: grep -iE 'phase|plan|Epilogue|Roadmap|Issues table|sprint|get_sprint|move_sprint' commands/update-docs.md returns only tofu plan (the CLI command, not a pal-e-docs plan)
• All 10 acceptance criteria from issue #190 verified against the diff
• Step count remains at 10 (2 removed, 2 added)
• Run /update-docs on next PR merge to validate the new flow end-to-end

Review Checklist

• No stale plan/phase/Epilogue/sprint references remain
• Gather Context fields match board-driven workflow
• Project page step references current template sections (Status, Milestones)
• Validation column gate included (Step 6) before done (Step 7)
• MCP restart step included (Step 3)
• Nit-bundle uses board backlog, not plan Epilogue
• Traceability chain rewritten for board-driven flow
• Completion summary template matches new steps

Related Notes

• sop-post-merge-docs -- the SOP note (pal-e-docs, separate update needed)
• skill-update-docs -- the SKILL.md (pal-e-docs, separate update needed)
• convention-kanban-over-plans -- the shift this command now reflects

Related

Closes #190

## Summary Fully deprecates the plan/phase-driven path in `commands/update-docs.md` per `convention-kanban-over-plans`. Replaces stale plan/phase steps with MCP restart check and production validation steps, fixes project page references to current template sections, and rewrites the traceability chain for board-driven flow. ## Changes - `commands/update-docs.md` -- rewritten from 10 plan-era steps to 10 board-driven steps: - **Removed** Steps 3-4 (phase note update, plan note update) -- plans are deprecated - **Removed** `phase-slug` and `plan-slug` from Gather Context - **Added** Step 3: MCP Restart Check for schema-changing merges - **Updated** Step 4 (Project Page): references Status + Milestones sections (not stale "Issues table" / "Roadmap") - **Updated** Step 4: uses `get_section` + `update_block` for surgical edits (not `update_note`) - **Split** old Step 7 into Step 6 (move to `validation` column) and Step 7 (production validation before `done`) - **Updated** Step 9 (Nit-bundle): nits go to board backlog, not plan Epilogue - **Replaced** Traceability Chain section: `Forgejo Issue -> PR -> Board Item -> Project Page` with label-based traceability (`story:`, `arch:`, `type:`) - **Updated** completion summary template to match new step numbering ## Test Plan - [ ] Grep for stale references: `grep -iE 'phase|plan|Epilogue|Roadmap|Issues table|sprint|get_sprint|move_sprint' commands/update-docs.md` returns only `tofu plan` (the CLI command, not a pal-e-docs plan) - [ ] All 10 acceptance criteria from issue #190 verified against the diff - [ ] Step count remains at 10 (2 removed, 2 added) - [ ] Run `/update-docs` on next PR merge to validate the new flow end-to-end ## Review Checklist - [x] No stale plan/phase/Epilogue/sprint references remain - [x] Gather Context fields match board-driven workflow - [x] Project page step references current template sections (Status, Milestones) - [x] Validation column gate included (Step 6) before done (Step 7) - [x] MCP restart step included (Step 3) - [x] Nit-bundle uses board backlog, not plan Epilogue - [x] Traceability chain rewritten for board-driven flow - [x] Completion summary template matches new steps ## Related Notes - `sop-post-merge-docs` -- the SOP note (pal-e-docs, separate update needed) - `skill-update-docs` -- the SKILL.md (pal-e-docs, separate update needed) - `convention-kanban-over-plans` -- the shift this command now reflects ## Related Closes #190

forgejo_admin added 1 commit 2026-03-28 11:52:02 +00:00

refactor: update post-merge command for board-driven workflow (#190) ... d7e439f808

Fully deprecate plan/phase-driven path per convention-kanban-over-plans.
Remove Steps 3-4 (phase/plan note updates), add MCP restart check and
production validation steps, fix project page references to current
template sections (Status + Milestones), update nit-bundle to use board
backlog instead of plan Epilogue, and rewrite traceability chain for
board-driven flow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented 2026-03-28 11:52:55 +00:00

Author

Contributor

Copy link

QA Review -- PR #207

Acceptance Criteria Verification (Issue #190)

#	Criterion	Status
1	SOP handles board-driven post-merge flow only (plan-driven fully deprecated)	PASS -- Steps 3-4 (phase/plan) removed, no plan/phase slugs in Gather Context
2	Steps reference current template-project-page sections	PASS -- Step 4 references Status + Milestones (not "Issues table" / "Roadmap")
3	Validation column step included between merge and done	PASS -- Step 6 (validation gate) + Step 7 (prod validation before done)
4	MCP restart step included for schema-changing merges	PASS -- Step 3 added
5	Nit-bundle references updated (no Epilogue reference)	PASS -- Step 9 uses "project board backlog"
6	No references to deprecated concepts	PASS -- grep for phase/plan/Epilogue/Roadmap/sprint returns only tofu plan (CLI command)
7	Traceability chain updated for board-driven flow	PASS -- New section: Forgejo Issue -> PR -> Board Item -> Project Page
8	skill-update-docs SKILL.md updated	N/A -- pal-e-docs entity, outside this PR scope
9	skill-update-docs stale MCP tool references replaced	N/A -- pal-e-docs entity, outside this PR scope
10	commands/update-docs.md updated to match corrected SOP steps	PASS -- 59 additions, 50 deletions

Stale Reference Grep

$ grep -iE 'phase|plan|Epilogue|Roadmap|Issues table|sprint|get_sprint|move_sprint' commands/update-docs.md
- **Infrastructure (tofu):** Verify resources exist (`tofu plan` shows no drift, ...

Only match is the tofu plan CLI command -- correct, not a pal-e-docs plan reference.

Nits

None found. The diff is clean and well-scoped.

Scope Note

ACs 8-9 (skill-update-docs SKILL.md + MCP tool references) are pal-e-docs entities that require get_section + update_block -- not code changes. They are explicitly called out in the PR body as "separate update needed." This PR correctly limits scope to the code file.

VERDICT: APPROVE

## QA Review -- PR #207 ### Acceptance Criteria Verification (Issue #190) | # | Criterion | Status | |---|-----------|--------| | 1 | SOP handles board-driven post-merge flow only (plan-driven fully deprecated) | PASS -- Steps 3-4 (phase/plan) removed, no plan/phase slugs in Gather Context | | 2 | Steps reference current template-project-page sections | PASS -- Step 4 references Status + Milestones (not "Issues table" / "Roadmap") | | 3 | Validation column step included between merge and done | PASS -- Step 6 (validation gate) + Step 7 (prod validation before done) | | 4 | MCP restart step included for schema-changing merges | PASS -- Step 3 added | | 5 | Nit-bundle references updated (no Epilogue reference) | PASS -- Step 9 uses "project board backlog" | | 6 | No references to deprecated concepts | PASS -- grep for phase/plan/Epilogue/Roadmap/sprint returns only `tofu plan` (CLI command) | | 7 | Traceability chain updated for board-driven flow | PASS -- New section: `Forgejo Issue -> PR -> Board Item -> Project Page` | | 8 | skill-update-docs SKILL.md updated | N/A -- pal-e-docs entity, outside this PR scope | | 9 | skill-update-docs stale MCP tool references replaced | N/A -- pal-e-docs entity, outside this PR scope | | 10 | commands/update-docs.md updated to match corrected SOP steps | PASS -- 59 additions, 50 deletions | ### Stale Reference Grep ``` $ grep -iE 'phase|plan|Epilogue|Roadmap|Issues table|sprint|get_sprint|move_sprint' commands/update-docs.md - **Infrastructure (tofu):** Verify resources exist (`tofu plan` shows no drift, ... ``` Only match is the `tofu plan` CLI command -- correct, not a pal-e-docs plan reference. ### Nits None found. The diff is clean and well-scoped. ### Scope Note ACs 8-9 (skill-update-docs SKILL.md + MCP tool references) are pal-e-docs entities that require `get_section` + `update_block` -- not code changes. They are explicitly called out in the PR body as "separate update needed." This PR correctly limits scope to the code file. **VERDICT: APPROVE**

forgejo_admin commented 2026-03-28 11:55:57 +00:00

Author

Contributor

Copy link

PR #207 Review

DOMAIN REVIEW

Tech stack: Markdown command file (Claude Code slash command). No executable code -- this is a procedural SOP document that drives agent behavior during /update-docs runs.

Scope: Single file change (commands/update-docs.md), +59/-50 lines. Rewrites the post-merge documentation chain from plan/phase-driven to board-driven workflow per convention-kanban-over-plans.

Correctness of changes:

1. Gather Context cleanup: Phase slug and plan slug removed. Board slug added with example (board-pal-e-agency). The fallback lookup guidance correctly updated from "phase note's Lineage header" to "board item's labels." Clean.

2. Step 3 replacement (Phase Note -> MCP Restart Check): Well-scoped. The decision criteria ("schema, database columns, note types, or any interface consumed by MCP servers") are specific enough to be actionable. Report format follows the established pattern.

3. Step 4 replacement (Plan Note -> Project Page, renumbered): The "Issues table" reference replaced with "Milestones" -- aligns with current project page templates. The method changed from update_note to get_section + update_block for surgical edits. This is a meaningful improvement -- surgical block edits are safer than full-note overwrites.

4. Step 6/7 split (Board Item -> Validation then Prod Validation -> Done): This is the most substantive change. The old single step ("move to done") is now a two-step gate: move to validation column first (Step 6), then validate in production (Step 7), then move to done. The validation scope guidance (infrastructure/backend/frontend/config) is practical. The "STOP if validation fails" guard is correct.

5. Step 9 (Nit-bundle): "Add a one-line reference in the plan's Epilogue section" replaced with "Add the nit-bundle issue to the project board backlog." Correct per feedback_nits_to_epilogue.md and the kanban-over-plans convention.

6. Completion summary template: All 10 steps match the new numbering and descriptions. The alignment formatting (padding with spaces) improves readability.

7. Traceability Chain section: New section added at the end. Forgejo Issue -> PR -> Board Item -> Project Page (Status + Milestones) is clear. The story:, arch:, type: label traceability aligns with feedback_traceability_triangle.md.

8. Terminology fix: "skill" -> "command" in the header and footer reference lines. Correct -- this file lives in commands/, not skills/.

Step count verification: 10 steps before, 10 steps after. 2 removed (Phase Note, Plan Note), 2 added (MCP Restart Check, Production Validation). Confirmed correct.

Stale reference audit: All phase, plan, Epilogue, Roadmap, Issues table, sprint, get_sprint, move_sprint references are removed from the changed lines. The only remaining references to ~/secrets/ and source are in the untouched Step 1 and Step 2 (pre-existing, properly using env vars).

BLOCKERS

None.

• No new functionality requiring test coverage (this is a documentation/SOP file, not executable code)
• No user input handling
• No secrets or credentials introduced
• No DRY violations in auth paths

NITS

1. Discovered scope -- hook terminology drift: /home/ldraney/claude-custom/hooks/remind-update-docs.sh line 40 still says "The /update-docs skill walks through..." while this PR changes the command file to say "command" instead of "skill." This is a separate file not in the PR scope, but creates a minor terminology inconsistency. Recommend a follow-up issue to align the hook wording.

2. Step 1 stale note about missing close_issue MCP tool: Line 36 says "There is no close_issue MCP tool." This was not introduced by this PR, but given that mcp__forgejo__update_issue now exists (it appeared in the tool list during this review), the curl workaround in Step 1 may be outdated. Out of scope for this PR, but worth noting as discovered scope.

3. Step 3 MCP Restart -- no "how": The step says "restart the affected MCP server process" but does not specify the mechanism (e.g., kill + relaunch, systemd restart, tmux session restart). The other steps that use shell commands include the exact commands. This step relies on the agent knowing how to restart MCP servers. Minor -- the agent context likely has this knowledge, but explicitness would match the style of Steps 1-2.

SOP COMPLIANCE

• Branch named after issue: 190-audit-post-merge-sop matches issue #190
• PR body has Summary, Changes, Test Plan, Related sections
• Related section references Closes #190
• No secrets committed -- no .env files, no credentials in diff
• No unnecessary file changes -- single file, tightly scoped to issue #190
• Commit message is descriptive: refactor: update post-merge command for board-driven workflow
• Related section does not reference a plan slug (N/A -- convention-kanban-over-plans means no plan slug expected)

PROCESS OBSERVATIONS

• Change failure risk: Low. This is a documentation/process file. If the new steps have gaps, the worst case is an incomplete /update-docs run, which is recoverable.
• Deployment frequency impact: Positive. The validation gate (Step 6 -> Step 7) adds a production verification checkpoint that should catch post-merge issues earlier.
• Documentation gap: The PR body notes that sop-post-merge-docs (pal-e-docs) and skill-update-docs (pal-e-docs) need separate updates to match. This is correctly flagged as out-of-scope in the Related Notes section.

VERDICT: APPROVED

## PR #207 Review ### DOMAIN REVIEW **Tech stack:** Markdown command file (Claude Code slash command). No executable code -- this is a procedural SOP document that drives agent behavior during `/update-docs` runs. **Scope:** Single file change (`commands/update-docs.md`), +59/-50 lines. Rewrites the post-merge documentation chain from plan/phase-driven to board-driven workflow per `convention-kanban-over-plans`. **Correctness of changes:** 1. **Gather Context cleanup:** Phase slug and plan slug removed. Board slug added with example (`board-pal-e-agency`). The fallback lookup guidance correctly updated from "phase note's Lineage header" to "board item's labels." Clean. 2. **Step 3 replacement (Phase Note -> MCP Restart Check):** Well-scoped. The decision criteria ("schema, database columns, note types, or any interface consumed by MCP servers") are specific enough to be actionable. Report format follows the established pattern. 3. **Step 4 replacement (Plan Note -> Project Page, renumbered):** The "Issues table" reference replaced with "Milestones" -- aligns with current project page templates. The method changed from `update_note` to `get_section` + `update_block` for surgical edits. This is a meaningful improvement -- surgical block edits are safer than full-note overwrites. 4. **Step 6/7 split (Board Item -> Validation then Prod Validation -> Done):** This is the most substantive change. The old single step ("move to done") is now a two-step gate: move to `validation` column first (Step 6), then validate in production (Step 7), then move to `done`. The validation scope guidance (infrastructure/backend/frontend/config) is practical. The "STOP if validation fails" guard is correct. 5. **Step 9 (Nit-bundle):** "Add a one-line reference in the plan's Epilogue section" replaced with "Add the nit-bundle issue to the project board backlog." Correct per `feedback_nits_to_epilogue.md` and the kanban-over-plans convention. 6. **Completion summary template:** All 10 steps match the new numbering and descriptions. The alignment formatting (padding with spaces) improves readability. 7. **Traceability Chain section:** New section added at the end. `Forgejo Issue -> PR -> Board Item -> Project Page (Status + Milestones)` is clear. The `story:`, `arch:`, `type:` label traceability aligns with `feedback_traceability_triangle.md`. 8. **Terminology fix:** "skill" -> "command" in the header and footer reference lines. Correct -- this file lives in `commands/`, not `skills/`. **Step count verification:** 10 steps before, 10 steps after. 2 removed (Phase Note, Plan Note), 2 added (MCP Restart Check, Production Validation). Confirmed correct. **Stale reference audit:** All `phase`, `plan`, `Epilogue`, `Roadmap`, `Issues table`, `sprint`, `get_sprint`, `move_sprint` references are removed from the changed lines. The only remaining references to `~/secrets/` and `source` are in the untouched Step 1 and Step 2 (pre-existing, properly using env vars). ### BLOCKERS None. - No new functionality requiring test coverage (this is a documentation/SOP file, not executable code) - No user input handling - No secrets or credentials introduced - No DRY violations in auth paths ### NITS 1. **Discovered scope -- hook terminology drift:** `/home/ldraney/claude-custom/hooks/remind-update-docs.sh` line 40 still says "The /update-docs skill walks through..." while this PR changes the command file to say "command" instead of "skill." This is a separate file not in the PR scope, but creates a minor terminology inconsistency. Recommend a follow-up issue to align the hook wording. 2. **Step 1 stale note about missing `close_issue` MCP tool:** Line 36 says "There is no `close_issue` MCP tool." This was not introduced by this PR, but given that `mcp__forgejo__update_issue` now exists (it appeared in the tool list during this review), the curl workaround in Step 1 may be outdated. Out of scope for this PR, but worth noting as discovered scope. 3. **Step 3 MCP Restart -- no "how":** The step says "restart the affected MCP server process" but does not specify the mechanism (e.g., `kill` + relaunch, systemd restart, tmux session restart). The other steps that use shell commands include the exact commands. This step relies on the agent knowing how to restart MCP servers. Minor -- the agent context likely has this knowledge, but explicitness would match the style of Steps 1-2. ### SOP COMPLIANCE - [x] Branch named after issue: `190-audit-post-merge-sop` matches issue #190 - [x] PR body has Summary, Changes, Test Plan, Related sections - [x] Related section references `Closes #190` - [x] No secrets committed -- no `.env` files, no credentials in diff - [x] No unnecessary file changes -- single file, tightly scoped to issue #190 - [x] Commit message is descriptive: `refactor: update post-merge command for board-driven workflow` - [ ] Related section does not reference a plan slug (N/A -- `convention-kanban-over-plans` means no plan slug expected) ### PROCESS OBSERVATIONS - **Change failure risk:** Low. This is a documentation/process file. If the new steps have gaps, the worst case is an incomplete `/update-docs` run, which is recoverable. - **Deployment frequency impact:** Positive. The validation gate (Step 6 -> Step 7) adds a production verification checkpoint that should catch post-merge issues earlier. - **Documentation gap:** The PR body notes that `sop-post-merge-docs` (pal-e-docs) and `skill-update-docs` (pal-e-docs) need separate updates to match. This is correctly flagged as out-of-scope in the Related Notes section. ### VERDICT: APPROVED

forgejo_admin merged commit 9309987d6e into main 2026-03-28 11:56:34 +00:00

forgejo_admin deleted branch 190-audit-post-merge-sop 2026-03-28 11:56:34 +00:00

forgejo_admin referenced this pull request from a commit 2026-03-28 11:56:35 +00:00

refactor: update post-merge command for board-driven workflow (#207)

forgejo_admin referenced this pull request 2026-03-28 12:08:55 +00:00

Validate session 2026-03-28 merges (9 PRs) #208

forgejo_admin referenced this pull request 2026-03-28 22:46:04 +00:00

Validate session 2026-03-28 merges (9 PRs) #208

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

domain:backend

  

domain:devops

  

domain:frontend

  

status:approved

QA passed, awaiting merge approval

  

status:in-progress

Dev agent is actively working

  

status:needs-fix

QA found issues, back to dev

  

status:qa

PR submitted, awaiting QA review

  

type:bug

Bug fix

  

type:devops

Infrastructure/CI/config work

  

type:feature

New functionality

No labels

domain:backend

domain:devops

domain:frontend

status:approved

status:in-progress

status:needs-fix

status:qa

type:bug

type:devops

type:feature

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

ldraney/claude-custom!207

No description provided.