ldraney/claude-custom

Fork 0

Reconcile skill-review-ticket review note format with template-review hook headings #241

New issue

Open

opened 2026-04-11 20:31:05 +00:00 by forgejo_admin · 1 comment

forgejo_admin commented

2026-04-11 20:31:05 +00:00

Contributor

Type

Bug

Lineage

Discovered twice during 2026-04-10 ticket review pipeline (review-944-2026-04-10 and review-945-2026-04-10). Both review agents independently reported the same drift. Re-review of this ticket itself (review-970-2026-04-11) caught a location error in the original body — the drift is in the pal-e-docs note skill-review-ticket, not in ~/claude-custom/skills/review-ticket/SKILL.md. Body updated to point at the correct surface.

Repo

forgejo_admin/claude-custom (tracking only — the actual fix is a content update in pal-e-docs via mcp__pal-e-docs__update_block. Filed in claude-custom because it lives in the agent enforcement domain.)

What Broke

The pal-e-docs note skill-review-ticket (the canonical skill content read by review agents) prescribes a review-note section heading called Decomposition, but template-review (and the corresponding check-note-template.sh enforcement at lines 65–73) requires Decomposition Assessment. When a review agent follows the skill's prescribed format literally, the first create_note attempt is denied by the PreToolUse hook because the heading does not match.

Repro Steps

Verify drift exists in pal-e-docs note:

mcp__pal-e-docs__get_note_toc(slug="skill-review-ticket")
mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000")

Observe the section contains <h3>Decomposition</h3> (not Decomposition Assessment).

Verify the routing-logic file is NOT the source: grep -i "Decompos" ~/claude-custom/skills/review-ticket/SKILL.md returns zero matches.
Spawn a review agent with subagent_type=general-purpose and a prompt that loads the skill-review-ticket skill (via mcp__pal-e-docs__get_note(slug="skill-review-ticket")).
Have the agent follow the skill's "Review Note Format" section verbatim — it will write a review note with ### Decomposition as a heading.
Agent calls mcp__pal-e-docs__create_note with note_type=review and content containing ### Decomposition.
Observe: check-note-template.sh denies with missing required sections: Decomposition Assessment.

Confirmed in both review-944-2026-04-10 and review-945-2026-04-10 runs (and indirectly in review-970-2026-04-11 which used the canonical wording to bypass the drift).

Expected Behavior

The pal-e-docs note skill-review-ticket prescribed format should match the hook's enforced headings exactly. A review agent following the skill literally should create the review note successfully on the first attempt with no hook denial.

Environment

Drift source (the file to fix): pal-e-docs note skill-review-ticket, block anchor code-8000 — accessed via mcp__pal-e-docs__get_note(slug="skill-review-ticket") or mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000")
Routing-logic file (NOT the drift source — verified empty of "Decompos" content): ~/claude-custom/skills/review-ticket/SKILL.md (117 lines, contains routing/loop logic only)
Hook source: ~/claude-custom/hooks/check-note-template.sh, lines 65–73 (canonical, do not modify)
Template source: template-review in pal-e-docs (canonical, do not modify in this ticket)
Affected agents: any general-purpose or QA agent invoked via /review-ticket

Hook's required headings (canonical)

Template Completeness
Traceability
File Targets
Repo Placement
Dependencies
Acceptance Criteria
Blast Radius
Decomposition Assessment   ← canonical wording
Recommendation

Resolution

Update the code-8000 block in pal-e-docs note skill-review-ticket to use Decomposition Assessment instead of Decomposition. Verify all 9 headings agree across skill-review-ticket ↔ template-review ↔ hook.

Exact MCP call (the dev path is content-only, no code PR):

mcp__pal-e-docs__update_block(
    slug="skill-review-ticket",
    anchor_id="code-8000",
    content="<the corrected code block content with 'Decomposition Assessment' instead of 'Decomposition'>"
)

Use mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000") first to read the current content, then apply the correction.

Acceptance Criteria

All 9 review-note headings in pal-e-docs note skill-review-ticket exactly match the hook's REQUIRED_HEADINGS for note_type=review
Future review agents create review notes on the first try without hook denial
If template-review in pal-e-docs has any drift from the hook, file a follow-up ticket (do NOT update the template here — content changes go through their own flow)
No other skills affected
mcp__pal-e-docs__search_notes(query="Decomposition") returns no orphaned references to the old wording in any other skill or convention note

Test Expectations

After the block update, dispatch a test review agent against any existing ticket and confirm the review note creates without hook denial on first attempt
Run mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000") and verify the corrected wording is present
Run mcp__pal-e-docs__search_notes(query="Decomposition") and verify no skill or convention note still references the old wording

Constraints

