ldraney/claude-custom

Fork 0

Audit post-merge SOP for board-driven (non-plan) workflow #190

New issue

Closed

opened 2026-03-28 03:55:02 +00:00 by forgejo_admin · 3 comments

forgejo_admin commented

2026-03-28 03:55:02 +00:00

Contributor

Type

Task

Lineage

Standalone — discovered during PR #226 post-merge flow

Repo

forgejo_admin/claude-custom

Scope

The 10-step post-merge checklist in sop-post-merge-docs assumes plan/phase-driven work (steps 3-4: "update phase note", "update plan note"). With the kanban-over-plans shift, most work is now board-driven — tickets on boards, not phases in plans. The SOP needs to be audited and updated for both workflows.

The skill-update-docs SKILL.md executes these same steps — if only the SOP note is updated, agents continue running the stale workflow. Both artifacts must be updated in lockstep.

The commands/update-docs.md command file (180 lines) is the third artifact agents execute — it contains the same stale plan/phase references and must be updated in lockstep with the SOP note and SKILL.md.

Specific issues found during PR #226 post-merge:

Steps 3-4 don't apply to board-driven work (no phase or plan to update). SOP should branch: "if plan-driven, do steps 3-4; if board-driven, update spike/board note status."
Step 5 references "Issues table" and "Roadmap" on project pages — the current template-project-page has neither. Project pages have Vision, User Stories, Architecture, Board, Status, Milestones, Repos.
Step 6 says sync_board — correct, but doesn't mention moving the board item to validation column (the new right gate) before done.
Step 8 (nit-bundle) — references "plan Epilogue" which is a legacy concept. Nits should just be Forgejo issues on the board backlog.
Missing: MCP restart step — when the merged code changes the API schema (new types, new columns), the MCP server needs a restart. This isn't in the SOP.
Missing: validation step — the new validation column in the kanban means post-merge should include production validation (per template-validation) before moving to done. The SOP ends at "sync board + move to done" without validation.
Traceability chain section has stale references — the the-traceability-chain section in the SOP references "Phase note → Plan note → Issues table/Roadmap" which are deprecated concepts. Must be updated to reflect board-driven traceability.

Resolved: Fully deprecate plan-driven path. Per convention-kanban-over-plans, plans are obsolete. Remove all plan/phase references from the SOP.

File Targets

sop-post-merge-docs — the SOP note (via get_section + update_block)
skill-update-docs — the SKILL.md that agents execute (mirrors the SOP checklist)
commands/update-docs.md — the 180-line command file agents execute (has same stale plan/phase references)

Acceptance Criteria

SOP handles board-driven post-merge flow only (plan-driven path fully deprecated)
Steps reference current template-project-page sections (not stale ones)
Validation column step included between merge and done
MCP restart step included for schema-changing merges
Nit-bundle references updated (no Epilogue reference)
No references to deprecated concepts (Roadmap table, plan Epilogue)
the-traceability-chain section updated for board-driven flow
skill-update-docs SKILL.md updated to match corrected SOP steps
skill-update-docs references to get_sprint_board and move_sprint_item replaced with list_board_items and update_board_item
commands/update-docs.md updated to match corrected SOP steps

Constraints

Use get_section + update_block for surgical edits to the SOP note — no full rewrites
Forgejo read-only for context; all doc changes via mcp__pal-e-docs__* tools
commands/update-docs.md is a code file — changes go through normal branch/PR flow on claude-custom

project-pal-e-agency
sop-post-merge-docs — the SOP to update
skill-update-docs — the skill that executes the SOP
commands/update-docs.md — the command file that executes the SOP
sop-board-workflow — column semantics (validation column)
template-validation — validation note structure
convention-kanban-over-plans — the shift this SOP needs to reflect

