tdx-skills/segment: surface include/exclude composition as the answer to "nested segments"

[xerial]

Why

A customer filed a product gap for "Nested Segment Creation" (tracked in HubSpot / #hs-product-gap-updates), and the tdx team was cc'd on the request. Tracing it back to the original thread, the triage there was "tdx has capability to create segment including referenced segment, but td-skills doesn't handle the referenced segment."

That last part isn't accurate — include/exclude references have been documented since #43 (2025-12-23), and the decomposition workaround for cross-attribute Or since #111 (2026-03-05). But the skill's description never mentioned references at all; it advertised only "nested condition group restrictions." Someone scanning the description sees what's forbidden, not the supported way to build a segment on top of another segment. Two people in that thread concluded "not supported."

What changed

• description now names include/exclude composition, and reframes the nesting clause as "how to express nested AND/OR logic that the Console rejects" rather than a bare restriction.
• Segment References section says up front that this is how you build a nested/composed segment.
• Cross-attribute Or limitation gets the decomposition written out in YAML instead of a one-line "consider creating separate segments…", plus the push-order constraint (branches before the composition).
• NESTED_CONDITION_GROUP row in Common Issues now points at references, not just In/flatten — that's the line an agent lands on after a validation failure.
• test.yml gains three scenarios for the reference path: plain include nesting, the validate-passes/push-fails asymmetry on a missing reference, and the cross-attribute-Or decomposition. All three pre-existing scenarios covered only sg move name resolution.
• tests/trigger-tests.yml gains two nested-segment prompts.

Scope — what this does not fix

I measured rather than assumed, and the results limit the claim:

Check	Result
Skill selection for nested-segment prompts (old vs new description, 87 skills, haiku)	segment both ways
"Can you build (country = US) OR (age > 30)?" against old body, 3 runs	correct answer + type: include YAML 3/3
Same against new body, 3 runs	correct answer + type: include YAML 3/3

So a model that actually loads this skill already answered correctly before this PR. This is a discoverability and test-coverage fix, not a behavior fix, and it does not by itself explain the downstream "not supported" answer that reached the customer. The likelier remaining suspect is whether this skill is in context at all on the Foundry Audience-agent / TAIS path — that's being followed up separately and is out of scope here.

The two new trigger tests pass before and after, so they're coverage, not regression guards for this change.

Testing

./tests/run-tests.sh needs yq, which I don't have installed, so I replicated the runner's logic (same extract-skills.sh output, same prompt template, same --model haiku) to produce the table above. YAML frontmatter and both test files parse. SKILL.md is 302 lines, within the 500-line guidance.

Worth a second opinion on the description rewrite specifically — it's now noticeably longer, and description length trades off against the resolver's precision across 87 skills.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves discoverability of “nested segments” support in the segment skill by explicitly framing include/exclude segment references as the supported composition mechanism, and adds test coverage for those reference-based workflows.

Changes:

• Expand tdx-skills/segment/SKILL.md to highlight include/exclude references as the solution for composed/nested segments and document the cross-attribute Or decomposition workflow.
• Add new scenarios to tdx-skills/segment/test.yml to cover reference-based composition and validate/push asymmetry.
• Add nested-segment prompts to tests/trigger-tests.yml to improve trigger coverage.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
tests/trigger-tests.yml	Adds two prompts intended to trigger the segment skill for nested/composed segment requests.
tdx-skills/segment/test.yml	Adds three new regression scenarios for include/exclude composition and reference-resolution behavior.
tdx-skills/segment/SKILL.md	Updates frontmatter description and documentation sections to surface segment references as the “nested segment” approach and expands workaround guidance.

Comments suppressed due to low confidence (2)

tdx-skills/segment/test.yml:74

• This scenario runs tdx sg push against /tmp/refs-missing-segment.yml, but that file is never created in setup, so the command will fail due to a missing file rather than exercising the intended “reference not found” behavior.

      - tdx sg push --dry-run -y /tmp/refs-missing-segment.yml

tdx-skills/segment/test.yml:91

• The cross-attribute Or scenario references segments/us-visitors.yml, segments/over-30.yml, and segments/us-or-over-30.yml, but these files don’t exist in the repo and aren’t created in setup, so the scenario can’t run as written.

      - tdx sg push -y segments/us-visitors.yml
      - tdx sg push -y segments/over-30.yml
      - tdx sg validate segments/us-or-over-30.yml
      - tdx sg push --dry-run -y segments/us-or-over-30.yml

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adher-code]

Governance review — PDM

The discoverability improvement here is genuinely useful — surfacing include/exclude as the answer to "nested segments" is the right call. Good scope, good test additions.

1. Test scenario bug (flagged by Copilot) — the three new scenarios in test.yml reference type: Behavior syntax in the YAML examples, but this skill's own documentation says type: Behavior is invalid and must be rewritten as type: Value + TimeWithinPast. The test scenarios won't run as written. Please update them to use the documented valid syntax — and while rebasing, verify the NESTED_CONDITION_GROUP behavior description is consistent with what main now says (warning-only vs. hard rejection).
2. SKILL.meta.yml — the existing validation entry (2026-07-07) covers the name-resolution guidance. A new entry should be added for this change, confirming that the include/exclude composition examples were validated against a live CDP environment.

The governance frontmatter is already complete from PR #196 — nothing missing there. Once the rebase, test fix, and meta entry are in, this is straightforward to approve.

As you Leo are working on this I thing the developer reviewer is you even if Ai wrote the code.