Add /update-docs custom command for post-merge docs #72
No reviewers
Labels
No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
ldraney/claude-custom!72
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "71-add-update-docs-slash-command-for-post-m"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Creates the first custom slash command (
commands/update-docs.md) that walks the 7-step post-merge traceability chain fromsop-post-merge-docs. This is the command thatremind-update-docs.shtells agents to run after every PR merge.Changes
commands/update-docs.md(new): Self-contained prompt that walks the full traceability chain -- close Forgejo issue, update phase note, update plan note, update project page, move sprint board item, update memory, capture discovered scope. Asks for context (PR number, phase/plan slugs) if not already known. Idempotent. Referencesskill-update-docspal-e-docs note as canonical source.README.md: Added "Custom Commands" section documenting thecommands/directory convention, deploy process, and the distinction between commands and skills.Test Plan
~/.claude/commands->~/claude-custom/commands//update-docsappears in the Claude Code command list/update-docsafter a test merge and verify it walks through all 7 stepsReview Checklist
Related
plan-2026-02-26-tf-modularize-postgres-- Phase 7f-7 post-merge automationPR #72 Review
BLOCKERS
1. Step 1 uses raw
curlinstead of MCP tools for issue closing.The command instructs the agent to close the Forgejo issue via a raw
curlcommand referencing$FORGEJO_TOKENand the hardcoded domainforgejo.tail5b443a.ts.net. This is fragile for several reasons:$FORGEJO_TOKENin their environment.curlapproach bypasses the MCP tool layer, which is the standard interface for all Forgejo operations in this platform.I checked the Forgejo MCP tool list and there does not appear to be a dedicated
close_issuetool. However,mcp__forgejo__list_issuesis referenced correctly for checking state. The fix here is either:Bashwith thecurlcommand but source credentials from~/secrets/pal-e-services/forgejo.envper the CLAUDE.md platform detection convention, rather than assuming$FORGEJO_TOKENexists.Without one of these, an agent following this prompt will likely fail at Step 1 when
$FORGEJO_TOKENis undefined.NITS
1. Potential double-reminder for sprint board updates. Both
remind-update-docs.shandremind-sprint-update.shfire onmcp__forgejo__merge_approved_pr. If the agent follows/update-docs(which includes Step 5: sprint board move), the separate sprint reminder hook will also fire. The sprint move is idempotent so this is not a bug, but it creates noise. Consider noting this in the command or eventually deduplicating the hooks.2. The "Commands vs Skills" section in the README references skills that do not exist yet. The
skills/directory has noSKILL.mdfiles currently. The distinction is still useful documentation for future convention, but it is forward-looking. A minor note like "(no skills exist yet -- this establishes the convention)" would make the current state clearer.3. The Gather Context section could prompt for repo owner explicitly. The context list asks for "PR number and repo (owner/repo)" but the curl command template uses
{owner}and{repo}as separate placeholders. A small clarity improvement would be splitting them: "Repo owner" and "Repo name" as separate items, matching the curl template and the MCP tool parameters.4. Step 6 (Update Memory) tells the agent to "edit only the relevant sections" but does not specify which tool to use. Steps 2-5 and 7 all name their MCP tools explicitly. Step 6 breaks this pattern. Adding "Use
ReadandEdit" (or equivalent) would maintain consistency.SOP COMPLIANCE
71-add-update-docs-slash-command-for-post-mreferences issue #71)plan-2026-02-26-tf-modularize-postgres)sop-post-merge-docsare coveredskill-update-docsas canonical sourceremind-update-docs.shhook (hook tells agent to run/update-docs)VERDICT: NOT APPROVED
The single blocker is the raw
curlapproach for issue closing in Step 1. An agent following this prompt will encounter an undefined$FORGEJO_TOKENin most execution contexts. This needs either a workaround annotation with proper credential sourcing, or an acknowledgment that the MCP gap exists with a filed issue. The rest of the command is well-structured, covers all 7 SOP steps, and establishes a solid convention for the first custom command in the repo.QA Review Fixes Applied
All findings from the review have been addressed in commit
8527469:BLOCKER Fixed
$FORGEJO_TOKENassumption withsource ~/secrets/pal-e-services/forgejo.envper platform convention. Replaced hardcodedforgejo.tail5b443a.ts.netdomain with$FORGEJO_URLfrom the env file. Added a note documenting the missingclose_issueMCP tool gap.Nits Fixed
remind-sprint-update.shalso fires on merge, producing a harmless but potentially noisy duplicate reminder.ReadandEdittools, matching the pattern used in Steps 2-5 and 7.PR #72 Re-Review
Re-review after dev agent addressed findings from the first review.
Previous Findings Status
~/secrets/pal-e-services/forgejo.envbefore using$FORGEJO_TOKENand$FORGEJO_URL. Both variables are confirmed present in that file.remind-sprint-update.shoverlap and why it is harmless.ReadandEditas the tools to use.BLOCKERS
1. Naming collision with existing
/update-docsskillThe file
skills/update-docs/SKILL.mdalready exists on main and registers as/update-docs. This PR addscommands/update-docs.mdwhich also registers as/update-docs. The PR does not remove or modify the existing skill.These two have different designs:
get_note(slug="skill-update-docs")Having both registered under the same name creates ambiguity. Claude Code's resolution behavior when a command and skill share a name is undefined and likely to confuse agents. Either:
skills/update-docs/SKILL.md(the command supersedes it), orThis must be resolved before merge. Pick one canonical
/update-docsimplementation.NITS
1. Auth pattern inconsistency -- Step 1 uses token auth (
Authorization: token $FORGEJO_TOKEN) while every function inhooks/forgejo-helper.shuses basic auth (-u "$FORGEJO_USER:$FORGEJO_PASSWORD"). Both work, but a future reader may wonder which is correct. Consider using the same pattern asforgejo-helper.shfor consistency, or add a one-line comment explaining why token auth is used here. Non-blocking.SOP COMPLIANCE
71-add-update-docs-slash-command-for-post-mreferences #71)plan-2026-02-26-tf-modularize-postgres)VERDICT: NOT APPROVED
The previous blocker is fixed but a new blocker emerged: naming collision between the new command and the existing
skills/update-docs/SKILL.mdskill. One must be removed or renamed. Once that is resolved this is ready to merge.QA Re-Review Fixes Applied
Commit
5c301b2addresses both findings from the re-review:BLOCKER Fixed: Naming collision
skills/update-docs/SKILL.md-- this was a 2-line pointer that delegated tomcp__pal-e-docs__get_note(slug="skill-update-docs"). The newcommands/update-docs.mdis the complete, self-contained replacement with all 7 SOP steps inline. Only one/update-docsregistration now exists.Nit Fixed: Auth pattern inconsistency
-u "$FORGEJO_USER:$FORGEJO_PASSWORD") matching the pattern inhooks/forgejo-helper.sh, instead of token auth (Authorization: token $FORGEJO_TOKEN). Added a note in the command explaining this alignment.Additional fix
skills/. Updated the Commands vs Skills section to accurately describe the relationship: skills delegate to pal-e-docs, commands are self-contained replacements for agents without pal-e-docs access.PR #72 Review (Round 3 -- Final)
Previous Findings Verification
All issues from rounds 1 and 2 are resolved:
~/secrets/pal-e-services/forgejo.envbefore the curl call (line 29).skills/update-docs/SKILL.md) -- FIXED. The file is deleted in this diff (-16 lines). Theskills/directory is now empty.-u "$FORGEJO_USER:$FORGEJO_PASSWORD"matching the established pattern inhooks/forgejo-helper.sh.commands/directory, conventions, deploy process, and the commands-vs-skills distinction.BLOCKERS
None.
NITS
None. LGTM.
SOP COMPLIANCE
71-add-update-docs-slash-command-for-post-mreferences issue #71)plan-2026-02-26-tf-modularize-postgres)~/secrets/pal-e-services/forgejo.env)VERDICT: APPROVED