### Type Task ### Lineage Standalone — discovered during PR #226 post-merge flow ### Repo `forgejo_admin/claude-custom` ### Scope The 10-step post-merge checklist in `sop-post-merge-docs` assumes plan/phase-driven work (steps 3-4: "update phase note", "update plan note"). With the kanban-over-plans shift, most work is now board-driven — tickets on boards, not phases in plans. The SOP needs to be audited and updated for both workflows. The `skill-update-docs` SKILL.md executes these same steps — if only the SOP note is updated, agents continue running the stale workflow. Both artifacts must be updated in lockstep. The `commands/update-docs.md` command file (180 lines) is the third artifact agents execute — it contains the same stale plan/phase references and must be updated in lockstep with the SOP note and SKILL.md. Specific issues found during PR #226 post-merge: 1. **Steps 3-4 don't apply** to board-driven work (no phase or plan to update). SOP should branch: "if plan-driven, do steps 3-4; if board-driven, update spike/board note status." 2. **Step 5 references "Issues table" and "Roadmap"** on project pages — the current template-project-page has neither. Project pages have Vision, User Stories, Architecture, Board, Status, Milestones, Repos. 3. **Step 6 says sync_board** — correct, but doesn't mention moving the board item to `validation` column (the new right gate) before `done`. 4. **Step 8 (nit-bundle)** — references "plan Epilogue" which is a legacy concept. Nits should just be Forgejo issues on the board backlog. 5. **Missing: MCP restart step** — when the merged code changes the API schema (new types, new columns), the MCP server needs a restart. This isn't in the SOP. 6. **Missing: validation step** — the new `validation` column in the kanban means post-merge should include production validation (per template-validation) before moving to done. The SOP ends at "sync board + move to done" without validation. 7. **Traceability chain section has stale references** — the `the-traceability-chain` section in the SOP references "Phase note → Plan note → Issues table/Roadmap" which are deprecated concepts. Must be updated to reflect board-driven traceability. **Resolved:** Fully deprecate plan-driven path. Per convention-kanban-over-plans, plans are obsolete. Remove all plan/phase references from the SOP. ### File Targets - `sop-post-merge-docs` — the SOP note (via `get_section` + `update_block`) - `skill-update-docs` — the SKILL.md that agents execute (mirrors the SOP checklist) - `commands/update-docs.md` — the 180-line command file agents execute (has same stale plan/phase references) ### Acceptance Criteria - [ ] SOP handles board-driven post-merge flow only (plan-driven path fully deprecated) - [ ] Steps reference current template-project-page sections (not stale ones) - [ ] Validation column step included between merge and done - [ ] MCP restart step included for schema-changing merges - [ ] Nit-bundle references updated (no Epilogue reference) - [ ] No references to deprecated concepts (Roadmap table, plan Epilogue) - [ ] `the-traceability-chain` section updated for board-driven flow - [ ] `skill-update-docs` SKILL.md updated to match corrected SOP steps - [ ] `skill-update-docs` references to `get_sprint_board` and `move_sprint_item` replaced with `list_board_items` and `update_board_item` - [ ] `commands/update-docs.md` updated to match corrected SOP steps ### Constraints - Use `get_section` + `update_block` for surgical edits to the SOP note — no full rewrites - Forgejo read-only for context; all doc changes via `mcp__pal-e-docs__*` tools - `commands/update-docs.md` is a code file — changes go through normal branch/PR flow on `claude-custom` ### Related - `project-pal-e-agency` - `sop-post-merge-docs` — the SOP to update - `skill-update-docs` — the skill that executes the SOP - `commands/update-docs.md` — the command file that executes the SOP - `sop-board-workflow` — column semantics (validation column) - `template-validation` — validation note structure - `convention-kanban-over-plans` — the shift this SOP needs to reflect

forgejo_admin commented

2026-03-28 05:45:57 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-506-2026-03-27

All 6 issues enumerated in the Scope section were verified against the current SOP — every claim is accurate. Traceability is complete (story:pm-scope, arch:note-system, Forgejo issue open). No blockers or dependencies.

Issues found:

[BODY] Blast radius: skill-update-docs has identical stale patterns — the skill is what agents actually execute. If only the SOP is updated, agents continue running the stale workflow. Add skill-update-docs to scope and deliverables.
[BODY] Missing AC for traceability chain code block — section the-traceability-chain in the SOP also has stale "Phase note → Plan note → Issues table/Roadmap" references. Add AC to cover it.
[BODY] Add Constraints section: "Use get_section + update_block for surgical edits."
[SCOPE] Clarify plan-driven path retention — Should the SOP branch (plan-driven vs board-driven) or fully deprecate plan references? convention-kanban-over-plans says plans are deprecated, but legacy plan phases still exist on boards.

