Portwood: Skill for Claude Code

Fixing a merge-tag bug

The trap: there is more than one place that resolves tags, and they do not share code. A fix landed in one path leaves the others broken, and the failure is silent — the tag just prints raw or evaluates wrong for templates that happen to take a different route.

Before writing a fix, work out which path(s) the reported template takes.

The three merge-tag resolution paths

DocGenGiantQueryAssembler does not call processXml(). So:

Path	Resolved by	Reached when
Row-level loop bodies	DocGenService.processXml()	normal templates
Parent-level tags outside the loop	DocGenGiantQueryAssembler.resolveParentMergeTags()	giant-query templates (>2000 child rows)
Grand-total aggregates	DocGenGiantQueryAssembler.resolveGiantAggregateTags()	giant-query templates

A section-tag fix in processXml covers only row-level loop bodies. If the change needs to behave consistently for giant-query templates, mirror it in the assembler or route it through processXmlForTest the same way format-suffix tags already do.

Always check whether your fix needs the same change in the giant-query parent path, and add an e2e-07 assertion either way — including one that proves it doesn't need it.

The four {#ChartBucket} resolution paths

{#ChartBucket:relationship:field[:mod=val&...]}body{/ChartBucket} has its own set, and all four must stay consistent:

1. In-memory — DocGenChartBucketResolver.preprocessInline against pre-loaded relationship records. Used when child count <2000 and no where=/groupBy=. SOQL-free, fastest.
2. SOQL fallback — tryFallbackSoqlAggregateAdvanced, when the relationship isn't on the data map or where=/groupBy= force it. Schema-auto-discovers child object and FK via ChildRelationship, issues a GROUP BY aggregate at constant cost. This is how 30K-scale templates work.
3. Parent-level — resolveParentMergeTags()'s regex skips {#…} prefixes so charts pass through, then processXmlForTest routes to the inline path.
4. Giant-query parent — resolveGiantChartBuckets for charts targeting the giant relationship. Same modifiers, same shape.