P0 — Product Guide Section Alignment Specification

P0 — Product Guide Section Alignment Specification

Status: v1 — draft authored S190 WP5 (23/04/2026). Spec-only; implementation plan to follow in a separate /planning-and-task-breakdown pass once signed off. Severity: pre-launch blocker (action-tracker B.2; also covers SS7.4 reciprocal cross-refs and partial SS7.7). Author: Claude Code (S190 WP5, main track). Roadmap placement: docs/reference/product-roadmap.md SS1.13 (Option C sequence) / action-tracker B.2. Source decision: Liam feedback 22/04/2026 in docs/gap-analysis-response-decisions.md: “Align naming to mind map for ALL sections / Add ALL missing sections (also covers SS7.4 and some of SS7.7).” Source analysis: docs/client-documentation/kb-hub-gap-analysis-response-s188.md SS7.2 (Product Guide section naming divergence).

---

1. Problem Statement

1.1 Section naming divergence from Matthew’s mind map

The three Product Guides (Advanced Audits, LMS, Websites) share an identical 19-section structure populated via migration 20260422174420_wire_product_guide_sections.sql (S189 WP4). A 20th “Research Feed” section was added via migration 20260422174117_add_research_feed_to_product_guides.sql (S189 WP5).

Matthew’s gap analysis (SS7.2, 20/04/2026) identified that several section names diverge from the mind-map naming convention used by the client team. The divergence causes confusion when cross-referencing the Knowledge Hub guide structure against Matthew’s planning documents and the client’s internal terminology.

1.2 Missing sections

Seven sections present in Matthew’s mind map have no equivalent in the current build:

1. Problems It Solves — no equivalent section exists.
2. Relevant Sectors — no equivalent; Sector Guides have “Relevant Products” (section 8), but Product Guides lack the reciprocal link (SS7.4 cross-referencing gap).
3. ROI & Impact Evidence — build has “Success Stories” (section 10) which conflates ROI evidence with case-study references; these are distinct concepts.
4. IMPACT of “If Not Now” — Matthew’s highest-priority addition; the core cost-of-inaction sales argument is structurally absent.
5. Functionality (capability matrix) — no dedicated section; capability content is dispersed across multiple sections.
6. External Parties — third-party processors, suppliers, and dependencies have no structural home.
7. FAQs — the Q&A Library is a separate cross-cutting feature; there is no per-product FAQ section within guides.

1.3 SS7.4 reciprocal cross-referencing

Sector Guides contain a “Relevant Products” section (section 8) but Product Guides have no “Relevant Sectors” section. Adding “Relevant Sectors” closes this asymmetry and enables bidirectional navigation between product and sector intelligence.

1.4 Existing content population state

S189 WP4 wired 14 unique subtopic_filter values across the 19 existing sections. 48 of 57 section-guide combinations resolve >= 1 content item on ‘r’; 9 are content-population-pending (Pricing, Data Handling, Certifications at company_reference layer — 3 sections x 3 guides). The new sections added by this spec will initially resolve to 0 items each; content population is a separate Matthew-side task.

---

2. Goals and Non-Goals

2.1 Goals

1. G1. Rename existing Product Guide sections to align with Matthew’s mind-map naming, closing the terminology divergence flagged in SS7.2.
2. G2. Add 7 new sections (Problems It Solves, Relevant Sectors, ROI & Impact Evidence, IMPACT of “If Not Now”, Functionality, External Parties, FAQs) to all 3 Product Guides.
3. G3. Maintain the Research Feed section (shipped S189 WP5) at a stable position in the section order.
4. G4. Ship a single idempotent migration scoped strictly to the 3 Product Guide UUIDs.
5. G5. Reassess existing subtopic_filter mappings against the expanded section layout and update where semantically warranted.
6. G6. Extend existing guard tests (product-guide-resolution.test.ts, product-guide-migration-sync.test.ts) to cover renamed sections and new section additions.

2.2 Non-Goals

1. N1. Content population of new sections. This is a data task for the client team and does not belong in this spec.
2. N2. Dual-tier (Standard/Advanced) section splitting for Advanced Audits. That is action-tracker B.4, a separate spec (p0-advanced-audits-dual-tier-spec.md).
3. N3. Layer-nesting UI changes. That is action-tracker B.1, a separate spec (p0-layer-nesting-spec.md).
4. N4. Sector Guide modifications. This spec is strictly Product Guide-scoped.
5. N5. Changes to the get_guide_content RPC or suggestGuideSections() resolution logic. The existing matching algorithm handles renamed sections transparently (it matches on filter columns, not section names).
6. N6. Changes to the guide_sections schema (no new columns). The migration uses existing columns only.
7. N7. Taxonomy changes (no new domains or subtopics). New sections use existing taxonomy subtopics or NULL filters.

---

3. Current State Evidence

3.1 Product Guide UUIDs

Verified against live DB and migration files (lines 29-31 of 20260422174420):

