Add /update-docs custom command for post-merge docs #72

Merged
forgejo_admin merged 3 commits from 71-add-update-docs-slash-command-for-post-m into main 2026-03-08 19:59:12 +00:00
Contributor

Summary

Creates the first custom slash command (commands/update-docs.md) that walks the 7-step post-merge traceability chain from sop-post-merge-docs. This is the command that remind-update-docs.sh tells 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. References skill-update-docs pal-e-docs note as canonical source.
  • README.md: Added "Custom Commands" section documenting the commands/ directory convention, deploy process, and the distinction between commands and skills.

Test Plan

  • Verify symlink exists: ~/.claude/commands -> ~/claude-custom/commands/
  • Confirm /update-docs appears in the Claude Code command list
  • Run /update-docs after a test merge and verify it walks through all 7 steps
  • Verify the command asks for missing context when not already in conversation
  • No regressions in existing skills or hooks

Review Checklist

  • Passed automated review-fix loop
  • No secrets committed
  • No unnecessary file changes
  • Commit messages are descriptive
  • Closes forgejo_admin/claude-custom #71
  • plan-2026-02-26-tf-modularize-postgres -- Phase 7f-7 post-merge automation
## Summary Creates the first custom slash command (`commands/update-docs.md`) that walks the 7-step post-merge traceability chain from `sop-post-merge-docs`. This is the command that `remind-update-docs.sh` tells 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. References `skill-update-docs` pal-e-docs note as canonical source. - `README.md`: Added "Custom Commands" section documenting the `commands/` directory convention, deploy process, and the distinction between commands and skills. ## Test Plan - [ ] Verify symlink exists: `~/.claude/commands` -> `~/claude-custom/commands/` - [ ] Confirm `/update-docs` appears in the Claude Code command list - [ ] Run `/update-docs` after a test merge and verify it walks through all 7 steps - [ ] Verify the command asks for missing context when not already in conversation - [ ] No regressions in existing skills or hooks ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive ## Related - Closes forgejo_admin/claude-custom #71 - `plan-2026-02-26-tf-modularize-postgres` -- Phase 7f-7 post-merge automation
Creates the first custom command in commands/update-docs.md that walks the
7-step post-merge traceability chain from sop-post-merge-docs. The command
gathers context (PR number, phase/plan/project slugs), then walks through
closing the Forgejo issue, updating phase/plan/project notes, moving sprint
board items, updating memory, and capturing discovered scope.

Also documents the commands/ directory convention in README.md, including
the distinction between commands (self-contained prompts) and skills
(frontmatter-enabled, delegate to pal-e-docs).

Closes #71

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Author
Contributor

PR #72 Review

BLOCKERS

1. Step 1 uses raw curl instead of MCP tools for issue closing.

The command instructs the agent to close the Forgejo issue via a raw curl command referencing $FORGEJO_TOKEN and the hardcoded domain forgejo.tail5b443a.ts.net. This is fragile for several reasons:

  • Agents running as subagents or in forked contexts may not have $FORGEJO_TOKEN in their environment.
  • The curl approach bypasses the MCP tool layer, which is the standard interface for all Forgejo operations in this platform.
  • The hardcoded domain ties the command to a specific Tailscale deployment.

I checked the Forgejo MCP tool list and there does not appear to be a dedicated close_issue tool. However, mcp__forgejo__list_issues is referenced correctly for checking state. The fix here is either:

  • (a) Add a note that this is a known workaround due to missing MCP close-issue tool, and file an issue for the gap, OR
  • (b) Use Bash with the curl command but source credentials from ~/secrets/pal-e-services/forgejo.env per the CLAUDE.md platform detection convention, rather than assuming $FORGEJO_TOKEN exists.

Without one of these, an agent following this prompt will likely fail at Step 1 when $FORGEJO_TOKEN is undefined.

NITS

1. Potential double-reminder for sprint board updates. Both remind-update-docs.sh and remind-sprint-update.sh fire on mcp__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 no SKILL.md files 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 Read and Edit" (or equivalent) would maintain consistency.

