Issue #3586390: Document purpose guidance for conditional subcontext.

Kristen Polrequested to merge
issue/ai_context-3586390:3586390-document-purpose-field into 1.0.x

Description

Follow-up to:

Test current conditional subcontext selection b... (#3586351) • Kristen Pol • 1.0.0-beta5

Real-provider testing showed the current conditional subcontext prompt (parent Content + task + each child ID and Purpose) works well when Purpose values are clear and distinct. Failures were more often caused by vague or overlapping Purpose text than by missing child labels or descriptions.

This MR adds editorial guidance so authors understand that Purpose drives conditional AI inclusion decisions. Detailed examples and anti-patterns live in documentation; the item form uses a single static Purpose description.

Changes (#3586390)

Form (AiContextItemForm)

  • Replaces the generic Purpose help with one static description for all items:
    • Purpose is included in injected context metadata
    • For conditional subcontext children, Purpose is the primary signal for inclusion decisions

Entity field descriptions (AiContextItem)

  • Purpose: clarifies metadata role and conditional inclusion behavior
  • Subcontext type: links conditional selection to each child Purpose

Documentation

  • docs/features/context_items.md — corrects outdated “not sent to agents” text; links to subcontext guidance
  • docs/features/subcontext.md — new section Writing Purpose for conditional children with examples and anti-pattern table

Test

  • AiContextItemFormTest::testPurposeFieldShowsGuidance()

No runtime behavior changes.

Testing instructions

  1. Create or edit any context item (/admin/config/ai/context/items/add or edit an existing item).
  2. Confirm the Purpose field shows the updated static description (metadata + conditional subcontext note).
  3. Create or edit a conditional subcontext child and confirm the same Purpose description appears (no separate conditional guidance block).
  4. Read docs/features/subcontext.md#writing-purpose-for-conditional-children and the updated Purpose section in docs/features/context_items.md.

Automated:

./lint.sh
ddev phpunit --filter testPurposeFieldShowsGuidance \
  web/modules/contrib/ai_context/tests/src/Functional/AiContextItemFormTest.php

Checklist

  • I have updated the MR title to use format: Issue #1234: My issue title.
  • I have updated the MR description to include: Closes #1234
  • I have performed a self-review of my own code
  • I have added or updated tests, or explained in the description why this change is not covered by tests
  • I have updated documentation for any new or changed functionality
  • I have written testing instructions and verified them locally
  • I have noted any required post-merge steps (config imports, cache rebuilds, manual changes)
  • This MR contains no breaking API or hook changes, or they are explicitly documented in the description

Post-merge: None. Cache rebuild not required.

AI Compliance

  • AI Assisted Code — Mainly written by a human; AI used for autocomplete or partial generation under full human supervision.

Closes #3586390

Edited by Kristen Pol

Merge request reports