Guide	UUID	slug
Advanced Audits	a4cfe046-9a6c-4e3f-b0ff-2d4f0d958687	audits-product
LMS	f216848e-decf-4a86-a19f-f9907b6b55c8	lms-product
Websites	ff2b9333-80f7-41a7-88d8-82baeb65b20e	websites-product

All 3 guides have domain_filter = 'product-feature' and guide_type = 'product'.

3.2 Current 20-section layout (per guide)

Source: migration 20260422174420 (lines 44-63) + migration 20260422174117.

#	display_order	section_name	subtopic_filter	expected_layer	Items on ‘r’
1	1	Elevator Pitch	functionality	sales_brief	14
2	2	Key Features	functionality	sales_brief	14
3	3	Differentiators	approach	sales_brief	2
4	4	Target Audience	company-info	sales_brief	4
5	5	Use Cases	functionality	bid_detail	28
6	6	Pricing	financial	company_reference	0
7	7	Objection Handling	approach	sales_brief	2
8	8	Demo Flow	usability	sales_brief	8
9	9	Competitor Comparison	standards	bid_detail	11
10	10	Success Stories	references	sales_brief	1
11	11	Upsell Paths	company-info	sales_brief	4
12	12	Technical Spec	technical	bid_detail	51
13	13	Security & Compliance	cyber-security	bid_detail	9
14	14	Implementation	deployment	bid_detail	2
15	15	SLAs	sla	company_reference	1
16	16	Integrations	integration	bid_detail	5
17	17	Data Handling	data-protection	company_reference	0
18	18	Accessibility	usability	bid_detail	38
19	19	Certifications	certification	company_reference	0
20	20	Research Feed	NULL	research	varies

Total per guide: 20 sections. Total guide_sections rows across 3 Product Guides: 60.

3.3 guide_sections schema (relevant columns)

Source: docs/reference/SCHEMA-QUICK-REFERENCE.md SS guide_sections + migration 20260416102457:

• id (uuid PK, auto-generated)
• guide_id (uuid FK -> guides.id, NOT NULL)
• section_name (varchar, NOT NULL)
• description (text, nullable)
• content_type_filter (varchar, nullable)
• subtopic_filter (varchar, nullable)
• expected_layer (varchar, nullable)
• is_required (boolean, NOT NULL, default true)
• display_order (int, NOT NULL, default 0)
• parent_section_id (uuid, nullable, FK -> guide_sections.id ON DELETE CASCADE, indexed)
• created_at / updated_at (timestamptz, auto)

No unique constraint on (guide_id, section_name). This means ON CONFLICT is not available for idempotent INSERTs; the migration must use WHERE NOT EXISTS guards (same pattern as the Research Feed migration).

---

4. Target State

4.1 Rename table

The following table maps current section names to mind-map-aligned names. Evidence sources are the SS7.2 table in kb-hub-gap-analysis-response-s188.md (lines 128-149) and Liam’s decision in gap-analysis-response-decisions.md (line 9).

Important: The mind map itself is not available as a file in the repository. The rename recommendations below are the best-effort interpretation from the gap-analysis evidence. Items marked [CONFIRM] require Matthew or Liam validation before migration execution.

#	Current Name	Proposed Name	Rationale	Status
1	Elevator Pitch	Product Overview	SS7.2 evidence: mind map has “Product Overview” in place of “Elevator Pitch”	Rename
2	Key Features	Key Features	Already matches mind map	Keep
3	Differentiators	The Value Proposition	SS7.2: mind map has “The Value Proposition”; “Differentiators” is a subset concept	Rename
4	Target Audience	Target Buyer & Roles	SS7.2: mind map uses “Target Buyer & Roles” — more specific	Rename
5	Use Cases	Use Cases	Not mentioned in SS7.2 divergence list; keep	Keep
6	Pricing	Pricing	Not mentioned in SS7.2 divergence list; keep	Keep
7	Objection Handling	Common Objections & Responses	SS7.2: mind map has “Common Objections & Responses”	Rename
8	Demo Flow	Demo Highlights / What to Show	SS7.2: mind map naming; [CONFIRM] — “Demo Flow” is shorter but client prefers mind-map name	Rename [CONFIRM]
9	Competitor Comparison	Competitor Positioning	SS7.2: mind map spirit is “Competitor Positioning”	Rename
10	Success Stories	Success Stories	Keep; new “ROI & Impact Evidence” section separates ROI from case studies	Keep
11	Upsell Paths	Upsell Paths	Not in mind map but build-only addition; keep per SS7.2 note	Keep
12	Technical Spec	Technical Specs / Architecture	SS7.2: mind map uses full name	Rename [CONFIRM]
13	Security & Compliance	Security & Compliance	Keep combined; SS7.1 splitting is a B.1 concern, not this spec	Keep
14	Implementation	Implementation	Not in SS7.2 divergence list; keep	Keep
15	SLAs	SLAs & Support	SS7.2: mind map extends to “SLAs & Support”	Rename [CONFIRM]
16	Integrations	Integrations	Not in SS7.2 divergence list; keep	Keep
17	Data Handling	Data Processing / DPIA	SS7.2: mind map is more specific with DPIA reference	Rename
18	Accessibility	Accessibility	Not in SS7.2 divergence list; build-only addition; keep	Keep
19	Certifications	Certifications	Not in SS7.2 divergence list; keep	Keep
20	Research Feed	Research Feed	Shipped S189 WP5; keep unchanged	Keep

