applies-to-tagging: add generate-from-intent mode and cumulative-docs rules

[florent-leborgne]

Summary

Two related additions that make docs-applies-to-tagging the canonical home for both applies_to syntax and the cumulative-docs decisions that surround it (preserve vs. replace, append vs. replace lifecycle, when to delete a removed feature's page).

• Generate-from-intent mode — accept a structured description of a change and return the right applies_to syntax, instead of only validating an existing file.
• Cumulative documentation rules — capture the preservation logic that determines whether new tagged content should sit alongside old content or replace it.

4 new evals exercise both additions. Skill version: 1.1.0 → 1.2.0 (MINOR). Plugin version: 1.0.3 → 1.0.4.

Why

Two gaps exist today:

1. The skill says it can "generate correct ones for new or updated content," but the only documented entry point for generation is "if asked to fix or generate tags, use Edit to apply corrections" — i.e., file-bound. Callers that have a structured change description but no file (for example, the docs-quest-scanner skill, when drafting a docsGap entry from a PR) have no clean way to ask this skill to generate a tag.
2. The cumulative-docs preservation rules (do users on older versions still need the old content? when do you append a lifecycle vs. replace it? when do you keep a removed feature's page?) live informally inside docs-quest-scanner's SKILL.md instead of next to the syntax they govern.

This PR fixes both, so downstream skills can delegate to one canonical source.

What changed

SKILL.md

Modes section (new)

Distinguishes validate mode (existing — file or pasted content) from generate-from-intent mode (new — structured change description). Detection cues for the new mode are explicit; ambiguous cases prompt one focused clarifying question rather than guessing.

Cumulative documentation rules (new section, before Task execution)

• Preserve old content when possible — two questions to ask before any version-scoped change.
• Lifecycle changes — versioned products append (stack: ga 9.2+, preview =9.0), unversioned replace.
• Removals — GA/deprecated removed from versioned product → keep content + removed 9.x; removed from unversioned only → can delete; preview/beta-only feature ending → can delete.
• Lightest-format preference — tagged paragraph or admonition → tagged list items → applies-switch tabs (last resort).
• Version display reminders — no version numbers in prose adjacent to badges; Major.Minor display; latest-patch semantics.

Generate-from-intent execution (new section)

Five-step flow:

1. Extract the change description (dimension, lifecycle per key, version per lifecycle, sub-projects, scope, preserve-vs-replace).
2. Decide preservation vs. replacement using the cumulative rules.
3. Pick the lightest format that scopes correctly.
4. Generate the canonical syntax (frontmatter, fenced section block, inline, admonition).
5. Output with explicit rationale and a preservation note when applicable.

Task execution (lightly edited)

The validate flow now references generate-from-intent for the "no file, just a change description" case so users land in the right mode.

Description (frontmatter)

Widened to mention preservation decisions — this is now a triggering use case in addition to validation and generation.

evals.json

4 new evals (ids 6–9):

• 6 — Generate-from-intent, simple stack + serverless: feature added in 9.5 in stack and in serverless elasticsearch. Expects stack: ga 9.5+ plus the serverless.elasticsearch: ga sub-key (not bare serverless: ga, since the user specified the sub-project).
• 7 — Generate-from-intent, multi-lifecycle progression: stack-only feature, preview at 9.4, GA at 9.5. Expects stack: ga 9.5+, preview =9.4, ordered newest-first, with =9.4 for the exact preview version.
• 8 — Cumulative preservation, default-value change: a configuration default changed in 9.4. Expects "preserve the existing paragraph, add a tagged paragraph or admonition for the new default" — not replacement.
• 9 — Cumulative preservation, removal from versioned product: GA in stack until 9.3, removed in 9.4. Expects "keep the page, append stack: removed 9.4," not deletion.

Test plan

• python3 -m json.tool evals/evals.json — valid
• Local replay of validate-skills.yml Python checks — 17 skills validated, 0 errors
• Manual review: existing validation rules and syntax sections unchanged; existing evals 1–5 unchanged
• CI validate-skills.yml and skill-eval-test.md runs on PR
• Eval grading on the 4 new cases

Notes for reviewers

• Ordering on the page: I put the new Cumulative documentation rules before Generate-from-intent execution because the generation flow references those rules (Step 2 explicitly applies them). They could equally live as a subsection of the generation flow, but cumulative rules also apply during validation and as standalone questions, so I gave them their own section.
• Plugin version bump conflicts with another open PR (content-type-checker: add classify-proposal mode #68 — content-type-checker). Whichever lands second will need a one-line plugin version rebase.
• The existing language "validate existing applies_to tags and generate correct ones for new or updated content" already promised generation; this PR simply makes the generation path first-class with a real entry point and rationale.