Do not modify template-review content in this ticket
Do not modify the hook's required headings — the hook is canonical
Do not modify ~/claude-custom/skills/review-ticket/SKILL.md — verified to contain no drifted content
Match heading wording exactly, including capitalization
This is a content task via MCP, not a code PR — no branch, no PR, no merge gate

Checklist

Block updated via mcp__pal-e-docs__update_block
Test review agent run successfully
search_notes verification step run
No unrelated changes

template-review — canonical template note (read-only this ticket)
hooks/check-note-template.sh — enforcement surface (canonical)
skill-review-ticket — the pal-e-docs note containing the drifted block (the surface to fix)
review-944-2026-04-10 and review-945-2026-04-10 — reviews that surfaced the drift
review-970-2026-04-11 — review of this ticket itself, which caught the location error

### Type Bug ### Lineage Discovered twice during 2026-04-10 ticket review pipeline (review-944-2026-04-10 and review-945-2026-04-10). Both review agents independently reported the same drift. Re-review of this ticket itself (review-970-2026-04-11) caught a location error in the original body — the drift is in the **pal-e-docs note `skill-review-ticket`**, not in `~/claude-custom/skills/review-ticket/SKILL.md`. Body updated to point at the correct surface. ### Repo `forgejo_admin/claude-custom` (tracking only — the actual fix is a content update in pal-e-docs via `mcp__pal-e-docs__update_block`. Filed in claude-custom because it lives in the agent enforcement domain.) ### What Broke The pal-e-docs note `skill-review-ticket` (the canonical skill content read by review agents) prescribes a review-note section heading called `Decomposition`, but `template-review` (and the corresponding `check-note-template.sh` enforcement at lines 65–73) requires `Decomposition Assessment`. When a review agent follows the skill's prescribed format literally, the first `create_note` attempt is denied by the PreToolUse hook because the heading does not match. ### Repro Steps 1. Verify drift exists in pal-e-docs note: ``` mcp__pal-e-docs__get_note_toc(slug="skill-review-ticket") mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000") ``` Observe the section contains `<h3>Decomposition</h3>` (not `Decomposition Assessment`). 2. Verify the routing-logic file is NOT the source: `grep -i "Decompos" ~/claude-custom/skills/review-ticket/SKILL.md` returns zero matches. 3. Spawn a review agent with `subagent_type=general-purpose` and a prompt that loads the `skill-review-ticket` skill (via `mcp__pal-e-docs__get_note(slug="skill-review-ticket")`). 4. Have the agent follow the skill's "Review Note Format" section verbatim — it will write a review note with `### Decomposition` as a heading. 5. Agent calls `mcp__pal-e-docs__create_note` with `note_type=review` and content containing `### Decomposition`. 6. Observe: `check-note-template.sh` denies with `missing required sections: Decomposition Assessment`. Confirmed in both `review-944-2026-04-10` and `review-945-2026-04-10` runs (and indirectly in `review-970-2026-04-11` which used the canonical wording to bypass the drift). ### Expected Behavior The pal-e-docs note `skill-review-ticket` prescribed format should match the hook's enforced headings exactly. A review agent following the skill literally should create the review note successfully on the first attempt with no hook denial. ### Environment - Drift source (the file to fix): pal-e-docs note `skill-review-ticket`, block anchor `code-8000` — accessed via `mcp__pal-e-docs__get_note(slug="skill-review-ticket")` or `mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000")` - Routing-logic file (NOT the drift source — verified empty of "Decompos" content): `~/claude-custom/skills/review-ticket/SKILL.md` (117 lines, contains routing/loop logic only) - Hook source: `~/claude-custom/hooks/check-note-template.sh`, lines 65–73 (canonical, do not modify) - Template source: `template-review` in pal-e-docs (canonical, do not modify in this ticket) - Affected agents: any general-purpose or QA agent invoked via `/review-ticket` ### Hook's required headings (canonical) ``` Template Completeness Traceability File Targets Repo Placement Dependencies Acceptance Criteria Blast Radius Decomposition Assessment ← canonical wording Recommendation ``` ### Resolution Update the `code-8000` block in pal-e-docs note `skill-review-ticket` to use `Decomposition Assessment` instead of `Decomposition`. Verify all 9 headings agree across `skill-review-ticket` ↔ `template-review` ↔ `hook`. **Exact MCP call (the dev path is content-only, no code PR):** ```python mcp__pal-e-docs__update_block( slug="skill-review-ticket", anchor_id="code-8000", content="<the corrected code block content with 'Decomposition Assessment' instead of 'Decomposition'>" ) ``` Use `mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000")` first to read the current content, then apply the correction. ### Acceptance Criteria - [ ] All 9 review-note headings in pal-e-docs note `skill-review-ticket` exactly match the hook's `REQUIRED_HEADINGS` for `note_type=review` - [ ] Future review agents create review notes on the first try without hook denial - [ ] If `template-review` in pal-e-docs has any drift from the hook, file a follow-up ticket (do NOT update the template here — content changes go through their own flow) - [ ] No other skills affected - [ ] `mcp__pal-e-docs__search_notes(query="Decomposition")` returns no orphaned references to the old wording in any other skill or convention note ### Test Expectations - [ ] After the block update, dispatch a test review agent against any existing ticket and confirm the review note creates without hook denial on first attempt - [ ] Run `mcp__pal-e-docs__get_section(slug="skill-review-ticket", anchor_id="code-8000")` and verify the corrected wording is present - [ ] Run `mcp__pal-e-docs__search_notes(query="Decomposition")` and verify no skill or convention note still references the old wording ### Constraints - Do not modify `template-review` content in this ticket - Do not modify the hook's required headings — the hook is canonical - Do not modify `~/claude-custom/skills/review-ticket/SKILL.md` — verified to contain no drifted content - Match heading wording exactly, including capitalization - This is a content task via MCP, not a code PR — no branch, no PR, no merge gate ### Checklist - [ ] Block updated via `mcp__pal-e-docs__update_block` - [ ] Test review agent run successfully - [ ] `search_notes` verification step run - [ ] No unrelated changes ### Related - `template-review` — canonical template note (read-only this ticket) - `hooks/check-note-template.sh` — enforcement surface (canonical) - `skill-review-ticket` — the pal-e-docs note containing the drifted block (the surface to fix) - `review-944-2026-04-10` and `review-945-2026-04-10` — reviews that surfaced the drift - `review-970-2026-04-11` — review of this ticket itself, which caught the location error