Summary: 8 renames, 12 keep-as-is. 3 renames marked [CONFIRM] for Liam/Matthew sign-off on the exact wording.

4.2 New sections

Seven new sections to add to each Product Guide. All are uniform across the 3 guides (same pattern as the existing 19-section structure).

New #	Section Name	subtopic_filter	expected_layer	Rationale	display_order (proposed)
N1	Problems It Solves	functionality	sales_brief	Core sales narrative: what pain points does this product address? Maps to same content pool as Product Overview but with a problem-framing lens.	3
N2	Relevant Sectors	NULL	NULL	Reciprocal cross-ref to Sector Guides’ “Relevant Products” (SS7.4). No subtopic filter — this is a navigational/cross-link section, not a content-resolution section. Content will be manually curated or resolved via guide-level metadata.	11
N3	ROI & Impact Evidence	references	sales_brief	Separated from Success Stories; ROI calculators, measurable outcomes, before/after metrics. Uses references subtopic at sales_brief layer (same pool as Success Stories but semantically distinct section).	12
N4	IMPACT of “If Not Now”	approach	sales_brief	Matthew’s highest-priority addition. Cost-of-inaction argument. Uses approach subtopic — the methodology of articulating why delay is costly.	13
N5	Functionality	functionality	bid_detail	Dedicated capability matrix section. Uses functionality at bid_detail layer — same pool as Use Cases but structured as a feature/capability grid rather than narrative use cases.	14
N6	External Parties	supply-chain	company_reference	Third-party processors, sub-contractors, supply-chain dependencies. Uses supply-chain subtopic at company_reference layer.	24
N7	FAQs	NULL	NULL	Per-product FAQ aggregation. No filter — this section is expected to be populated via manual curation or a future content_type_filter = 'q_a_pair' refinement.	25

4.3 Full target section layout (post-migration)

After applying renames + inserts + display_order renumbering:

display_order	Section Name	subtopic_filter	expected_layer	Source
1	Product Overview	functionality	sales_brief	Renamed from “Elevator Pitch”
2	Key Features	functionality	sales_brief	Existing
3	Problems It Solves	functionality	sales_brief	NEW
4	The Value Proposition	approach	sales_brief	Renamed from “Differentiators”
5	Target Buyer & Roles	company-info	sales_brief	Renamed from “Target Audience”
6	Use Cases	functionality	bid_detail	Existing
7	Pricing	financial	company_reference	Existing
8	Common Objections & Responses	approach	sales_brief	Renamed from “Objection Handling”
9	Demo Highlights / What to Show	usability	sales_brief	Renamed from “Demo Flow”
10	Competitor Positioning	standards	bid_detail	Renamed from “Competitor Comparison”
11	Relevant Sectors	NULL	NULL	NEW
12	ROI & Impact Evidence	references	sales_brief	NEW
13	IMPACT of “If Not Now”	approach	sales_brief	NEW
14	Functionality	functionality	bid_detail	NEW
15	Success Stories	references	sales_brief	Existing
16	Upsell Paths	company-info	sales_brief	Existing
17	Technical Specs / Architecture	technical	bid_detail	Renamed from “Technical Spec”
18	Security & Compliance	cyber-security	bid_detail	Existing
19	Implementation	deployment	bid_detail	Existing
20	SLAs & Support	sla	company_reference	Renamed from “SLAs”
21	Integrations	integration	bid_detail	Existing
22	Data Processing / DPIA	data-protection	company_reference	Renamed from “Data Handling”
23	Accessibility	usability	bid_detail	Existing
24	External Parties	supply-chain	company_reference	NEW
25	FAQs	NULL	NULL	NEW
26	Certifications	certification	company_reference	Existing
27	Research Feed	NULL	research	Existing (moved from display_order 20)

Total per guide: 27 sections. Total guide_sections rows across 3 Product Guides: 81. Delta: +21 new rows (7 sections x 3 guides) + 0 deleted rows.

---

5. Sequencing and Dependencies

5.1 Upstream dependencies

Dependency	Status	Impact
S189 WP4 migration 20260422174420 (subtopic_filter wiring)	Shipped	This spec’s renames operate on rows created by WP4. The migration must run after WP4.
S189 WP5 migration 20260422174117 (Research Feed)	Shipped	Research Feed row exists at display_order=20. This spec moves it to display_order=27.
Taxonomy subtopics	Stable	All subtopic_filter values used in this spec exist in the current taxonomy_subtopics table. No new subtopics required.

