#138 - Align update-docs skill with SOP — add missing steps and verification-before-skip - ldraney/claude-custom

forgejo_admin commented

2026-03-21 17:01:33 +00:00

Contributor

Type

Feature

Lineage

plan-pal-e-agency → Phase 18 → 18e

Repo

forgejo_admin/claude-custom

User Story

As the superuser, when /update-docs runs after a merge, every SOP step is executed or explicitly verified — no steps are silently skipped with rationalizations. The skill produces an auditable summary showing UPDATED, VERIFIED CURRENT, or NOT APPLICABLE (reason) for each step.

Context

The commands/update-docs.md skill has 8 steps but the sop-post-merge-docs SOP has 10. Three SOP steps are missing from the skill entirely: step 2 (verify deploy), step 8 (nit-bundle creation, formerly epilogue nits), and step 10 (cross-pillar impact check). Additionally, almost every skill step says "if [condition], skip this step" — this allows Betty Sue to rationalize skipping steps that the SOP says should not be skipped. Observed in production: project page updates and memory updates skipped with "doesn't need updating" without actually reading the artifacts to verify.

File Targets

Files the agent should modify:

commands/update-docs.md — rewrite to match all 10 SOP steps with verification-before-skip

Files the agent should NOT touch:

hooks/remind-update-docs.sh — the trigger hook is fine
Any pal-e-docs notes — SOP already updated separately

Acceptance Criteria

Skill has all 10 steps from sop-post-merge-docs (close issue, verify deploy, phase note, plan note, project page, sync board, memory, nit-bundle, discovered scope, cross-pillar impact)
No step says "skip this step" — instead requires verification before reporting VERIFIED CURRENT
Step 4 (project page) requires reading the page before claiming it's current
Step 8 references template-issue-nit-bundle for nit-bundle creation
Completion summary uses UPDATED / VERIFIED CURRENT / NOT APPLICABLE (reason) — "SKIPPED" is not a valid outcome
Step numbering matches SOP for traceability

Test Expectations

Read the updated skill and verify every SOP step is present
Verify no step allows unconditional skip

Constraints

Follow the SOP step numbering exactly (1-10)
Reference pal-e-docs tools by their MCP tool names
Keep the "Gather Context" preamble — it's useful
The skill must reference sop-post-merge-docs as the canonical source

Checklist

PR opened
Tests pass
No unrelated changes

phase-pal-e-agency-18-enterprise-definitions — parent phase
sop-post-merge-docs — the canonical SOP this skill must match
template-issue-nit-bundle — referenced in step 8
glossary — enterprise definitions

### Type Feature ### Lineage `plan-pal-e-agency` → Phase 18 → 18e ### Repo `forgejo_admin/claude-custom` ### User Story As the superuser, when `/update-docs` runs after a merge, every SOP step is executed or explicitly verified — no steps are silently skipped with rationalizations. The skill produces an auditable summary showing UPDATED, VERIFIED CURRENT, or NOT APPLICABLE (reason) for each step. ### Context The `commands/update-docs.md` skill has 8 steps but the `sop-post-merge-docs` SOP has 10. Three SOP steps are missing from the skill entirely: step 2 (verify deploy), step 8 (nit-bundle creation, formerly epilogue nits), and step 10 (cross-pillar impact check). Additionally, almost every skill step says "if [condition], skip this step" — this allows Betty Sue to rationalize skipping steps that the SOP says should not be skipped. Observed in production: project page updates and memory updates skipped with "doesn't need updating" without actually reading the artifacts to verify. ### File Targets Files the agent should modify: - `commands/update-docs.md` — rewrite to match all 10 SOP steps with verification-before-skip Files the agent should NOT touch: - `hooks/remind-update-docs.sh` — the trigger hook is fine - Any pal-e-docs notes — SOP already updated separately ### Acceptance Criteria - [ ] Skill has all 10 steps from `sop-post-merge-docs` (close issue, verify deploy, phase note, plan note, project page, sync board, memory, nit-bundle, discovered scope, cross-pillar impact) - [ ] No step says "skip this step" — instead requires verification before reporting VERIFIED CURRENT - [ ] Step 4 (project page) requires reading the page before claiming it's current - [ ] Step 8 references `template-issue-nit-bundle` for nit-bundle creation - [ ] Completion summary uses UPDATED / VERIFIED CURRENT / NOT APPLICABLE (reason) — "SKIPPED" is not a valid outcome - [ ] Step numbering matches SOP for traceability ### Test Expectations - [ ] Read the updated skill and verify every SOP step is present - [ ] Verify no step allows unconditional skip ### Constraints - Follow the SOP step numbering exactly (1-10) - Reference pal-e-docs tools by their MCP tool names - Keep the "Gather Context" preamble — it's useful - The skill must reference `sop-post-merge-docs` as the canonical source ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `phase-pal-e-agency-18-enterprise-definitions` — parent phase - `sop-post-merge-docs` — the canonical SOP this skill must match - `template-issue-nit-bundle` — referenced in step 8 - `glossary` — enterprise definitions