## Scope Review: NEEDS_REFINEMENT Review note: `review-506-2026-03-27` All 6 issues enumerated in the Scope section were verified against the current SOP — every claim is accurate. Traceability is complete (story:pm-scope, arch:note-system, Forgejo issue open). No blockers or dependencies. **Issues found:** - `[BODY]` **Blast radius: `skill-update-docs` has identical stale patterns** — the skill is what agents actually execute. If only the SOP is updated, agents continue running the stale workflow. Add `skill-update-docs` to scope and deliverables. - `[BODY]` **Missing AC for traceability chain code block** — section `the-traceability-chain` in the SOP also has stale "Phase note → Plan note → Issues table/Roadmap" references. Add AC to cover it. - `[BODY]` Add Constraints section: "Use get_section + update_block for surgical edits." - `[SCOPE]` **Clarify plan-driven path retention** — Should the SOP branch (plan-driven vs board-driven) or fully deprecate plan references? `convention-kanban-over-plans` says plans are deprecated, but legacy plan phases still exist on boards.

forgejo_admin commented

2026-03-28 11:41:45 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-506-2026-03-27
Scope is strong but missing a critical file target and has one stale AC.

Issues found:

commands/update-docs.md (the actual command file agents execute) is not in File Targets -- if only the pal-e-docs notes are updated, agents will continue running the stale workflow
AC 1 says "handles both plan-driven and board-driven" but the Resolved section says "fully deprecate plan-driven path" -- contradicts itself
Constraints claim "No code changes" but commands/update-docs.md IS a code file in this repo
skill-update-docs pal-e-docs note has stale MCP tool references (get_sprint_board, move_sprint_item) not mentioned in scope
Missing template sections: Lineage, Repo headers

Action items (all [BODY] fixes):

Add commands/update-docs.md to File Targets
Fix AC 1 to match the deprecation decision
Add AC 9 for commands/update-docs.md updates
Add AC 10 for skill-update-docs MCP tool table cleanup
Update Constraints to acknowledge the code file change
Add Lineage + Repo headers

## Scope Review: NEEDS_REFINEMENT Review note: `review-506-2026-03-27` Scope is strong but missing a critical file target and has one stale AC. **Issues found:** - `commands/update-docs.md` (the actual command file agents execute) is not in File Targets -- if only the pal-e-docs notes are updated, agents will continue running the stale workflow - AC 1 says "handles both plan-driven and board-driven" but the Resolved section says "fully deprecate plan-driven path" -- contradicts itself - Constraints claim "No code changes" but `commands/update-docs.md` IS a code file in this repo - `skill-update-docs` pal-e-docs note has stale MCP tool references (get_sprint_board, move_sprint_item) not mentioned in scope - Missing template sections: Lineage, Repo headers **Action items (all [BODY] fixes):** 1. Add `commands/update-docs.md` to File Targets 2. Fix AC 1 to match the deprecation decision 3. Add AC 9 for commands/update-docs.md updates 4. Add AC 10 for skill-update-docs MCP tool table cleanup 5. Update Constraints to acknowledge the code file change 6. Add Lineage + Repo headers

forgejo_admin commented

2026-03-28 11:48:25 +00:00

Author

Contributor

Scope Review v3: READY

Review note: review-506-2026-03-27-v3

All 5 v2 fixes verified: Lineage+Repo headers present, AC contradiction resolved (plan-driven fully deprecated), constraints corrected, stale MCP tool AC added, commands/update-docs.md included as third file target.

File targets: All 3 verified — stale plan/phase/Epilogue/sprint references confirmed in sop-post-merge-docs, skill-update-docs, and commands/update-docs.md.
Traceability: Complete (story:pm-scope, arch:note-system, issue open).
Dependencies: All 3 prerequisites done (#397, #487, #480).
Decomposition: Not needed — 3 tightly-coupled targets, estimated ~4 min agent pass.

Minor non-blocking observations:

[BODY] Consider adding ### Test Expectations with grep verification terms
[BODY] Consider adding ### Checklist (standard items)

## Scope Review v3: READY Review note: `review-506-2026-03-27-v3` All 5 v2 fixes verified: Lineage+Repo headers present, AC contradiction resolved (plan-driven fully deprecated), constraints corrected, stale MCP tool AC added, commands/update-docs.md included as third file target. **File targets:** All 3 verified — stale plan/phase/Epilogue/sprint references confirmed in `sop-post-merge-docs`, `skill-update-docs`, and `commands/update-docs.md`. **Traceability:** Complete (story:pm-scope, arch:note-system, issue open). **Dependencies:** All 3 prerequisites done (#397, #487, #480). **Decomposition:** Not needed — 3 tightly-coupled targets, estimated ~4 min agent pass. Minor non-blocking observations: - `[BODY]` Consider adding `### Test Expectations` with grep verification terms - `[BODY]` Consider adding `### Checklist` (standard items)