5.2 Downstream dependents

Dependent	Impact
Action-tracker B.4 (dual-tier Advanced Audits spec)	B.4 will add child sections via parent_section_id beneath the section names established by THIS spec. B.4 must run after this spec ships.
Action-tracker B.1 (layer nesting UI spec)	B.1 changes how sections render based on layer, not section names. No blocking dependency, but B.1 should use the final section names from this spec.
Product Guide resolution tests	Must be updated as part of this spec’s implementation (SS10).
Guard test product-guide-migration-sync.test.ts	Must be updated to include new section names and new migration file reference.

5.3 Sequencing order

S189 WP4 (subtopic_filter wiring) -- SHIPPED
    |
S189 WP5 (Research Feed)          -- SHIPPED
    |
THIS SPEC (section alignment)     -- spec phase
    |
B.4 (dual-tier Advanced Audits)   -- depends on final section names
    |
B.1 (layer nesting UI)            -- independent but uses final names

---

6. Architecture — Idempotent Migration Strategy

6.1 Migration structure

A single SQL migration file with three phases executed in order:

Phase 1 — Renames (UPDATE statements)

UPDATE guide_sections
SET section_name = '{new_name}',
    updated_at = NOW()
WHERE guide_id IN (
    'f216848e-decf-4a86-a19f-f9907b6b55c8',
    'ff2b9333-80f7-41a7-88d8-82baeb65b20e',
    'a4cfe046-9a6c-4e3f-b0ff-2d4f0d958687'
)
AND section_name = '{old_name}';

One UPDATE per rename. 8 UPDATEs total. No idempotency guard needed beyond the WHERE clause — renaming an already-renamed row matches zero rows (no-op).

Phase 2 — New section INSERTs

INSERT INTO guide_sections (
    guide_id, section_name, description, expected_layer,
    subtopic_filter, content_type_filter, display_order,
    is_required, parent_section_id
)
SELECT
    '{guide_id}'::uuid,
    '{section_name}',
    NULL,
    '{expected_layer}',  -- or NULL
    '{subtopic_filter}', -- or NULL
    NULL,
    {display_order},
    FALSE,
    NULL
WHERE NOT EXISTS (
    SELECT 1 FROM guide_sections
     WHERE guide_id = '{guide_id}'::uuid
       AND section_name = '{section_name}'
);

One INSERT per guide per new section. 7 sections x 3 guides = 21 INSERT statements. Idempotent via WHERE NOT EXISTS guard (same pattern as Research Feed migration).

New sections have is_required = FALSE because they start with zero content items; flipping to TRUE is a post-population decision.

Phase 3 — Display order renumbering

UPDATE guide_sections
SET display_order = {new_order},
    updated_at = NOW()
WHERE guide_id IN (
    'f216848e-decf-4a86-a19f-f9907b6b55c8',
    'ff2b9333-80f7-41a7-88d8-82baeb65b20e',
    'a4cfe046-9a6c-4e3f-b0ff-2d4f0d958687'
)
AND section_name = '{section_name}';

One UPDATE per section per guide. This renumbers all 27 sections to the target layout in SS4.3. Using section_name (post-rename) as the match key. 27 UPDATEs total.

Idempotent: setting display_order to the same value is a no-op in effect.

6.2 Execution order within migration

1. Renames first (Phase 1) — so Phase 2 and Phase 3 can use the new names.
2. Inserts second (Phase 2) — creates new rows.
3. Renumber third (Phase 3) — assigns final display_order to all rows (existing + new).

6.3 UUID scoping

Every UPDATE and INSERT is scoped to the 3 Product Guide UUIDs via guide_id IN (...). No other guides are touched.

6.4 Idempotency verification

Running the migration a second time:

• Phase 1 renames: WHERE section_name = '{old_name}' matches zero rows (already renamed). No-op.
• Phase 2 inserts: WHERE NOT EXISTS (... AND section_name = '{new_section}') evaluates to FALSE (row exists). No-op.
• Phase 3 renumber: SET display_order = N on rows already at order N. Writes updated_at = NOW() but is functionally a no-op.

---

7. Display Order and Research Feed Placement

7.1 Options

Option	Approach	Research Feed display_order	Pros	Cons
(a)	Push Research Feed to end of list	27	Mechanical simplicity; Research Feed is a trailing aggregation section	Requires renumbering all sections between old and new RF position
(b)	Keep Research Feed at 20 and insert new sections around it	20	No RF row change	Awkward ordering; new sections like FAQs and External Parties would need to fit before RF or jump to 21+

7.2 Recommendation

Option (a) — move Research Feed to display_order 27 (end of list). Rationale:

• Research Feed is semantically a trailing section (it aggregates research-layer content across the guide’s domain). Every other guide type (Sector Guides, MAT Auditing Intelligence Guide) places Research Feed as the last or near-last section.
• Placing operational/reference sections (External Parties, FAQs, Certifications) before the Research Feed maintains a logical flow: product narrative -> technical detail -> governance/compliance -> research aggregation.
• The renumbering is handled entirely within Phase 3 of the migration (SS6.1) and does not require any special handling.