forgejo_admin commented

2026-04-11 20:55:02 +00:00

Author

Contributor

Scope Review: READY

Review note: review-970-2026-04-11

Dogfooding bug confirmed. Scope is tight, single-file change, all traceability verified (story:agent-write, arch:claude-custom). Drift confirmed in pal-e-docs note skill-review-ticket (review-note-format block, anchor code-8000) — contains <h3>Decomposition</h3> where hook requires Decomposition Assessment.

One scope clarification (non-blocking, [BODY] refinements):

The Environment section points to ~/claude-custom/skills/review-ticket/SKILL.md as the skill source. That file exists (117 lines) but contains only routing/loop logic — grep for "Decompos" returns zero matches. The actual drifted content lives in the pal-e-docs note skill-review-ticket, review-note-format section.

Fix procedure for dev agent:

Use mcp__pal-e-docs__update_block(slug="skill-review-ticket", anchor_id="code-8000", ...) — not file Edit on claude-custom.
Replace <h3>Decomposition</h3> with <h3>Decomposition Assessment</h3> in the code block content. No other changes.
Post-fix: run search_notes(query="Decomposition") to catch any other drifted review-note prescriptions.
Per AC3: diff template-review against hook; file follow-up ticket if drift found (do NOT edit template in this ticket).

Verdict: READY. Recommend lightly refining the issue body to point the dev agent at the pal-e-docs note (not the claude-custom file), then advance todo → next_up.

This review note itself was created on first attempt using Decomposition Assessment — hook accepted cleanly, proving the canonical wording is enforceable and the fix will eliminate the drift.

## Scope Review: READY Review note: `review-970-2026-04-11` Dogfooding bug confirmed. Scope is tight, single-file change, all traceability verified (story:agent-write, arch:claude-custom). Drift confirmed in pal-e-docs note `skill-review-ticket` (review-note-format block, anchor `code-8000`) — contains `<h3>Decomposition</h3>` where hook requires `Decomposition Assessment`. **One scope clarification (non-blocking, [BODY] refinements):** The Environment section points to `~/claude-custom/skills/review-ticket/SKILL.md` as the skill source. That file exists (117 lines) but contains only routing/loop logic — grep for "Decompos" returns zero matches. The actual drifted content lives in the **pal-e-docs note** `skill-review-ticket`, review-note-format section. **Fix procedure for dev agent:** - Use `mcp__pal-e-docs__update_block(slug="skill-review-ticket", anchor_id="code-8000", ...)` — not file Edit on claude-custom. - Replace `<h3>Decomposition</h3>` with `<h3>Decomposition Assessment</h3>` in the code block content. No other changes. - Post-fix: run `search_notes(query="Decomposition")` to catch any other drifted review-note prescriptions. - Per AC3: diff `template-review` against hook; file follow-up ticket if drift found (do NOT edit template in this ticket). Verdict: **READY**. Recommend lightly refining the issue body to point the dev agent at the pal-e-docs note (not the claude-custom file), then advance todo → next_up. This review note itself was created on first attempt using `Decomposition Assessment` — hook accepted cleanly, proving the canonical wording is enforceable and the fix will eliminate the drift.