SOP COMPLIANCE

  • Branch named after issue (71-add-update-docs-slash-command-for-post-m references issue #71)
  • PR body follows template (Summary, Changes, Test Plan, Related all present)
  • Related references plan slug (plan-2026-02-26-tf-modularize-postgres)
  • No secrets committed (no tokens, passwords, or .env files in diff)
  • No unnecessary file changes (only 2 files: the command and the README update)
  • All 7 SOP steps from sop-post-merge-docs are covered
  • Command references skill-update-docs as canonical source
  • Idempotency addressed (each step has skip-if-already-done language)
  • Aligns with remind-update-docs.sh hook (hook tells agent to run /update-docs)

VERDICT: NOT APPROVED

The single blocker is the raw curl approach for issue closing in Step 1. An agent following this prompt will encounter an undefined $FORGEJO_TOKEN in 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.

## PR #72 Review ### BLOCKERS **1. Step 1 uses raw `curl` instead of MCP tools for issue closing.** The command instructs the agent to close the Forgejo issue via a raw `curl` command referencing `$FORGEJO_TOKEN` and the hardcoded domain `forgejo.tail5b443a.ts.net`. This is fragile for several reasons: - Agents running as subagents or in forked contexts may not have `$FORGEJO_TOKEN` in their environment. - The `curl` approach bypasses the MCP tool layer, which is the standard interface for all Forgejo operations in this platform. - The hardcoded domain ties the command to a specific Tailscale deployment. I checked the Forgejo MCP tool list and there does not appear to be a dedicated `close_issue` tool. However, `mcp__forgejo__list_issues` is referenced correctly for checking state. The fix here is either: - (a) Add a note that this is a known workaround due to missing MCP close-issue tool, and file an issue for the gap, OR - (b) Use `Bash` with the `curl` command but source credentials from `~/secrets/pal-e-services/forgejo.env` per the CLAUDE.md platform detection convention, rather than assuming `$FORGEJO_TOKEN` exists. Without one of these, an agent following this prompt will likely fail at Step 1 when `$FORGEJO_TOKEN` is undefined. ### NITS **1. Potential double-reminder for sprint board updates.** Both `remind-update-docs.sh` and `remind-sprint-update.sh` fire on `mcp__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 no `SKILL.md` files 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 `Read` and `Edit`" (or equivalent) would maintain consistency. ### SOP COMPLIANCE - [x] Branch named after issue (`71-add-update-docs-slash-command-for-post-m` references issue #71) - [x] PR body follows template (Summary, Changes, Test Plan, Related all present) - [x] Related references plan slug (`plan-2026-02-26-tf-modularize-postgres`) - [x] No secrets committed (no tokens, passwords, or .env files in diff) - [x] No unnecessary file changes (only 2 files: the command and the README update) - [x] All 7 SOP steps from `sop-post-merge-docs` are covered - [x] Command references `skill-update-docs` as canonical source - [x] Idempotency addressed (each step has skip-if-already-done language) - [x] Aligns with `remind-update-docs.sh` hook (hook tells agent to run `/update-docs`) ### VERDICT: NOT APPROVED The single blocker is the raw `curl` approach for issue closing in Step 1. An agent following this prompt will encounter an undefined `$FORGEJO_TOKEN` in 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.
Address blocker and nits from PR #72 review:

- BLOCKER: Replace raw curl with proper credential sourcing from
  ~/secrets/pal-e-services/forgejo.env, use $FORGEJO_URL instead of
  hardcoded domain, and document the missing close_issue MCP tool gap
- Nit 1: Add note about remind-sprint-update.sh hook overlap in Step 5
- Nit 2: Add parenthetical noting no skills exist yet in README
- Nit 3: Split "PR number and repo" into separate owner/name fields
  matching curl template placeholders
- Nit 4: Add explicit Read/Edit tool references to Step 6

Closes #71

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Author
Contributor

QA Review Fixes Applied

All findings from the review have been addressed in commit 8527469:

BLOCKER Fixed

  • Step 1 curl credentials: Replaced raw $FORGEJO_TOKEN assumption with source ~/secrets/pal-e-services/forgejo.env per platform convention. Replaced hardcoded forgejo.tail5b443a.ts.net domain with $FORGEJO_URL from the env file. Added a note documenting the missing close_issue MCP tool gap.

Nits Fixed

  1. Sprint hook overlap (Step 5): Added a note that remind-sprint-update.sh also fires on merge, producing a harmless but potentially noisy duplicate reminder.
  2. Skills convention (README): Added parenthetical "(No skills exist yet -- this establishes the convention for future use.)"
  3. Owner/repo split (Gather Context): Separated "PR number and repo (owner/repo)" into three distinct items -- "Repo owner", "Repo name", "PR number" -- matching the curl template placeholders and MCP tool parameters.
  4. Step 6 tool references: Changed "Read the memory file first, then edit" to explicitly name Read and Edit tools, matching the pattern used in Steps 2-5 and 7.
## QA Review Fixes Applied All findings from the review have been addressed in commit `8527469`: ### BLOCKER Fixed - **Step 1 curl credentials**: Replaced raw `$FORGEJO_TOKEN` assumption with `source ~/secrets/pal-e-services/forgejo.env` per platform convention. Replaced hardcoded `forgejo.tail5b443a.ts.net` domain with `$FORGEJO_URL` from the env file. Added a note documenting the missing `close_issue` MCP tool gap. ### Nits Fixed 1. **Sprint hook overlap (Step 5)**: Added a note that `remind-sprint-update.sh` also fires on merge, producing a harmless but potentially noisy duplicate reminder. 2. **Skills convention (README)**: Added parenthetical "(No skills exist yet -- this establishes the convention for future use.)" 3. **Owner/repo split (Gather Context)**: Separated "PR number and repo (owner/repo)" into three distinct items -- "Repo owner", "Repo name", "PR number" -- matching the curl template placeholders and MCP tool parameters. 4. **Step 6 tool references**: Changed "Read the memory file first, then edit" to explicitly name `Read` and `Edit` tools, matching the pattern used in Steps 2-5 and 7.
Author
Contributor

PR #72 Re-Review

Re-review after dev agent addressed findings from the first review.

Previous Findings Status

Finding Status
BLOCKER: Step 1 raw curl without sourcing credentials FIXED -- Step 1 now sources ~/secrets/pal-e-services/forgejo.env before using $FORGEJO_TOKEN and $FORGEJO_URL. Both variables are confirmed present in that file.
Nit 1: Sprint hook redundancy undocumented FIXED -- Step 5 now includes an explicit note about the remind-sprint-update.sh overlap and why it is harmless.
Nit 2: README skills section missing FIXED -- README now has a "Custom Commands" section with directory structure, conventions, deploy notes, and a "Commands vs Skills" comparison.
Nit 3: Context gathering clarity FIXED -- "Gather Context" section explicitly says to ask the user for missing values and to check PR body, issue body, or phase Lineage header.
Nit 4: Missing tool name in Step 6 FIXED -- Step 6 now explicitly names Read and Edit as the tools to use.

BLOCKERS

1. Naming collision with existing /update-docs skill

The file skills/update-docs/SKILL.md already exists on main and registers as /update-docs. This PR adds commands/update-docs.md which also registers as /update-docs. The PR does not remove or modify the existing skill.

These two have different designs:

  • The skill delegates to pal-e-docs: get_note(slug="skill-update-docs")
  • The command is self-contained with all 7 steps inline

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:

  • (a) Remove skills/update-docs/SKILL.md (the command supersedes it), or
  • (b) Rename the command to avoid the collision, or
  • (c) Keep the skill and drop the command if the delegation pattern is preferred

This must be resolved before merge. Pick one canonical /update-docs implementation.

NITS

1. Auth pattern inconsistency -- Step 1 uses token auth (Authorization: token $FORGEJO_TOKEN) while every function in hooks/forgejo-helper.sh uses basic auth (-u "$FORGEJO_USER:$FORGEJO_PASSWORD"). Both work, but a future reader may wonder which is correct. Consider using the same pattern as forgejo-helper.sh for consistency, or add a one-line comment explaining why token auth is used here. Non-blocking.

SOP COMPLIANCE

  • Branch named after issue (71-add-update-docs-slash-command-for-post-m references #71)
  • PR body has Summary, Changes, Test Plan, Related sections
  • Related references plan slug (plan-2026-02-26-tf-modularize-postgres)
  • No secrets committed (env file path referenced, not credentials)
  • No unnecessary file changes (2 files: command + README update)
  • Commit messages are descriptive

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.md skill. One must be removed or renamed. Once that is resolved this is ready to merge.

## PR #72 Re-Review Re-review after dev agent addressed findings from the first review. ### Previous Findings Status | Finding | Status | |---------|--------| | **BLOCKER: Step 1 raw curl without sourcing credentials** | FIXED -- Step 1 now sources `~/secrets/pal-e-services/forgejo.env` before using `$FORGEJO_TOKEN` and `$FORGEJO_URL`. Both variables are confirmed present in that file. | | Nit 1: Sprint hook redundancy undocumented | FIXED -- Step 5 now includes an explicit note about the `remind-sprint-update.sh` overlap and why it is harmless. | | Nit 2: README skills section missing | FIXED -- README now has a "Custom Commands" section with directory structure, conventions, deploy notes, and a "Commands vs Skills" comparison. | | Nit 3: Context gathering clarity | FIXED -- "Gather Context" section explicitly says to ask the user for missing values and to check PR body, issue body, or phase Lineage header. | | Nit 4: Missing tool name in Step 6 | FIXED -- Step 6 now explicitly names `Read` and `Edit` as the tools to use. | ### BLOCKERS **1. Naming collision with existing `/update-docs` skill** The file `skills/update-docs/SKILL.md` already exists on main and registers as `/update-docs`. This PR adds `commands/update-docs.md` which also registers as `/update-docs`. The PR does not remove or modify the existing skill. These two have different designs: - The **skill** delegates to pal-e-docs: `get_note(slug="skill-update-docs")` - The **command** is self-contained with all 7 steps inline 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: - (a) Remove `skills/update-docs/SKILL.md` (the command supersedes it), or - (b) Rename the command to avoid the collision, or - (c) Keep the skill and drop the command if the delegation pattern is preferred This must be resolved before merge. Pick one canonical `/update-docs` implementation. ### NITS **1. Auth pattern inconsistency** -- Step 1 uses token auth (`Authorization: token $FORGEJO_TOKEN`) while every function in `hooks/forgejo-helper.sh` uses basic auth (`-u "$FORGEJO_USER:$FORGEJO_PASSWORD"`). Both work, but a future reader may wonder which is correct. Consider using the same pattern as `forgejo-helper.sh` for consistency, or add a one-line comment explaining why token auth is used here. Non-blocking. ### SOP COMPLIANCE - [x] Branch named after issue (`71-add-update-docs-slash-command-for-post-m` references #71) - [x] PR body has Summary, Changes, Test Plan, Related sections - [x] Related references plan slug (`plan-2026-02-26-tf-modularize-postgres`) - [x] No secrets committed (env file path referenced, not credentials) - [x] No unnecessary file changes (2 files: command + README update) - [x] Commit messages are descriptive ### 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.md` skill. One must be removed or renamed. Once that is resolved this is ready to merge.
Remove skills/update-docs/SKILL.md which collides with the new
commands/update-docs.md -- both registered as /update-docs. The command
is the self-contained replacement; the skill was a 2-line pointer to
pal-e-docs.

Align Step 1 curl auth to use basic auth (-u user:pass) matching
hooks/forgejo-helper.sh, instead of token auth which diverged from the
established pattern.

Fix README "no skills exist yet" statement -- other skills do exist.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Author
Contributor

QA Re-Review Fixes Applied

Commit 5c301b2 addresses both findings from the re-review:

BLOCKER Fixed: Naming collision

  • Deleted skills/update-docs/SKILL.md -- this was a 2-line pointer that delegated to mcp__pal-e-docs__get_note(slug="skill-update-docs"). The new commands/update-docs.md is the complete, self-contained replacement with all 7 SOP steps inline. Only one /update-docs registration now exists.

Nit Fixed: Auth pattern inconsistency

  • Step 1 now uses basic auth (-u "$FORGEJO_USER:$FORGEJO_PASSWORD") matching the pattern in hooks/forgejo-helper.sh, instead of token auth (Authorization: token $FORGEJO_TOKEN). Added a note in the command explaining this alignment.

Additional fix

  • README "no skills exist yet" was inaccurate -- there are 10 other skills in 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.
## QA Re-Review Fixes Applied Commit `5c301b2` addresses both findings from the re-review: ### BLOCKER Fixed: Naming collision - **Deleted `skills/update-docs/SKILL.md`** -- this was a 2-line pointer that delegated to `mcp__pal-e-docs__get_note(slug="skill-update-docs")`. The new `commands/update-docs.md` is the complete, self-contained replacement with all 7 SOP steps inline. Only one `/update-docs` registration now exists. ### Nit Fixed: Auth pattern inconsistency - **Step 1 now uses basic auth** (`-u "$FORGEJO_USER:$FORGEJO_PASSWORD"`) matching the pattern in `hooks/forgejo-helper.sh`, instead of token auth (`Authorization: token $FORGEJO_TOKEN`). Added a note in the command explaining this alignment. ### Additional fix - **README "no skills exist yet" was inaccurate** -- there are 10 other skills in `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.
Author
Contributor

PR #72 Review (Round 3 -- Final)

Previous Findings Verification

All issues from rounds 1 and 2 are resolved:

  1. Round 1 blocker (curl creds not sourced) -- FIXED. Step 1 now sources ~/secrets/pal-e-services/forgejo.env before the curl call (line 29).
  2. Round 1 nits -- All addressed per round 2 confirmation.
  3. Round 2 blocker (naming collision with skills/update-docs/SKILL.md) -- FIXED. The file is deleted in this diff (-16 lines). The skills/ directory is now empty.
  4. Round 2 nit (auth pattern) -- FIXED. Step 1 uses basic auth -u "$FORGEJO_USER:$FORGEJO_PASSWORD" matching the established pattern in hooks/forgejo-helper.sh.
  5. README accuracy -- The new "Custom Commands" section (lines 91-120) correctly documents the commands/ directory, conventions, deploy process, and the commands-vs-skills distinction.

BLOCKERS

None.

NITS

None. LGTM.

SOP COMPLIANCE

  • Branch named after issue (71-add-update-docs-slash-command-for-post-m references issue #71)
  • PR body follows template (Summary, Changes, Test Plan, Related sections present)
  • Related references plan slug (plan-2026-02-26-tf-modularize-postgres)
  • No secrets committed (only variable references to ~/secrets/pal-e-services/forgejo.env)
  • No unnecessary file changes (3 files: new command, deleted skill, README update -- all in scope)
  • Commit messages are descriptive

VERDICT: APPROVED

## PR #72 Review (Round 3 -- Final) ### Previous Findings Verification All issues from rounds 1 and 2 are resolved: 1. **Round 1 blocker (curl creds not sourced)** -- FIXED. Step 1 now sources `~/secrets/pal-e-services/forgejo.env` before the curl call (line 29). 2. **Round 1 nits** -- All addressed per round 2 confirmation. 3. **Round 2 blocker (naming collision with `skills/update-docs/SKILL.md`)** -- FIXED. The file is deleted in this diff (-16 lines). The `skills/` directory is now empty. 4. **Round 2 nit (auth pattern)** -- FIXED. Step 1 uses basic auth `-u "$FORGEJO_USER:$FORGEJO_PASSWORD"` matching the established pattern in `hooks/forgejo-helper.sh`. 5. **README accuracy** -- The new "Custom Commands" section (lines 91-120) correctly documents the `commands/` directory, conventions, deploy process, and the commands-vs-skills distinction. ### BLOCKERS None. ### NITS None. LGTM. ### SOP COMPLIANCE - [x] Branch named after issue (`71-add-update-docs-slash-command-for-post-m` references issue #71) - [x] PR body follows template (Summary, Changes, Test Plan, Related sections present) - [x] Related references plan slug (`plan-2026-02-26-tf-modularize-postgres`) - [x] No secrets committed (only variable references to `~/secrets/pal-e-services/forgejo.env`) - [x] No unnecessary file changes (3 files: new command, deleted skill, README update -- all in scope) - [x] Commit messages are descriptive ### VERDICT: APPROVED
forgejo_admin deleted branch 71-add-update-docs-slash-command-for-post-m 2026-03-08 19:59:12 +00:00
Sign in to join this conversation.
No description provided.