7.3 Research Feed survival guarantee

The migration does NOT delete the Research Feed row. Phase 3 simply updates its display_order from 20 to 27. If the migration is run after the Research Feed migration (which it must be, per SS5.1), the row is guaranteed to exist.

Verification: the migration includes a specific comment block documenting the Research Feed survival guarantee, and the guard test suite includes a test asserting Research Feed presence at display_order 27 post-migration.

---

8. Breaking Change Audit

8.1 UI rendering (guide pages)

Guide pages render sections by iterating guide_sections rows ordered by display_order. Section names are displayed as headings. Impact: renamed sections will show new headings immediately. No code change required — the UI reads section_name dynamically.

Risk: if any UI component hardcodes a section name (e.g. if (section.section_name === 'Elevator Pitch') for special rendering), the rename will break that conditional. Mitigation: grep the codebase for all 8 renamed section names; fix any hardcoded references.

8.2 MCP tools

MCP tools that reference guide sections (e.g. get_guide, update_guide_section) use UUIDs, not section names. No breaking change.

8.3 suggestGuideSections() resolution logic

The suggestGuideSections() function in lib/guide-section-mapping.ts matches on subtopic_filter, expected_layer, and content_type_filter — not on section_name. Renames do not affect resolution. New sections with existing subtopic values will naturally appear in suggestion results. No breaking change to resolution logic.

8.4 get_guide_content RPC

The get_guide_content RPC matches items to sections using guide_sections.subtopic_filter, expected_layer, content_type_filter, and the guide’s domain_filter. Section names are not part of the matching logic. No breaking change.

8.5 Test fixtures

The following test files contain hardcoded section names that must be updated:

1. __tests__/lib/guides/product-guide-resolution.test.ts — SECTION_FILTER_MAP constant (lines 54-79) lists all 19 section names. Must be updated to 27 sections with new names.
2. __tests__/lib/guides/product-guide-migration-sync.test.ts — EXPECTED_SECTION_NAMES constant (lines 56-76) lists all 19 names. Must be updated. MIGRATION_PATH (line 28) may need updating to reference the new migration file.
3. __tests__/lib/guides/product-guide-research-feed.test.ts — references Research Feed at display_order 20. Must be updated to verify display_order 27 if the test checks the alignment migration.

8.6 Downstream spec impact

B.4 (dual-tier Advanced Audits) spec will need to use the post-rename section names when creating child sections. This spec must ship before B.4 is authored.

8.7 Content-population-pending sections

The 3 existing content-population-pending sections (Pricing, Data Handling -> Data Processing / DPIA, Certifications) remain pending. Their subtopic_filter values do not change. The rename of “Data Handling” to “Data Processing / DPIA” is cosmetic and does not affect content resolution.

---

9. S189 WP4 Reassessment

9.1 Subtopic filter review for renamed sections

Renamed Section	subtopic_filter	Reassessment
Product Overview (was Elevator Pitch)	functionality	Keep. The core product overview content is functionality-scoped at sales_brief layer. Semantic fit.
The Value Proposition (was Differentiators)	approach	Keep. Value proposition is methodology/approach content. Semantic fit.
Target Buyer & Roles (was Target Audience)	company-info	Keep. Buyer/role information is company-context content. Semantic fit.
Common Objections & Responses (was Objection Handling)	approach	Keep. Objection responses are methodology/approach content. Semantic fit.
Demo Highlights / What to Show (was Demo Flow)	usability	Keep. Demo content maps to UX/usability. Semantic fit.
Competitor Positioning (was Competitor Comparison)	standards	Keep. Competitive positioning is benchmarked against standards. Semantic fit.
Technical Specs / Architecture (was Technical Spec)	technical	Keep. Direct match.
SLAs & Support (was SLAs)	sla	Keep. SLA content. Support content may also fall here or in a future separate section.
Data Processing / DPIA (was Data Handling)	data-protection	Keep. DPIA is data-protection content. Semantic fit.

Conclusion: All 14 existing subtopic_filter values remain semantically valid after the renames. No subtopic_filter changes required for existing sections.

9.2 Subtopic filter review for new sections

