pal-e-docs

Review: Issue #183 -- Expand check-note-template.sh (2026-03-27)

review-183-2026-03-27 Review

review needs_refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Checked against template-issue-feature. All required sections present:
Section Status Notes
Type Present Feature
Lineage Present Related to #180 (spike)
Repo Present forgejo_admin/claude-custom
User Story Present Betty Sue / PM perspective
Context Present Explains the audit finding (2 of 17 types enforced)
File Targets Present hooks/check-note-template.sh, with NOT-touch list
Acceptance Criteria Present 7 testable items
Test Expectations Present Manual hook testing
Constraints Present 3 constraints including template dependency
Checklist Present Standard 3-item checklist
Related Present Links to project and parent spike

File Targets

Verified: ~/claude-custom/hooks/check-note-template.sh exists (128 lines). Current structure routes on tags (project-page, issue) and extracts headings dynamically from template <pre><code> blocks.

Dependencies

The issue depends on 5 template notes existing. All 5 are confirmed present in pal-e-docs:
  • template-review (id 868) -- exists
  • template-architecture (id 870) -- exists
  • template-user-story (id 872) -- exists
  • template-sop (id 869) -- exists
  • template-convention (id 871) -- exists
Caveat: Issue #185 ("Create template notes for new types") is still OPEN despite all 5 templates existing. This creates ambiguity about whether templates are final/approved. Recommend closing #185 before this ticket moves to execution.

Acceptance Criteria

All 7 ACs are testable -- each specifies a note_type and whether creation should be blocked or allowed. No ambiguous language.

Critical Gaps -- Why NEEDS_REFINEMENT

Gap 1: No Required Headings Per Type

The issue says "add case branches for new types" and "Hook must read required headings from templates or a config mapping" but does NOT specify which headings each type must enforce. The dev agent would need to read all 5 templates, extract headings, and make judgment calls about which are "required" vs. example content. Extracted from templates:
Type Required Headings (from template code blocks)
review Template Completeness, Traceability, File Targets, Repo Placement, Dependencies, Acceptance Criteria, Blast Radius, Decomposition Assessment, Recommendation
architecture Diagram, Components, Key Decisions, Related
user-story Role, Key, Want, So That, Acceptance Criteria, Success Metric, Related Architecture, Related
sop Purpose, Steps, Rules, Related
convention Rule, Rationale, Examples, Enforcement, Related
This table (or equivalent) should be IN the issue body so the dev agent does not guess.

Gap 2: Routing Mechanism Change Not Addressed

The current hook routes on tags (e.g., grep -qw "project-page"). The new types would need to route on the note_type field (.tool_input.note_type), which is a different input field. The issue does not specify whether to:
  • (a) Add note_type-based routing alongside the existing tag-based routing
  • (b) Replace tag-based routing entirely with note_type-based routing
  • (c) Some hybrid approach

Gap 3: HTML vs. Markdown Heading Format in Templates

The current heading extraction uses grep -oE '^### .+' (markdown format). But two of the new templates use HTML <h3> tags in their code blocks:
  • template-sop -- uses <h3 id="purpose">Purpose</h3> (HTML)
  • template-convention -- uses <h3 id="rule">Rule</h3> (HTML)
  • template-review, template-architecture, template-user-story -- use ### Heading (markdown)
The current extraction logic would silently fail for the HTML-format templates, making the hook appear to work but not actually enforce anything for SOP and convention notes. The issue should specify the extraction strategy or mandate a consistent format across all templates.

Gap 4: template-validation Not Addressed

template-validation exists (id 840) but is not mentioned in the issue's acceptance criteria or constraints. Should validation notes be enforced? Explicitly include or exclude.

Recommendation

  • Add a "Required Headings Per Type" table to the issue body with the exact heading names per note_type.
  • Specify the routing mechanism: note_type-based routing for the new types (the note_type field is already available in tool_input).
  • Address the HTML vs. markdown format mismatch in template code blocks, or standardize all templates to one format first.
  • Explicitly include or exclude template-validation from scope.
  • Close issue #185 if the 5 templates are considered final, or note that #183 is blocked until #185 is closed.
  • template-issue-feature -- template this issue was checked against
  • forgejo_admin/claude-custom #183 -- the reviewed issue
  • forgejo_admin/claude-custom #185 -- dependency (template creation)
  • forgejo_admin/claude-custom #180 -- parent spike
  • template-review -- review note template followed