New Section	Proposed subtopic_filter	Rationale	Notes
Problems It Solves	functionality	Product pain points are expressed in terms of functional gaps. Same content pool as Product Overview/Key Features but with a problem-framing presentation.	Will initially resolve to existing functionality/sales_brief items. Content-specific “problem” items can be loaded later.
Relevant Sectors	NULL	Cross-link/navigational section. No content resolution via subtopic — this section will either be manually curated or resolved via a future guide-level cross-reference mechanism.	NULL filter = shows all domain-matching items or empty until manually populated.
ROI & Impact Evidence	references	ROI evidence is reference-type content (metrics, case data). Same subtopic pool as Success Stories but with ROI framing.	Consider adding a roi subtopic in a future taxonomy expansion if the content volume warrants it.
IMPACT of “If Not Now”	approach	Cost-of-inaction is a sales methodology/approach argument.	Same pool as Common Objections & Responses; distinct section curation needed.
Functionality	functionality	Capability matrix content. Same subtopic as Use Cases but at bid_detail layer (structured capabilities vs narrative use cases).	High overlap with Use Cases; distinct presentation (matrix vs narrative).
External Parties	supply-chain	Third-party processors, sub-contractors. Supply-chain subtopic is in the taxonomy (VALID_SUBTOPICS in test file, line 91).	Content population depends on client loading supply-chain content at company_reference layer.
FAQs	NULL	Aggregation section. Could be refined to content_type_filter = 'q_a_pair' in a future iteration, but starting with NULL to avoid premature filtering.	Future enhancement: wire content_type_filter = 'q_a_pair' to auto-populate from Q&A Library.

---

10. Test Plan

10.1 Update product-guide-resolution.test.ts

Current state: 40 tests across 7 describe blocks. SECTION_FILTER_MAP constant defines 19 sections.

Required changes:

1. Update SECTION_FILTER_MAP to 27 entries with renamed section names and new sections.
2. Update CONTENT_POPULATION_PENDING_SECTIONS set — “Data Handling” renamed to “Data Processing / DPIA”.
3. Update section name assertions in “section names match the known scaffold” test (line 183-192).
4. Update display_order assertion from “sequential 1-19” to “sequential 1-27” (line 179).
5. Add new section entries to the it.each RPC resolution simulation (section 4 of the test suite).
6. Add new tests for sections with NULL subtopic_filter (Relevant Sectors, FAQs) — these produce domain_only matches by design, not exact matches.
7. Extend the “Cross-Guide Uniformity” tests to verify 27 sections per guide.

New test count estimate: ~55-60 tests (up from 40).

10.2 Update product-guide-migration-sync.test.ts

Current state: 4 tests. Guards against migration typos by grepping the WP4 migration file.

Required changes:

1. Add a new ALIGNMENT_MIGRATION_PATH constant pointing to the new alignment migration file.
2. Update EXPECTED_SECTION_NAMES from 19 to 27 names (using post-rename names).
3. Add a new test that greps the alignment migration for all 8 rename UPDATE statements.
4. Add a new test that greps the alignment migration for all 21 INSERT statements (7 sections x 3 guides).
5. Verify that the alignment migration references all 3 Product Guide UUIDs.
6. Verify idempotency guards: every INSERT has WHERE NOT EXISTS.

New test count estimate: ~8-10 tests (up from 4).

10.3 Update product-guide-research-feed.test.ts

Current state: Tests verify Research Feed at display_order 20.

Required changes:

1. If the test validates display_order against the alignment migration (not just the original RF migration), update the expected display_order from 20 to 27.
2. Add a test verifying that the alignment migration does NOT delete or modify the Research Feed section_name.

10.4 Codebase grep for hardcoded section names

Before implementation, grep the codebase for all 8 renamed section names to identify any hardcoded references beyond test files:

grep -rn "Elevator Pitch\|Differentiators\|Target Audience\|Objection Handling\|Demo Flow\|Competitor Comparison\|Technical Spec\|Data Handling" \
  --include="*.ts" --include="*.tsx" \
  app/ components/ lib/ hooks/ contexts/

Any matches must be updated as part of the implementation.

10.5 Post-migration integration verification

After running the migration on ‘r’:

1. Query guide_sections for the 3 Product Guide UUIDs; verify 27 rows per guide.
2. Verify no duplicate section names within any guide.
3. Verify display_order is sequential 1-27 with no gaps.
4. Verify Research Feed exists at display_order 27 with expected_layer = 'research'.
5. Load each Product Guide in the UI; verify all 27 section headings render.
6. Run suggestGuideSections() with a known content item; verify renamed sections appear with correct names.

---

11. Acceptance Criteria

1. AC1. Migration is idempotent: running it twice produces zero changes on the second run (verified by row-count and updated_at comparison).
2. AC2. Migration is scoped strictly to the 3 Product Guide UUIDs listed in SS3.1. No other guide_sections rows are modified.
3. AC3. Research Feed section survives: present at display_order 27 with expected_layer = 'research', section_name = 'Research Feed', all filter columns unchanged.
4. AC4. All 8 renames produce the correct new names per SS4.1 table.
5. AC5. All 7 new sections exist with the correct subtopic_filter, expected_layer, and display_order per SS4.3 table.
6. AC6. product-guide-resolution.test.ts passes with updated section registry (27 sections).
7. AC7. product-guide-migration-sync.test.ts passes with updated section names and migration reference.
8. AC8. No hardcoded section name references remain in app/, components/, lib/, hooks/, contexts/ for the 8 renamed sections.
9. AC9. Post-migration, each Product Guide renders all 27 sections in the UI with correct ordering.
10. AC10. Content resolution via get_guide_content RPC continues to work for all sections (existing content items still resolve to the same sections under new names).

---

12. Rollback Path

12.1 Reverse migration

A reverse migration can be authored that:

1. Renames sections back to their original names (8 UPDATE statements with old/new swapped).
2. Deletes the 7 new sections by (guide_id, section_name) match (21 DELETE statements).
3. Restores display_order values to the pre-migration layout (20 UPDATE statements).

12.2 Risk assessment

Rollback is safe because:

• No content items reference guide_sections.section_name as a foreign key. Section names are display-only.
• No content resolution logic uses section names. All resolution is via subtopic_filter, expected_layer, and content_type_filter.
• New sections start empty (no content items would be lost by deleting them).

12.3 When to rollback

If Matthew or Liam determine that the renamed section names do not match the mind map after seeing them in the UI, a follow-up rename migration is preferred over a full rollback. Rollback is reserved for schema/integrity issues only.

---

13. Risks

#	Risk	Likelihood	Impact	Mitigation
R1	Renamed section names do not match Matthew’s mind map exactly (mind map file unavailable)	Medium	Low	3 renames marked [CONFIRM] in SS4.1; Liam/Matthew sign-off before migration execution. Open Question OQ1.
R2	Hardcoded section name references in application code break on rename	Low	Medium	Codebase grep in SS10.4; fix as part of implementation.
R3	Subtopic_filter values for new sections produce unexpected resolution results (wrong items showing in new sections)	Low	Low	New sections start with is_required = FALSE and are expected to have zero items initially. Resolution logic is the same as existing sections.
R4	Display order renumbering causes UI rendering issues	Very Low	Low	Display order is a simple integer sort; the UI iterates by this column. No known edge cases.
R5	B.4 (dual-tier) spec authors use pre-rename section names	Low	Medium	This spec documents the sequencing dependency in SS5.3. B.4 must not be authored until this spec ships.
R6	Overlap between new section content pools and existing sections (e.g. “Problems It Solves” and “Product Overview” both use functionality/sales_brief)	Medium	Low	Expected overlap. Sections provide different presentation framings for the same content pool. Content curation (manual or via description metadata) is the resolution mechanism, not filter exclusivity.
R7	The 3 [CONFIRM] renames are rejected by client, requiring a follow-up migration	Low	Low	Follow-up migration is trivial (3 UPDATE statements).

---

14. Adversarial Review Checklist

1. Does the migration run idempotently? (Verified: renames match zero rows on re-run; inserts blocked by WHERE NOT EXISTS; renumbers set same values.)
2. Is the migration scoped strictly to 3 Product Guide UUIDs? (Verified: every UPDATE and INSERT uses guide_id IN (uuid1, uuid2, uuid3) or guide_id = 'uuid'::uuid.)
3. Does Research Feed survive? (Verified: no DELETE; display_order updated from 20 to 27; section_name unchanged.)
4. Are all 14 existing subtopic_filter values preserved? (Verified: SS9.1 reassessment confirms all remain valid.)
5. Do any new subtopic_filter values reference non-existent taxonomy slugs? (Verified: supply-chain exists in VALID_SUBTOPICS set at product-guide-resolution.test.ts line 91. NULL values for Relevant Sectors and FAQs require no taxonomy entry.)
6. Is parent_section_id set correctly for new sections? (Verified: all new sections have parent_section_id = NULL; no hierarchy established by this spec.)
7. Does the migration contain any DELETE or DROP statements? (Verified: no. Only UPDATE and INSERT.)
8. Could the migration produce duplicate section names within a guide? (Verified: WHERE NOT EXISTS on (guide_id, section_name) prevents duplicates for new inserts. Renames target unique old names.)
9. Are test fixture updates specified for every test file that hardcodes section names? (Verified: SS10.1, SS10.2, SS10.3 enumerate all 3 affected test files.)
10. Does the spec create any product-scope assumptions that should be Liam decisions? (Verified: 3 renames marked [CONFIRM]; new section applicability is uniform across all 3 guides per SS4.2; no deferred items hidden in assumptions.)
11. Does the spec avoid scope creep into B.1, B.4, or content population? (Verified: explicit non-goals N2, N3, N4 in SS2.2.)
12. Are there any hardcoded section names in non-test application code? (Action: codebase grep required per SS10.4 before implementation.)
13. Is the display_order sequence gap-free from 1-27? (Verified: SS4.3 table shows sequential 1-27.)
14. Does the migration handle the case where a section was already renamed by a manual DB edit? (Verified: Phase 1 UPDATE matches section_name = '{old_name}'; if already renamed, zero rows match — safe no-op.)
15. Is the is_required flag set appropriately for new sections? (Verified: all new sections have is_required = FALSE; they start empty.)

---

15. Open Questions

OQ1 — Mind map file availability

The mind map is referenced throughout Matthew’s gap analysis but is not available as a file in the repository. The rename recommendations in SS4.1 are derived from the SS7.2 evidence table in kb-hub-gap-analysis-response-s188.md. Three renames are marked [CONFIRM] because the exact mind-map wording is not verifiable.

Decision needed from Liam: confirm or correct the 3 [CONFIRM] renames:

1. “Demo Flow” -> “Demo Highlights / What to Show” (or keep “Demo Flow”)
2. “Technical Spec” -> “Technical Specs / Architecture” (or “Technical Specifications”)
3. “SLAs” -> “SLAs & Support” (or keep “SLAs”)

OQ2 — Per-guide section applicability

The current spec applies all 7 new sections uniformly to all 3 Product Guides. Should any new section be omitted for a specific product?

Example: “External Parties” may be less relevant for Websites than for Advanced Audits (which involves third-party audit frameworks). However, uniformity is the current pattern and simplifies the migration.

Recommendation: apply uniformly; client can hide empty sections via is_required = FALSE (which is the default for new sections).

OQ3 — FAQs section content_type_filter

The FAQs section is proposed with content_type_filter = NULL. A future enhancement could set content_type_filter = 'q_a_pair' to auto-populate from the Q&A Library. Should this be done now or deferred?

Recommendation: defer to a follow-up. Starting with NULL allows manual curation; the Q&A Library connection can be wired once the client’s content structure is clearer.

OQ4 — Relevant Sectors cross-link mechanism

The “Relevant Sectors” section has subtopic_filter = NULL and expected_layer = NULL, meaning it will not auto-resolve content via the get_guide_content RPC. The cross-linking mechanism (how a Product Guide’s “Relevant Sectors” section connects to Sector Guides) needs design.

Options:

• (a) Manual: section description field contains a list of relevant Sector Guide slugs, rendered as links.
• (b) Metadata: new guide_sections column cross_link_guides (uuid array) referencing related guides.
• (c) Content-based: create “sector relevance” content items tagged to each product-sector intersection.

Recommendation: start with (a) for MVP; evaluate (b) if the client requests dynamic cross-linking. (c) is over-engineered for the current state.

---

16. Future Work

16.1 Content population (separate workstream)

Once the structural changes in this spec are shipped, Matthew’s team will populate the new sections with content. This is a data task, not a code task. The following new sections will start empty and need content:

• Problems It Solves
• Relevant Sectors (manual cross-links)
• ROI & Impact Evidence
• IMPACT of “If Not Now”
• Functionality (capability matrix)
• External Parties
• FAQs

16.2 Dual-tier splitting (action-tracker B.4)

After section names are finalised by this spec, B.4 can add child sections for the Advanced Audits guide using parent_section_id. This is a separate spec.

16.3 FAQs auto-population

A future enhancement could wire the FAQs section to auto-resolve Q&A Library items via content_type_filter = 'q_a_pair' (see OQ3).

16.4 Relevant Sectors cross-link enhancement

A future enhancement could add a cross_link_guides column or similar mechanism to programmatically link Product Guides to Sector Guides (see OQ4).

16.5 Section description population

All new sections have description = NULL. A follow-up task can populate section descriptions with guidance text for content authors (e.g. “This section contains cost-of-inaction arguments for prospects who are delaying purchase decisions”).

---

17. References

Document	Path	Relevance
Gap analysis response (SS7.2)	docs/client-documentation/kb-hub-gap-analysis-response-s188.md	Source evidence for section naming divergence
Gap analysis action tracker (B.2)	docs/client-documentation/kb-hub-gap-analysis-action-tracker.md	Tracker entry for this spec
Liam feedback / decisions	docs/gap-analysis-response-decisions.md	Decision to align all + add all
WP4 filter wiring migration	supabase/migrations/20260422174420_wire_product_guide_sections.sql	Current subtopic_filter mappings
WP5 Research Feed migration	supabase/migrations/20260422174117_add_research_feed_to_product_guides.sql	Research Feed section creation
Resolution test suite	__tests__/lib/guides/product-guide-resolution.test.ts	Tests to update
Migration sync guard test	__tests__/lib/guides/product-guide-migration-sync.test.ts	Guard test to update
Research Feed test suite	__tests__/lib/guides/product-guide-research-feed.test.ts	Test to verify RF survival
Guide section mapping logic	lib/guide-section-mapping.ts	Resolution logic (no changes needed)
Schema quick reference	docs/reference/SCHEMA-QUICK-REFERENCE.md SS guide_sections	Table schema
P0-BM Phase 3 spec (reference)	docs/specs/p0-bm-phase3-qa-library-importer-markdown-spec.md	Reference spec structure

---

18. Changelog

• 2026-04-23 (S190 WP5) — v1. Initial draft. Enumerates 8 renames, 7 new sections, full target layout of 27 sections per Product Guide. Migration strategy: single idempotent SQL file with 3 phases (rename, insert, renumber). 3 renames marked [CONFIRM] pending mind-map verification. 4 open questions. Research Feed survival at display_order 27. Test plan covers 3 existing test files.