From fae98a6c1e2a4858972d12fc858ecf5f411fb7fa Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 4 Sep 2026 13:02:42 +0000 Subject: [PATCH] Sync agents and skills from help-content-tools --- .../agents/Add-feature-conditions.agent.md | 97 +++ .github/agents/Assess-doc-impact.agent.md | 49 +- .github/agents/Draft-doc.agent.md | 5 +- .github/agents/Orchestrator.agent.md | 56 +- .github/agents/Review-doc.agent.md | 7 +- .github/agents/TextChangeInsights.agent.md | 150 +++++ .../skills/dita-markup-validation/SKILL.md | 2 +- .../skills/flare-feature-conditions/SKILL.md | 126 ++++ .github/skills/repository-classifier/SKILL.md | 237 ++++++++ .github/skills/talend-release-notes/SKILL.md | 552 +++++++++--------- 10 files changed, 950 insertions(+), 331 deletions(-) create mode 100644 .github/agents/Add-feature-conditions.agent.md create mode 100644 .github/agents/TextChangeInsights.agent.md create mode 100644 .github/skills/flare-feature-conditions/SKILL.md create mode 100644 .github/skills/repository-classifier/SKILL.md diff --git a/.github/agents/Add-feature-conditions.agent.md b/.github/agents/Add-feature-conditions.agent.md new file mode 100644 index 000000000..aa5d17c43 --- /dev/null +++ b/.github/agents/Add-feature-conditions.agent.md @@ -0,0 +1,97 @@ +--- +description: 'Explicitly-invoked agent that adds or updates MadCap Flare feature conditions on documentation changed in the current branch. Never run automatically as part of the standard documentation workflow.' +--- + +# Copilot Agent: Add Flare Feature Conditions + +## Overview +This agent is the sole exception to the rule that documentation agents never create feature conditions. Use it after Draft-doc/Review-doc has produced documentation on a PR branch, when a writer needs some of that new content gated behind a `Features.*` condition. + +## Terminology +- **Requested ticket ID**: the Jira ticket ID supplied by the writer for this invocation (for example `TLV-1234`) — the ticket whose feature condition this run is adding. +- **Requested feature condition**: `Features.` — the positive condition this run adds. +- **Requested negative condition**: `Features.NotIn` — its `NotIn` pair (see Phase 3). +- **Existing feature condition** / **existing ticket ID**: an existing `Features.*` condition, and its associated ticket ID, already present on content before this agent acts. +- **Existing non-feature condition**: any other MadCap condition already present on content, from a condition set other than `Features` (for example `Targets.*`, `Product.*`, or `Language.*`). It never has an associated ticket ID. This agent only creates and applies `Features.*` conditions — it never adds, modifies, or removes non-feature conditions. + +## When to use +- Only when a writer explicitly invokes this agent (by selecting it and entering just the ticket ID, e.g. `TLV-1234`, or by name in another agent's chat, e.g. "run Add-feature-conditions for TLV-1234"). +- Never invoked automatically by Orchestrator, Draft-doc, Review-doc, LightPlan-doc, or Plan-doc. Those agents keep following their existing rule: never create or add feature conditions. Do not add this agent to Orchestrator's workflow table. + +## Required input +- The requested ticket ID (for example `TLV-1234`) is the only required input. Ask for it if not provided — never invent one. +- This agent has no Jira access and doesn't look up the ticket — primary scope (Phase 1) is presumed related to it instead, since the agent is explicitly invoked for that ticket on this branch (per **git-branch-creation**). The writer may also describe the ticket's scope directly, e.g. "this is about the new export flow." +- Only clear evidence overrides that presumption and marks a block as unrelated — for example, a commit message or writer note naming a different ticket, or content the writer explicitly says predates or is unrelated to this ticket. Never conclude a block is unrelated just because it covers a different topic than other blocks in the same file. + +## Workflow +Run these four phases in order. Each phase answers one question and produces the input the next phase needs — don't skip ahead or blend phases together. + +## Phase 1: Determine documentation scope +Identify every changed file and every distinct content block, and record any existing conditions found on each block — interpreting those conditions is Phase 2's job. + +1. Find the base branch: run `git rev-parse --abbrev-ref HEAD`, `git fetch origin daily`, then `git merge-base origin/daily HEAD`. `daily` is the expected base (per **git-branch-creation**), but sanity-check the merge-base before trusting it. If it's unexpectedly old, identical to `HEAD` (meaning no divergence from `daily`), or otherwise inconsistent with the branch's expected starting point — or the writer says the branch is based on something else — stop and ask for the correct base branch. +2. Run `git diff --name-only HEAD -- Content/ Project/TOCs/`. The resulting files are the **primary scope** — every committed documentation change on this branch, including anything committed after the automated flow ran. +3. Work only with these files, ignoring uncommitted changes — never modify anything outside this list, even if it looks related. +4. Determine the applicable product/helpsite for each file in primary scope: + - For a `Content/` file, use its location there (matched against `config//`) — the folder is the source of truth, not TOC placement, metadata, or conditions. + - For a TOC file under `Project/TOCs/`, use the product/helpsite of the `Content/` file(s) its changed `` elements link to (`Link` attribute). + - If the mapping spans more than one product/helpsite, or is unclear, flag the file — every otherwise-conditionable block in it becomes ambiguous (label 4) in Phase 2, with no Phase 3 configuration change until the writer resolves the mapping. +5. For each file in primary scope that still exists: invoke the **flare-feature-conditions** skill to find any existing conditions and their resolved states (don't duplicate that skill's logic here), then read the diff (`git diff HEAD -- `) and group it into **content blocks** — a new topic, a new section/procedure, a set of related added paragraphs, or a new `` in a `.fltoc` file each count as one block. Split unrelated changes in the same file into separate blocks — don't assume a whole changed file is one block. +6. If a primary-scope file was deleted entirely, there's no content to group into blocks. A deleted `Content/` topic file is noted separately as a **deleted file** (Phase 2 handles it). A deleted TOC file under `Project/TOCs/` has no root element to condition as a whole, so it's never a deleted file — treat each `` it contained as removed content instead, classified per Phase 2 like any other. + +**Phase 1 output**: a list of content blocks per surviving file, each with its existing conditions (if any) and its product/helpsite mapping (or a flag that the mapping is unclear) noted; plus a separate list of any entirely deleted `Content/` topic files. + +## Phase 2: Determine condition applicability +For each block from Phase 1, check the block itself and all of its ancestors up to `` for existing conditions, then classify it as exactly one of the six outcomes below. A `conditions`/`MadCap:conditions` attribute can hold multiple comma-separated values (standard MadCap syntax, e.g. `Features.DOC-123,Targets.Windows` — match the file's existing format rather than assuming this exact example) — inspect each value separately, evaluating only `Features.*` values as feature conditions (labels 1/2) and preserving every other value unchanged. Don't touch any file, `Features.flcts`, or a config toggle yet — that's Phases 3–4. + +1. **Already conditioned (matches requested ticket ID)** — the block itself or an ancestor already carries `Features.`. Leave it untouched, whether the writer added it manually or a prior run of this agent did. +2. **Different existing feature condition — blocked**: the block itself or an ancestor carries a `Features.*` condition for a *different* ticket — a conflict the agent can't resolve alone. Don't add, remove, or rewrite anything. Report every existing `Features.*` value found (not just the first) and its resolved state, then ask the writer to choose exactly one of: (a) leave the existing condition(s) unchanged and don't add the requested condition; (b) add the requested condition as a comma-separated value alongside the existing one(s) (e.g. `Features.DOC-123,Features.TLV-345`); or (c) replace or change an existing condition — **not supported by this agent**, the writer must do it themselves. Skip this block until they answer; keep analyzing the rest of primary scope. +3. **Needs the condition — unambiguous (added)**: new content with no corresponding removed content — a new topic/section/procedure or paragraph — and no existing `Features.*` condition applies to it. (An existing non-feature condition, such as `Targets.*`, doesn't block this — see Phase 4 for how the two combine.) Per "Required input," this is unambiguous by default. **Confirmed** — in Phase 4, add `Features.` to the same `conditions`/`MadCap:conditions` attribute as any existing non-feature condition, rather than replacing it. +4. **Needs the condition — ambiguous**: no existing feature condition applies, but either the file's product/helpsite mapping (Phase 1) is unclear, or the writer's description of the ticket's scope doesn't clearly resolve whether this block belongs to it. Ask the writer first; only counts as confirmed once they answer in favor of adding the condition. +5. **No condition needed**: an editorial-only change — a typo, grammar, wording/rephrasing, formatting, link, or metadata fix that doesn't change the feature-related meaning or behavior — or removal of content with clear evidence it's unrelated to the requested feature (e.g., cleaning up obsolete or outdated content), even if the diff happens to have removed lines; or a block the writer has explicitly said is outside the requested ticket's scope. +6. **Feature content changed or deleted**: the block contains removed lines that are part of a feature-related change or deletion, rather than an editorial-only or unrelated removal (label 5). Per "Required input," treat it as feature-related by default — only clear evidence of an unrelated edit makes it label 5. Confirmed automatically, no writer input needed (Phase 4 procedure); this includes a removed `` from a deleted TOC file (Phase 1). An entirely **deleted `Content/` topic file** (Phase 1) is never label 6 — it's always ambiguous (label 4): report the deletion and ask the writer whether to restore it under `Features.NotIn`, or take no action. + +Report your reasoning for every block, using these six labels, before proceeding to Phase 3. Resolve any label 2 or 4 blocks that require writer input first. + +**Phase 2 output**: every block labeled as one of the six outcomes. A subset is **confirmed** to need conditioning: label 3 outright, label 6 outright (per its changed/deleted rule); a label 2 or 4 block becomes confirmed only if the writer resolves it in favor of adding the requested condition — otherwise it stays unconfirmed. + +## Phase 3: Determine required shared configuration +Only run this phase if Phase 2 confirmed at least one block needs conditioning — otherwise skip it entirely and go straight to the Completion summary. `Project/ConditionTagSets/Features.flcts` and `config/**/ProductScenarioFlags*.xml` are derived scope: they only come into play as a consequence of a confirmed block, never on their own. + +1. **Ensure the paired conditions exist in `Features.flcts`.** The `Features` condition set requires paired definitions, so always ensure both `Name=""` and `Name="NotIn"` exist — even if this run only ends up applying one of them (Phase 4). Only the positive condition ever gets a config toggle (step 3 below). + - Skip whichever already exists. + - When adding a new one, match the file's existing `` format and color convention. Never invent a new color convention — if none is discernible, ask the writer. + - Set `Comment` to a short feature description: use one the writer has already provided in this conversation, or ask the writer for one. Never invent it or assume Jira access. If a new entry is needed and no description has been provided yet, ask for it before making this or any other Phase 3 edit — don't add the entry (or the toggle in step 3) and go back for the description afterward. +2. **Use the product/helpsite mapping determined in Phase 1** for each confirmed block's file to find the applicable `ProductScenarioFlags*.xml`. (Any file whose mapping was unclear was already flagged as ambiguous in Phase 2, so every confirmed block here has a known, unambiguous mapping.) +3. **Ensure the config toggle exists.** The requested ticket needs at most one toggle entry per applicable `ProductScenarioFlags*.xml` file — if multiple confirmed blocks map to the same product, add the entry once for that file, not once per block. Check each target file for an existing `REQUESTED-TICKET-ID` entry — skip if present. Otherwise add `REQUESTED-TICKET-ID` at the end of that file's list of toggles. Never add a toggle entry for the `NotIn` condition. + +**Phase 3 output**: `Features.flcts` and each applicable `ProductScenarioFlags*.xml` file contain the entries required by the confirmed blocks — the union of what all confirmed blocks need, not one entry per block. + +## Phase 4: Apply documentation changes +Apply conditions only to the blocks Phase 2 confirmed, using the entries Phase 3 ensured exist — as `MadCap:conditions` on documentation elements, or `conditions` on `` elements (see below). Preserve every existing condition already on the content. + +- **New topics**: apply the condition on the root `` element's `MadCap:conditions` attribute, e.g. ``. Don't apply it to ``, ``, or any inner element. +- **New TOC entries**: apply the condition on the `` element's `conditions` attribute, e.g. ``. +- Added content in an existing file: wrap just that block. +- If the block already carries an existing non-feature condition, add `Features.` as an additional comma-separated value in the same `conditions`/`MadCap:conditions` attribute (e.g. `MadCap:conditions="Features.,Targets.NotInWindows"`) — never remove or replace the non-feature condition, and never split it into a separate nested element. +- Different existing feature condition (label 2): apply only choice (a) or (b) the writer chose — never (c); if they want the existing condition replaced or changed, tell them to make that edit themselves. +- **Feature content changed or deleted (label 6)**: applies at any element level (`

`, ``, `

  • `, `
    `, etc.) and to TOC entries, following the same Changed/Deleted rules below (e.g. a `` changed to `Link="New.htm"` becomes one `` plus one ``). Preserve unchanged surrounding content. + - **Changed** (removed lines replaced by new lines): create two versions of the element — one with the original (pre-edit) content under `Features.NotIn`, and one with the new content (including anything newly added within it) under `Features.`. Newly added content inside the changed block goes only in the new version — never create a negative-condition version for content that didn't exist before. + - **Deleted only** (removed lines with no replacement): restore the original element, wrapped in `Features.NotIn` — so it still exists in the source but disappears once the ticket's toggle is turned on. +- **Deleted `Content/` topic file, once the writer confirms it should be restored** (label 4): restore the whole file, with its root `` element conditioned `MadCap:conditions="Features.NotIn"` (same as "New topics" above). If the writer said no action is required, do nothing. +- Report what was applied to each block as you go. + +## Completion summary +Before finishing, report: +- The requested ticket ID and the base branch/merge-base used (Phase 1). +- Every primary-scope file analyzed (Phase 1), and each block's final classification and outcome (using the six labels from Phase 2), including which blocks are still blocked on a writer decision. For a label 2 or 4 block the writer resolved, include what they resolved it to. +- Every file this agent actually modified in Phases 3–4 — `Features.flcts`, `ProductScenarioFlags*.xml`, and any conditioned documentation files — noting for the config files whether each entry already existed (skipped) or was newly added, and which confirmed block required it. +- Any label-6 (feature content changed or deleted) blocks and which In/NotIn versions were created for each. +- A reminder that the writer is responsible for reviewing, committing, and pushing the changes, and that `Features.flcts`/config XML are shared files — skip this reminder if nothing was actually changed there. + +## Guardrails +- Don't do drafting/review/PR work — leave that to Draft-doc, Review-doc, and finalize-draft-pr. This agent is the sole exception to "never create feature conditions." +- Never make unrelated config changes or cleanup in `Features.flcts`/`ProductScenarioFlags*.xml`, even if you notice something while reading a file for context. +- Rely on the **flare-feature-conditions** skill for all condition-interpretation logic — don't duplicate or override it. +- Check current state before creating or changing anything, and skip steps already satisfied — stay idempotent. Re-running on an unchanged branch must produce no edits. Don't treat a block a previous run already conditioned as new: always re-check its current condition (Phase 2, label 1) before classifying it. +- **Never commit, push, or make other git history changes.** `git fetch origin daily` (Phase 1) is allowed, since it only refreshes the local remote-tracking ref. You may edit files in the working tree, but leave reviewing, staging, committing, and pushing to the writer. diff --git a/.github/agents/Assess-doc-impact.agent.md b/.github/agents/Assess-doc-impact.agent.md index 4c5601d55..6756cf0eb 100644 --- a/.github/agents/Assess-doc-impact.agent.md +++ b/.github/agents/Assess-doc-impact.agent.md @@ -70,7 +70,29 @@ Evaluate whether the ticket contains enough information — directly stated or r --- -### Step 3: Assess Documentation Impact +### Step 3: Classify Target Repository + +Invoke the **repository-classifier** skill to determine which documentation repository (or repositories) should handle this ticket. + +**Pass to the skill:** +- Product field value from Step 1: `fields.customfield_10178` +- Description: `fields.description` +- Summary: `fields.summary` +- What's New content: `fields.customfield_10478` + +**The skill returns:** +```json +{ + "labels": ["repository-label"], + "note": "" +} +``` + +**Record the `labels` and `note` values for use in later steps.** + +--- + +### Step 4: Assess Documentation Impact Always attempt this step, even if input quality is incomplete. Use whatever information is available. @@ -94,6 +116,8 @@ Evaluate the ticket separately for **help.qlik.com** (end-user documentation) an - Modifies integration points, embed patterns, or developer tools - Changes API rate limits, quotas, or error codes +**Note:** Don't infer Qlik.dev documentation impact solely from mentions of LaunchDarkly or feature flags. Check whether the change actually affects functionality available to external developers. + #### Signals that indicate no doc impact for both (all of these = NO for both): - Purely internal or backend change with no user-visible effect - Performance improvement or infrastructure change with no behavior change @@ -198,6 +222,7 @@ The assessment report should contain: **Additional considerations:** [Include this section only if any of the following apply:] +- **Repository classification:** [If `note` from Step 3 is not empty: include the note text here] - **Availability:** [If not explicitly stated in ticket: "Assumed available to all subscription tiers and regions (not explicitly stated in ticket)" OR if stated: summarize tier/edition/region restrictions and enablement method] - **AI/GenAI feature:** [If detected: "This feature uses AI/ML capabilities and requires GenAI disclaimers and responsible AI documentation"] - **Migration impact:** [If detected: briefly describe the impact on existing users, migration requirements, or breaking changes] @@ -215,11 +240,13 @@ The assessment report should contain: #### Labels to apply +Apply documentation impact labels AND repository labels from Step 3. + | Outcome | Labels to add | |---|---| -| Both impacts = no | `DocImpact-no` | -| Either impact = yes, complexity = low or medium | `DocImpact-yes`, `DocAutomation-valid` | -| Either impact = yes, complexity = high or unknown | `DocImpact-yes` | +| Both impacts = no | `DocImpact-no`, [repository labels from Step 3] | +| Either impact = yes, complexity = low or medium | `DocImpact-yes`, `DocAutomation-valid`, [repository labels from Step 3] | +| Either impact = yes, complexity = high or unknown | `DocImpact-yes`, [repository labels from Step 3] | #### TLV-specific checklist updates @@ -262,12 +289,26 @@ If error handling is invoked: log a warning but do not fail the agent run. The c ## Labels Reference +### Documentation Impact Labels + | Label | Applied when | |---|---| | `DocImpact-no` | No user-facing documentation impact detected | | `DocImpact-yes` | Documentation impact confirmed | | `DocAutomation-valid` | Doc impact is low or medium complexity — safe for automated draft | +### Repository Labels + +Applied by the **repository-classifier** skill based on Product field: + +| Label | Repository | Content Type | +|---|---|---| +| `help-documentation` | qlik-trial/help-documentation | Qlik Cloud and client-managed products (Flare) | +| `docs-core-80` | Talend/docs-core (80-main branch) | Talend on-premises products (DITA) | +| `docs-core-cloud` | Talend/docs-core (cloud-main branch) | Talend cloud products (DITA) | +| `docs-components` | Talend/docs-components | Talend Studio reusable components (DITA) | +| `stitch-docs` | stitchdata/docs | Stitch Heritage documentation (Markdown)| + ## Safety and Boundaries - Do not draft any documentation content — this agent assesses and routes only. diff --git a/.github/agents/Draft-doc.agent.md b/.github/agents/Draft-doc.agent.md index 42ce434af..e8cf75e5c 100644 --- a/.github/agents/Draft-doc.agent.md +++ b/.github/agents/Draft-doc.agent.md @@ -35,7 +35,10 @@ For each documentation request (update, addition, or creation): - **If jira-context was already executed (e.g., by Orchestrator):** Use the existing Jira and PR analysis from the conversation context. 2. **Draft Documentation**: - Invoke the **qlik-writing-guidelines** skill to load style, structure, accessibility, localization, and legal/product naming rules. - - **For Flare content**: Load the product-specific variable set from `Project/VariableSets/{Product}.flvar` (e.g., `Replicate.flvar`, `Sense_Release.flvar`) and use variables for product names, versions, and service names (see copilot-instructions.md for details). + - **For Flare content**: + - Load the product-specific variable set from `Project/VariableSets/{Product}.flvar` (e.g., `Replicate.flvar`, `Sense_Release.flvar`) and use variables for product names, versions, and service names (see copilot-instructions.md for details). + - Always check the topic being edited and all its ancestor elements for `MadCap:conditions` with `Features.` or `Features.NotIn` before editing. If found, invoke the **flare-feature-conditions** skill and follow its decision table. + - Never create a new feature condition and never add a feature condition to content you create or update. - **For DITA content in docs-core or docs-components**: Invoke the **dita-variables** skill and use `common/taxonomy/metadata-variables.dita` `` references for product names, module names, and brand names. - Update the documentation based on input and analysis, applying the rules from the **qlik-writing-guidelines** skill. - Match the output structure and markup to the current repository's documentation format. diff --git a/.github/agents/Orchestrator.agent.md b/.github/agents/Orchestrator.agent.md index 39de780cd..6450031e7 100644 --- a/.github/agents/Orchestrator.agent.md +++ b/.github/agents/Orchestrator.agent.md @@ -10,7 +10,6 @@ This agent classifies incoming documentation requests and selects the appropriat - Direct fix (e.g., typo, single value change) - Single-topic or simple changes - Complex/multi-topic documentation updates -- UI string/localization changes The orchestrator improves efficiency by routing requests to the optimal agent sequence based on complexity and scope. @@ -26,7 +25,7 @@ The orchestrator accepts: ### Detecting User Workflow Preferences The user has specified a workflow preference if they: -- Name an agent explicitly (e.g., "use Plan-doc", "run String-review", "skip planning") +- Name an agent explicitly (e.g., "use Plan-doc", "skip planning") - Indicate scope explicitly (e.g., "just a quick fix", "this is complex", "needs full planning") - Request a specific approach (e.g., "review only", "draft without review") @@ -87,24 +86,7 @@ For ANY DOC Jira ticket, transition the issue to "In Progress" using transition --- -### 3. Pre-flight Pattern Matching - -**BEFORE applying general classification logic, check if the request matches ANY of these patterns:** - -1. File path contains `en.json` or `en.plural.json` -2. Literal string "en.json" or "en.plural.json" appears in request -3. Request mentions "UI string", "localization string", "UX copy", or "translation" -4. Request contains JSON structure with `"comment"` and `"value"` keys -5. Request mentions updating text in a locale file or resource bundle - -**If ANY pattern matches:** -- Set classification: **Localization/UI string change** -- Set recommended workflow: **[String-review]** -- Flag as *high confidence localization request* - ---- - -### 4. Apply Classification Logic +### 3. Apply Classification Logic If no pre-flight pattern matched, classify based on scope and complexity: @@ -144,15 +126,7 @@ _Rationale_: Full documentation planning required to ensure consistency and comp --- -#### **Localization/UI String Change** *(from pre-flight)* -_Indicators_: Matched pre-flight patterns (see step 2) - -_Recommended workflow_: **[String-review]** -_Rationale_: Specialized agent for UI copy review (style, localization readiness, legal compliance). - ---- - -### 5. Resolve Workflow Conflicts +### 4. Resolve Workflow Conflicts **If the user specified a workflow preference AND it differs from the recommended classification:** @@ -179,12 +153,12 @@ Proceed directly to step 5 with the recommended workflow. --- -### 6. Announce Classification and Execute +### 5. Announce Classification and Execute 1. **Announce your classification and selected workflow clearly:** ``` - **Classification:** [Direct fix | Single-topic change | Complex change | Localization string] + **Classification:** [Direct fix | Single-topic change | Complex change] **Workflow:** [Agent sequence] **Rationale:** [Why this workflow was chosen] ``` @@ -213,7 +187,7 @@ Proceed directly to step 5 with the recommended workflow. --- -### 7. Handle Uncertainty +### 6. Handle Uncertainty **If automated classification is uncertain** (e.g., insufficient context, ambiguous scope): - Present 2-3 most likely classifications with recommended workflows @@ -229,7 +203,6 @@ Proceed directly to step 5 with the recommended workflow. | **Direct fix** | [Draft-doc] → (optional) [Review-doc] | Typos, single-value corrections, well-defined minimal changes | | **Single-topic** | [LightPlan-doc] → [Draft-doc] → [Review-doc] | One file/topic, minor additions, localized scope | | **Complex** | [Plan-doc] → [Draft-doc] → [Review-doc] | Multiple topics/files, new structures, cross-product impact | -| **Localization** | [String-review] | en.json, UI strings, UX copy, translation updates | --- @@ -312,19 +285,7 @@ This requirement exists to ensure that the agent has complete information before --- -### Example 4: Pre-flight localization match -**User**: `Update en.json: change "Click here" to "Select an option"` - -**Agent**: -1. Pre-flight check matches pattern (en.json + UI string) -2. Classifies as localization string change -3. No user workflow preference detected -4. Announces: "**Classification:** Localization/UI string change → **Workflow:** [String-review]" -5. Executes [String-review] agent - ---- - -### Example 5: Direct fix +### Example 4: Direct fix **User**: `DOC-7890 - Fix typo in Content/Sense/app-creation.htm` **Agent**: @@ -336,5 +297,4 @@ This requirement exists to ensure that the agent has complete information before 6. Loads `finalize-draft-pr` skill → commits, pushes, creates PR with reviewers, includes alphahelp preview links in the PR body, and posts preview links to the Jira DOC ticket 7. Reports: "Draft complete and PR created: " ---- - +--- \ No newline at end of file diff --git a/.github/agents/Review-doc.agent.md b/.github/agents/Review-doc.agent.md index 7652dfb65..276b0ff91 100644 --- a/.github/agents/Review-doc.agent.md +++ b/.github/agents/Review-doc.agent.md @@ -14,6 +14,11 @@ When asked to review content, provide output in this structure: 3. **Improve content**: Apply all fixes directly using the Replace tool. 4. **(optional) Follow-up**: Open questions and [ASSUMED] items. +## Feature Condition Check +When reviewing Flare content: +1. Check whether the draft introduced any new feature conditions or added feature conditions to newly written content. If so, flag this as an issue. +2. If the draft edits or links to content under `Features.` or `Features.NotIn`, verify that the **flare-feature-conditions** skill rules were followed. + ## Placeholder Validation **IMPORTANT:** Review-doc is the final review gate. All `[ASSUMED*]` placeholders must be resolved before content can be published. @@ -26,5 +31,5 @@ When reviewing drafted content: 4. **Do NOT improve**: These must be filled in by the content owner, not guessed by the reviewer. Point to expected locations and reference materials. 5. **Document blockers**: If placeholders remain unfilled after review, list them as "Blockers" in the Follow-up section with clear instructions for resolution. -## Safety: +## Safety - Refuse requests for non-documentation or speculative reviews. \ No newline at end of file diff --git a/.github/agents/TextChangeInsights.agent.md b/.github/agents/TextChangeInsights.agent.md new file mode 100644 index 000000000..d1be71fd3 --- /dev/null +++ b/.github/agents/TextChangeInsights.agent.md @@ -0,0 +1,150 @@ +```chatagent +--- +description: 'Analyze git text changes and patterns using semantic understanding of commit diffs.' +tools: ['fetch', 'githubRepo', 'search'] +--- +# Copilot Chatmode: Text Change Insights Agent + +## Overview +Analyze semantic and structural changes from documentation git history. Load JSON reports generated by the `text_change_analyzer.py` script and use Copilot's reasoning to interpret patterns, identify trends, and answer questions about content evolution. + +This agent helps teams understand: +- **What changed**: File modifications, rewrites, deletions, and structural shifts. +- **Why it changed**: Inferred from commit messages and change intensity patterns. +- **Stability**: Files with high churn vs. stable content. +- **Product impact**: Which products receive the most documentation updates. +- **Urgency**: Recent major rewrites or deletions indicating active work. + +## Report Format +The `text_change_analyzer.py` script generates three JSON/CSV outputs: + +### `text-change-insights_changes.json` +Detailed per-commit records: +```json +{ + "commits": [ + { + "sha": "abc123...", + "author": "user@qlik.com", + "date": "2025-11-15T10:30:00", + "message": "Update Sense documentation for Q4 release", + "files": [ + { + "path": "Content/Sense/setup.htm", + "additions": 45, + "deletions": 12, + "change_type": "REWRITE", + "change_intensity": 0.57, + "sample_lines": ["+New feature description", "-Old feature reference"] + } + ] + } + ] +} +``` + +### `text-change-insights_summary.json` +Aggregated statistics: +- `by_period`: Changes bucketed by time (daily/weekly/monthly) +- `by_file`: File-level metrics (change count, types, last modified) +- `by_product`: Product-level aggregation (inferred from Content/ prefix) + +Change types: `ADDITION` (>90% new), `DELETION` (>90% removed), `REWRITE` (30-90% changed), `MINOR` (<30% changed) + +Change intensity: 0.0-1.0 ratio of lines affected relative to final file size. + +## Interaction Patterns + +### Pattern 1: Load Report and Summarize +**User**: "Summarize the text changes from the last 30 days" +**Agent**: +1. Fetch or load the JSON report (user may paste or reference artifact URL). +2. Analyze period, file, and product data. +3. Identify key trends (e.g., "Sense product saw 3x more rewrites than usual"). +4. List top files by activity and change type distribution. + +### Pattern 2: Trend Analysis +**User**: "Show me files with the most churn" +**Agent**: +1. Extract file-level metrics (change_count, avg_intensity). +2. Rank by volatility (high change count + high intensity). +3. Infer intent from commit messages and change samples. +4. Highlight potential refactors, structural updates, or ongoing maintenance. + +### Pattern 3: Product Health Check +**User**: "Which product documentation is most active?" +**Agent**: +1. Summarize by_product aggregations. +2. Show change frequency, rewrite patterns, and emerging areas. +3. Flag products with unusual patterns (e.g., sudden spike in deletions). + +### Pattern 4: Change Deep-Dive +**User**: "Tell me about the changes to Content/Sense/setup.htm" +**Agent**: +1. Extract commits affecting the file. +2. Analyze change types and intensities over time. +3. Compare rewrites vs. minor updates to infer stability. +4. Suggest if file is actively developed or recently stabilized. + +### Pattern 5: Semantic Change Classification +**User**: "Which changes look like style guide updates?" +**Agent**: +1. Identify commits with uniform, widespread changes (many files touched, consistent intensity). +2. Look for keywords in messages ("style", "terminology", "format"). +3. Distinguish from isolated content updates. + +## Usage in Workflow + +1. **Generate Report**: Run the GitHub Actions workflow "Text Change Insights Report" with parameters: + - `since`: "30 days ago" (or any Git date spec) + - `granularity`: "weekly" (default) + - `path_prefix`: "Content/Sense" (optional product filter) + +2. **Download Artifact**: Fetch `text-change-insights_summary.json` from the workflow run. + +3. **Load into Copilot**: Paste JSON or reference the artifact URL. + +4. **Ask Questions**: Use natural language to explore patterns: + - "Show file stability over time" + - "Which files have the most rewrites?" + - "Did Q4 release cause a spike in documentation changes?" + - "Summarize changes by product" + +## Analysis Capabilities + +### Stability & Health Metrics +- **Volatility**: Files with high change frequency + high intensity → potential refactors or active development. +- **Dormancy**: Files untouched for months → candidates for archival or cleanup. +- **Patterns**: Recurring updates to same file → ongoing maintenance or iteration. + +### Change Intent Inference +- **Rewrite spike** in a file → possible major feature, restructure, or standard compliance push. +- **Deletions cluster** → deprecation, cleanup, or scope reduction. +- **Additions spike** → new features, expanded guidance, or onboarding content. + +### Trend Detection +- **Temporal patterns**: More updates on specific days/weeks → release cycles, deadlines. +- **Product correlation**: Changes to one product correlate with another → shared dependencies, coordinated updates. + +## Completion Criteria +- Summary is concise and data-backed +- Patterns identified with supporting metrics +- Recommendations actionable (e.g., "This file needs review") +- Assumptions about intent are labeled as inferred + +## Safety & Scope +- Analysis is read-only (no edits to source files) +- Interprets metadata and patterns only; does not guess unmapped data +- Refer to commit messages for authoritative intent +- Flag ambiguous patterns that need SME review + +## Follow-up Options +- Load additional time ranges or products for comparison +- Drill into specific commits or files +- Export insights as Markdown/CSV for reporting +- Cross-reference with product releases or content calendars + +--- + +End of Copilot Chatmode: Text Change Insights Agent +``` diff --git a/.github/skills/dita-markup-validation/SKILL.md b/.github/skills/dita-markup-validation/SKILL.md index 6dcc9c892..4abd41a6e 100644 --- a/.github/skills/dita-markup-validation/SKILL.md +++ b/.github/skills/dita-markup-validation/SKILL.md @@ -19,7 +19,7 @@ This skill provides a structured validation checklist for DITA XML output genera ### 1. Tag Integrity - [ ] All opening tags have matching closing tags (e.g., `

    ...

    `, `...`) - [ ] No orphaned tags (e.g., `
  • ` without `
    • `, `` without ``) -- [ ] Self-closing tags are avoided in DITA (use full open/close pairs) +- [ ] Self-closing tags are avoided in DITA (use full open/close pairs). Exception: variable use identified by the `dita-variables` skill [../dita-variables/SKILL.md]. A DITA variable uses self-closing tags. - [ ] No extra closing tags or duplicate tag pairs - [ ] Tag names use correct DITA element names and casing (lowercase: `

    `, `

  • `, ``) diff --git a/.github/skills/flare-feature-conditions/SKILL.md b/.github/skills/flare-feature-conditions/SKILL.md new file mode 100644 index 000000000..9ef10bb80 --- /dev/null +++ b/.github/skills/flare-feature-conditions/SKILL.md @@ -0,0 +1,126 @@ +--- +name: flare-feature-conditions +description: "Use when adding, editing, or linking to any MadCap Flare content in help-documentation. Enforces the rule that feature conditions must never be created or added, and determines whether existing feature-conditioned content is safe to edit or link to." +--- + +# Flare feature conditions skill + +## Overview + +Use this skill when working with existing Flare feature conditions in the `Features` condition set, for example: + +- `MadCap:conditions="Features.TLV-123"` +- `MadCap:conditions="Features.DOC-123"` +- `MadCap:conditions="Features.SUPPORT-123"` +- `MadCap:conditions="Features.NotInTLV-123"` + +Do not apply this skill to other non-feature conditions. + +## Definitions + +- Feature condition: A normal feature condition such as `TLV-123`. +- Inverse condition: The paired `NotIn` condition, such as `NotInTLV-123`. + +"Link to" means creating or modifying a link whose target content is controlled by a feature condition. + +## Condition definitions and feature state + +`Project/ConditionTagSets/Features.flcts` defines which feature conditions exist. Do not use it to determine whether a feature is active. + +Resolve the effective state from the relevant `ProductScenarioFlags*.xml` files under `config/`. + +The config contains the state of the feature condition only, for example `TLV-123`. The inverse `NotInTLV-123` condition always represents the inverse of the same state. + +## Required behavior + +### Never creating or modifying feature conditions + +The agent must never create, add, change, or remove a `Features.*` feature condition. This applies to both new and existing content, regardless of whether surrounding content already has feature conditions. + +Specifically, the agent must **never**: + +- Create a new feature condition by adding an entry to `Features.flcts` or to any `ProductScenarioFlags*.xml` file. +- Add a `Features.*` value to a `MadCap:conditions` attribute. +- Change an existing `Features.*` value in a `MadCap:conditions` attribute. +- Remove a `Features.*` value from a `MadCap:conditions` attribute. +- Add a `MadCap:conditions` attribute containing a `Features.*` value to any element it creates or modifies. + +When adding content inside an existing conditioned section, place the new content inside the already-conditioned parent element. Do not add a condition attribute to the new content itself. Do not copy or reuse a feature condition from surrounding or nearby content onto any new element — the presence of a `Features.*` condition on existing content is not a reason to add it to new content. + +The agent may edit the content of an element that already has a `Features.*` condition when permitted by the decision rules below. It may also read and reason about existing feature conditions to decide whether to edit or link to conditioned content. It must never modify the conditions themselves. + +### Resolving a feature condition + +1. Detect whether the content or link target has a feature condition. + + Look for: + + - `Features.` + - `Features.NotIn` + + Ticket IDs use Jira-style letters, a hyphen, and numbers, such as `TLV-123`, `DOC-123`, or `SUPPORT-123`. + + Check the element itself **and all its ancestor elements** up to and including the root `` element. A condition on any ancestor applies to all content inside it. Apply the decision rules for every `Features.*` condition found at any level. + + If multiple `Features.*` conditions are found at different levels and any one of them resolves to a blocked or forbidden state, do not edit or link automatically. Flag all conditions found and their resolved states for the writer to decide. + + If no `Features.*` condition is found on the element or any of its ancestors, the remaining steps in this workflow do not apply. The hard bans above still apply in all cases. + +2. Extract the ticket ID from either condition form (for example, `TLV-123`). + +3. Search all `ProductScenarioFlags*.xml` files under `config/` for that ticket ID. Use a broad search pattern such as `config/**/ProductScenarioFlags*.xml` and check every result — do not stop after the first file returns no match. + +4. Resolve the feature state from the state attribute: + + - `state="on"`: the feature is on + - `state="off"`: the feature is off + + If the same ticket ID has conflicting states across config files, do not edit or link automatically. Flag the case as a conflicting config issue. + +5. If the ticket ID is not found, or its state cannot be resolved reliably, do not edit or link automatically. Flag the case for writer review. + +## Decision rules for edits and links + +Apply these rules exactly: + +| Existing condition | Base feature state | Decision | +|---|---|---| +| `Features.` | `on` | **Allowed** | +| `Features.` | `off` | **Blocked** — future content uncertainty | +| `Features.NotIn` | `off` | **Blocked** — writer review required | +| `Features.NotIn` | `on` | **Forbidden** — deprecated/hidden content | + +### Examples + +If config contains: + +`TLV-123` + +then: + +- `Features.TLV-123` is the active content and may be edited or used as a link target. +- `Features.NotInTLV-123` is the hidden/deprecated content and must not be edited or used as a link target. + +If config contains: + +`TLV-123` + +then: + +- `Features.TLV-123` represents future content. Do not edit or link to it automatically. Flag it for writer review. +- `Features.NotInTLV-123` is the alternate content currently shown, but do not edit or link to it automatically. Flag it for writer review. + +The agent must not infer permission from visibility alone. Follow the decision table above. + +## Handling blocked cases + +When an edit or link is blocked, report: + +- The feature condition found. +- The resolved feature state. +- The reason for blocking: + - `future content uncertainty` + - `deprecated/hidden content` + - `unresolved config state` + - `conflicting config issue` +- That writer review is required. diff --git a/.github/skills/repository-classifier/SKILL.md b/.github/skills/repository-classifier/SKILL.md new file mode 100644 index 000000000..212a0f8ed --- /dev/null +++ b/.github/skills/repository-classifier/SKILL.md @@ -0,0 +1,237 @@ +--- +name: repository-classifier +description: "Classify Jira tickets to the correct documentation repository based on Product field value. Uses direct mapping for most products and AI inference for ambiguous cases. Returns repository labels, automation skip flag, and optional notes. Use when: assessing documentation impact, routing tickets, or determining target repository for documentation changes." +--- + +# Repository Classifier Skill + +## Purpose + +Determine which documentation repository (or repositories) should handle a given Jira ticket based on the Product field value. For ambiguous product values, use AI inference from Jira context to make the classification. + +## Input + +Provide the following from the Jira ticket: +- **Product field** (`fields.customfield_10178`) +- **Description** (`fields.description`) +- **Summary** (`fields.summary`) +- **What's New content** (`fields.customfield_10478`) - optional + +## Output Format + +Return a JSON structure with two fields: + +```json +{ + "labels": ["repository-label"], + "note": "" +} +``` + +- **`labels`** (array): Repository label(s) to apply to the Jira ticket +- **`note`** (string): Explanation when AI inference was used + +## Classification Logic + +### Tier 1: Direct Mappings + +Most products map directly to a repository without AI inference needed: + +| Product Field Value | Repository Label | Notes | +|---|---|---| +| All products | `help-documentation` | | +| Compose | `help-documentation` | | +| Data Product Catalog | `help-documentation` | | +| Insight bot | `help-documentation` | | +| Inventory Heritage | `docs-core-cloud` | | +| Nprinting | `help-documentation` | | +| Pipeline Designer Heritage | `docs-core-cloud` | | +| Qlik Alerting | `help-documentation` | | +| Qlik Analytics Connector | `help-documentation` | | +| Qlik Answers | `help-documentation` | | +| Qlik Automation | `help-documentation` | | +| Qlik Data Gateway - Data Movement | `help-documentation` | | +| Qlik Data Gateway - Direct Access | `help-documentation` | | +| Qlik Insight Advisor | `help-documentation` | | +| Qlik Predict | `help-documentation` | | +| Qlik Proactive | `help-documentation` | | +| Qlik Sense | `help-documentation` | | +| Qlik Web Connectors (standalone) | `help-documentation` | | +| Qlikview | `help-documentation` | | +| QTC Data Movement | `help-documentation` | | +| QTC Pipelines | `help-documentation` | | +| QTC Stewardship | `help-documentation` | | +| Replicate | `help-documentation` | | +| RnD Operations | `help-documentation` | | +| Stewardship Heritage | `docs-core-80` | Assuming no more cloud changes | +| Stitch Heritage | `stitch-docs` | | +| TAC | `docs-core-80` | | +| Talend Data Preparation Heritage | `docs-core-80` | Assuming no more cloud changes | +| TMC | `docs-core-cloud` | | + +**For Tier 1 products:** +```json +{ + "labels": [""], + "note": "" +} +``` + +--- + +### Tier 2: Conditional Mappings (AI Inference Required) + +These products require examining Jira context to determine the correct repository: + +#### Data Processing + +**Possible repositories:** `help-documentation` OR `docs-core-cloud` + +**Decision criteria:** +- **help-documentation signals:** "Qlik", "Qlik Cloud" +- **docs-core-cloud signals:** "Talend" +- **Default if ambiguous:** `help-documentation` + +**Output when help-documentation:** +```json +{ + "labels": ["help-documentation"], + "note": "AI inference: Qlik Cloud signals detected - [list key signals]" +} +``` + +**Output when docs-core-cloud:** +```json +{ + "labels": ["docs-core-cloud"], + "note": "AI inference: Talend signals detected - [list key signals]" +} +``` + +#### APP-API Integration + +**Possible repositories:** `help-documentation` OR `docs-core-cloud` + +**Decision criteria:** +- **help-documentation signals:** Qlik +- **docs-core-cloud signals:** Talend +- **Default if ambiguous:** `help-documentation` + +**Output format:** Same structure as Data Processing above + +#### Studio + +**Possible repositories:** `docs-core-80` OR `docs-components` + +**Decision criteria:** +- **docs-core-80 signals:** Studio UI, Studio perspectives, editors, workspace features, Studio preferences, Studio-specific functionality, general Studio documentation +- **docs-components signals:** Individual components or connectors (tMap, tLogRow, tMysqlInput, etc.), component parameters, component library, Hadoop components, reusable component definitions +- **Default if ambiguous:** `docs-core-80` + +**Output when docs-core-80:** +```json +{ + "labels": ["docs-core-80"], + "note": "AI inference: Studio core functionality detected - [list key signals]" +} +``` + +**Output when docs-components:** +```json +{ + "labels": ["docs-components"], + "note": "AI inference: Component-related keywords detected - [list key signals]" +} +``` + +--- + +## Implementation Guidelines + +### Step 1: Extract Product Field + +Get the product value from `fields.customfield_10178`. If empty or null, check description for inline product mentions. + +### Step 2: Apply Classification Logic + +1. Check Tier 2 (conditional mappings) - if match found, run AI inference +2. Check Tier 1 (direct mappings) +3. If no match found: return empty labels and note the issue + +### Step 3: Run AI Inference (Tier 2 only) + +For conditional mappings: +1. Extract relevant keywords from description, summary, and What's New content +2. Score signals for each possible repository +3. Select repository with strongest signals +4. If tied or no clear signals: use default +5. Record detected signals in the `note` field for transparency + +### Step 4: Return Structured Output + +Always return the two-field JSON structure as specified above. + +--- + +## Error Handling + +**If product field is empty:** +- Check description for product mentions +- If still not found: return `{"labels": [], "note": "Product field is empty and no product mentioned in description"}` + +**If product value doesn't match any tier:** +- Return `{"labels": [], "note": "Unknown product value: [product value]. Manual classification required."}` + +--- + +## Examples + +### Example 1: Direct Mapping + +**Input:** +- Product: "Qlik Sense" + +**Output:** +```json +{ + "labels": ["help-documentation"], + "note": "" +} +``` + +### Example 2: AI Inference (Data Processing → Talend) + +**Input:** +- Product: "Data Processing" +- Description: "Add new scheduling feature in Talend Remote engine for SaaS users..." + +**Output:** +```json +{ + "labels": ["docs-core-cloud"], + "note": "AI inference: Talend signals detected - 'Talend'" +} +``` + +### Example 3: AI Inference (Studio → Components) + +**Input:** +- Product: "Studio" +- Description: "Update tMysqlInput component to support new authentication method. Add parameter for connection pooling to tMap component." + +**Output:** +```json +{ + "labels": ["docs-components"], + "note": "AI inference: Component-related keywords detected - 'tMysqlInput', 'tMap', 'component parameters'" +} +``` + +--- + +## Integration Notes + +This skill is designed to be invoked by: +- **Assess-doc-impact agent** - to apply repository labels during impact assessment + +The skill performs classification only - it does not apply labels or modify Jira tickets. The calling agent is responsible for using the output appropriately. diff --git a/.github/skills/talend-release-notes/SKILL.md b/.github/skills/talend-release-notes/SKILL.md index f5d1719a6..4b1cbbf8a 100644 --- a/.github/skills/talend-release-notes/SKILL.md +++ b/.github/skills/talend-release-notes/SKILL.md @@ -1,276 +1,276 @@ ---- -name: talend-release-notes -description: "Use when drafting or updating Talend monthly release notes in DITA. Enforces structure, metadata, file naming, and map integration across all release-note product areas in docs-core." ---- - -# Talend release-notes drafting - -Use this skill to create or update Talend release notes in docs-core with consistent monthly structure across all products and subsystems. - -## When to use - -Invoke this skill when all of the following are true: -- The current repository is `docs-core`. -- The request is for Talend monthly release notes in `en/release-notes/`. - -Use the following signals as supporting evidence: -- The request includes month keys like `RYYYY-MM`. -- The Jira `fixVersion` field includes a monthly value matching `RYYYY-MM` or `8.0.1-RYYYY-MM`. -- The request names one or more Talend release-note product areas. - -### When to create release notes during documentation work - -This skill also applies when **documenting any product change** (new features, notable fixes, deprecations, removals, or other updates) that warrants a release note entry. If the Jira task links to a product code issue (e.g., QTDM-*, TDP-*, etc.) marked Done, and the change introduces user-facing functionality or impacts product usage, create or update the corresponding monthly release note entry in addition to updating the product documentation. If the required monthly release-note files do not exist, create them as part of this work. Release notes are mandatory for product documentation work. - -## Inputs - -Supported product areas include: -- Monthly wrapper and highlights video (`RYYYY-MM_c.dita`, `RYYYY-MM-highlights-video_c.dita`). -- Talend Studio (`RYYYY-MM_studio_c.dita`, plus child topics such as `..._studio_new-features...`, `..._studio_notable-fixes...`, `..._studio_deprecated-removed-items...`). -- Talend Runtime (`RYYYY-MM_runtime_c.dita`). -- Talend Remote Engine (`RYYYY-MM_talend-remote-engine_c.dita`). -- Talend Dynamic Engine (`RYYYY-MM_dynamic-engine_c.dita` or existing month-specific variant). -- Talend Cloud Management Console (`RYYYY-MM_cloud-management-console_c.dita`). -- Talend Cloud API Designer (`RYYYY-MM_talend-cloud-api-designer_c.dita`). -- Talend Administration Center (`RYYYY-MM_administration-center_c.dita`). -- Talend Cloud Migration Toolkit (`RYYYY-MM-cloud-migration-toolkit_c.dita`). -- Installers and software requirements (`RYYYY-MM_installers_r.dita`, `RYYYY-MM_software-requirements_r.dita`). -- Talend Data Catalog wrapper and children (`RYYYY-MMcatalog81.dita`, `RYYYY-MM-talend-data-catalog-application81_r.dita`, `RYYYY-MM-talend-data-catalog-bridges81_r.dita`). - -If the month is missing, use `[ASSUMED-MONTH]` in planning notes only, add an adjacent follow-up note, and ask for month confirmation before creating or renaming monthly files. - -### Follow-up note placement (required) - -When assumptions or missing data remain, write follow-up notes in the source DITA file being updated or created (not only in chat output). - -- Place each follow-up note immediately next to the corresponding `[ASSUMED-*]` placeholder in the same paragraph, list item, or table cell. -- Each follow-up note must include the exact data required to replace that placeholder. -- If multiple release-note files are updated, add adjacent follow-up notes in each file that contains unresolved placeholders. - -## Required outputs - -Create or update only the product files requested for that month under `en/release-notes/` and update `en/maps-guides/release-notes-80.ditamap` when new monthly topics are introduced. If a required monthly release-note file does not exist yet, create it using the nearest existing month as the template pattern for the same product area. Do not skip a required release-note entry only because the target monthly file is missing. - -The final output must include: -- The updated monthly release-note file set for requested product area(s). -- Any required update to `en/maps-guides/release-notes-80.ditamap` when new monthly topicrefs are added. -- In-source adjacent follow-up notes for all unresolved placeholders (`[ASSUMED-*]`) and the exact data needed to replace them. - -For a new monthly product topic, ensure: -- File naming follows existing monthly patterns for that product area. -- Topic `id` and `pageid` are month-aligned and consistent with nearby months. -- Parent/child topicref placement matches the structure used by adjacent month entries. - -When a month-level wrapper (`RYYYY-MM_c.dita`) or product parent topic for that month is missing, create the missing parent first, then add the child entry in the proper location. - -## Procedure - -### Step 1 - Collect source inputs - -1. Read Jira source content for each release-note entry (summary, description, acceptance details, and relevant comments). -2. Read Jira `fixVersion` values and confirm the monthly key (`RYYYY-MM` or `8.0.1-RYYYY-MM`). -3. If source details are incomplete, keep wording conservative, add `[ASSUMED-DETAILS]`, and record required confirmations in an adjacent follow-up note. -4. If product-area targeting is unclear, add `[ASSUMED-PRODUCT-AREA]` and ask for confirmation before creating new product-specific files. - -### Step 2 - Identify month and target section - -1. Parse the target month in `RYYYY-MM` format. -2. Locate the month node in `en/maps-guides/release-notes-80.ditamap`. -3. Reuse the nearest existing month as the structural pattern when adding a new month or new product subsection. -4. If the month node is missing in the map, create the month wrapper and add its topicref in chronological position. -5. If the month exists but the required product topic or child topic does not, create the missing file and add its topicref under the correct month parent. - -### Step 3 - Classify entries - -Classify each item using the destination topic structure: -- If the target topic already has named sections (for example, New features for Talend Studio), place entries in the matching section. -- If the target topic is a general concept topic, integrate entries in its existing section model without forcing new section names. -- If creating a new table-based topic, use clear section/table headings aligned with existing product patterns for that month. - -If classification is unclear, keep wording conservative and mark assumptions with `[ASSUMED-CLASSIFICATION]`. - -Classification decision rules: -- Determine classification from the **nature of the product change** in the linked implementation - ticket(s) and acceptance details, not from the Documentation Jira issue type. -- `new-features`: - Use when the capability is additive or newly available to users. - Typical cues: "now available", "new option", "support for", "can now". - Issue-type hint: task/story items with additive user impact usually belong here. -- `notable-fixes`: - Use when the entry restores expected behavior, corrects an error, or resolves a broken workflow. - Typical cues: "issue fixed", "no longer fails", "workaround removed". - Issue-type hint: bug/defect items with corrective user impact usually belong here. -- `deprecated-removed-items`: - Use when the entry announces deprecation, end-of-support intent, or removal of a capability. - Typical cues: "deprecated", "removed", "no longer supported", "replaced by". - Issue-type hint: if functionality is deprecated or removed, classify here regardless of issue type. -- `known-issues` subsection: - If an issue remains unresolved in the release and requires a workaround, place it in the known-issues - portion of the notable-fixes/known-issues topic for that month. -- When uncertain, compare with the previous two monthly files in the same product area and follow - the dominant pattern; if still ambiguous, add `[ASSUMED-CLASSIFICATION]` and record the missing confirmation in an adjacent follow-up note. - -### Step 4 - Draft DITA topics - -Draft according to the existing topic type for the product area: -- Use `` as the default topic type for release-note topics. -- When updating an existing release-note file that is already a ``, keep its current type unless a migration is explicitly requested. -- Keep section names and structure aligned with adjacent monthly files for the same product area. -- Keep content concise and user-focused. -- In all `` content, keep `` content to direct text or inline elements only; do not use block elements such as `

    ` inside ``. - -#### Highlights video topic conventions - -The highlights video topic (`RYYYY-MM-highlights-video_c.dita`) has a fixed structure identical every month. Copy the previous month's file content and update only: -- The topic `id` and `pageid` to the new month -- The Vidyard URL (two occurrences: `data` attribute in `` and the thumbnail `` value) - -The user must supply the Vidyard URL for the new release. If not provided, use `[ASSUMED-VIDYARD-URL]` as a placeholder and record it in an adjacent follow-up note. - -#### Talend Studio topics conventions - -**Child topics**: The Talend Studio monthly entry (`_studio_c.dita`) can have the following child topics, in this order: -1. Software requirements (`_studio_software-requirements_r.dita`) — not always present -2. New features (`_studio_new-features_c.dita`) -3. Notable fixes and known issues (`_studio_notable-fixes-known-issues_c.dita`) — not always present -4. Deprecated and removed features (`_studio_deprecated-removed-items_c.dita`) — not always present - -Create only the child topics relevant to the release. Always use an empty `` in child topics. Only populate it when a release has a single defining theme that affects all users (for example, a mandatory platform requirement). That is an exception, not the default. - -**Sections in child topics**: The standard section order is: -1. Shared features -2. Application Integration -3. Big Data -4. Continuous Integration -5. Data Integration -6. Data Mapper -7. Data Quality - -Include only the sections that have entries for the release. Do not generate empty sections as placeholders. - -**Writing guidelines — new features** - -Each entry uses a two-column `` with headers `Feature` and `Description`. - -- **Feature (first column)**: Use the following naming patterns: - - New version or option supported: **Support for XXX (to XXX)** — e.g., "Support for Kafka version 3.2.x" - - New functionality or check box: **New option (for XXX) to do XXX** — e.g., "New option for tFileInputExcel to customize the ratio between deflated and inflated bytes to detect zip bomb" - - Enhancement of an existing item: **Enhancement of XXX to XXX** — e.g., "Enhancement of tFileInputDelimited to support dynamic schema in Spark Jobs" - - For component-related features, list component names or family names depending on how many are affected — e.g., "New components to connect to Google Bigtable to store or retrieve data" -- **Description (second column)**: Answer the following questions, when applicable: - - What does this new feature do? - - Why is this new feature useful for the user? -- You can include a screenshot (with a red frame) using `` inside a ``, and a link to a scenario if one exists. - -**Writing guidelines — notable fixes and known issues** - -This topic uses **two distinct `` elements**: one for notable fixes (`id="notable-fixes"`), one for known issues (`id="known-issues"`). Both use headers `Issue` and `Description`. - -- **Issue (first column)**: Describe the issue only — do not explain how it is solved. Use the following naming patterns: - - General issue: **Issue(s) when/with XXX** or **XXX when/with XXX** — e.g., "Issues when using a flattening map with EDI 834 documents", "Slow refresh of Job design when moving JDBC components in case of large database tables" - - Job-related issue: **Job(s) fail(s) to XXX** or **XXX fail(s) to XXX** — e.g., "Jobs fail when tab characters are used as delimiters in CSV files" - - Studio error message: do not copy the full message; use **An error occurs when/with XXX** — e.g., "An error occurs when tDBOutput receives data of FLOAT type from tDBInput through a dynamic column" -- **Description (second column)**: Answer the following questions, when applicable: - - What was the issue? - - How has it been fixed? - - What is the workaround if it is not fixed yet (if any)? -- **Never link to a Jira ticket or filter.** Talend projects are private; external users cannot access them. - -**Writing guidelines — deprecated and removed features** - -This topic uses **two distinct `` elements**: one for deprecated features, one for removed features. Both use headers `Item` and `Description`. - -- **Item (first column)**: Name of the deprecated or removed item. -- **Description (second column)**: Answer the following questions, when applicable: - - What has been removed or deprecated? - - Does the deprecation or removal apply to something specific only? - - What is used instead of the removed or deprecated item? - -**Writing guidelines - upcoming major changes** - -Do not create a dedicated child topic for upcoming major changes. Instead, add a `
    ` at the end of the application parent topic (for example, `_studio_c.dita`). Do not use ``; the section title is sufficient to signal importance. Do not use the phrase "breaking changes" in the title, but you may use it in the body text. - -#### Talend Dynamic Engine topic conventions - -The Dynamic Engine release-note topic is a single `` file (not split into child topics). Use a non-empty `` summarizing the top 1–3 themes in one sentence. - -Include only the sections that have content for the release, in this order: - -1. `upcoming-changes` — forward-looking warnings for the next release; name the target release period in the section title (e.g., "Upcoming changes in R2026-08"); omit if none -2. `new-features` — `` with `Feature` and `Description` columns; one row per feature or release milestone; use `` for version strings, keys, and commands -3. `maintenance-releases` — `` with `Release` and `Description` columns; link each row to its detailed changelog when one exists; omit if none -4. `known-limitations` — state the limitation, scope, and workaround together; prefer a two-column `` with `Impact scope` and `Workaround` when there are multiple entries; omit if none -5. `deprecated-and-removed-items` — same structure as `new-features`; if an item is removed without replacement, state that explicitly; omit if none - -#### Talend Catalog conventions -- Use `` for `RYYYY-MMcatalog81.dita` wrapper. -- Keep `` concise and aligned with existing monthly wrappers. -- Use `` for new `application81` and `bridges81` entries. -- When updating existing `application81` or `bridges81` files that are ``, keep their current type unless a migration is explicitly requested. - -**Bridge naming standards** - -- For import bridges, use the official bridge name only (for example, `Qlik Sense`, not `Qlik Sense import`). -- For export bridges, append `export` to the official bridge name (for example, `Erwin Data Modeler export`). -- Validate bridge names against Meta Integration Supported Tools: `https://metaintegration.net/Products/MIMB/SupportedTools.html`. - -**Catalog entry structure** - -- For both `application81` and `bridges81` topics, use two sections with two-column simple tables: - - `New features and improvements` with headers `Feature` and `Description`. - - `Notable fixes` with headers `Issue` and `Description`. -- Keep each description concise and specific; target short, user-focused entries. - -**Catalog file naming and metadata patterns** - -- Wrapper concept: `RYYYY-MMcatalog81.dita` - - Topic `id`: `rYYYY-MMcatalog81` - - `pageid`: `rYYYY-MM-catalog` -- Application reference: `RYYYY-MM-talend-data-catalog-application81_r.dita` - - Topic `id`: `rYYYY-MM-talend-data-catalog-application81_r` - - `pageid`: `rYYYY-MM-talend-data-catalog-application81` -- Bridges reference: `RYYYY-MM-talend-data-catalog-bridges81_r.dita` - - Topic `id`: `rYYYY-MM-talend-data-catalog-bridges81_r` - - `pageid`: `rYYYY-MM-talend-data-catalog-bridges81` - -Follow adjacent monthly files for exact casing, delimiters, and conref usage when existing repository patterns differ. - -### Step 5 - Apply naming and metadata rules - -Validate: -- File names, topic `id`, and `pageid` follow monthly conventions. -- Existing taxonomy conrefs are preserved. -- Metadata is aligned with adjacent monthly topics. -- Product naming is consistent with established release-note wording (for example: Talend Studio, Talend Runtime, Talend Remote Engine). - -### Step 6 - Update release-notes map - -In `en/maps-guides/release-notes-80.ditamap`: -1. Locate `RYYYY-MM_c.dita`. -2. Insert new product topicrefs only when new files are created for that month. -3. Preserve product ordering and nesting based on adjacent months. -4. For Catalog additions, nest `application81` and `bridges81` under `RYYYY-MMcatalog81.dita`. -5. Preserve existing indentation and order. -6. If the month node does not exist, add it and include all newly created in-scope product topicrefs needed for the requested entry. - -### Step 7 - Validate output - -1. Invoke `qlik-writing-guidelines` for style and clarity checks. -2. Invoke `dita-markup-validation` to validate DITA structure. -3. Fix validation issues before final output. - -## Constraints - -- Do not invent unsupported features, version numbers, or issue details. -- Do not modify `en/archive-release-notes/`. -- Keep changes scoped to the requested release notes. -- Record unresolved details as specific placeholders in `[ASSUMED-*]` format with adjacent in-source follow-up notes. - -## Completion checklist - -- Target month and product area(s) identified. -- Only in-scope product files updated. -- Existing topic type and section model respected. -- Map updated only when new monthly topicrefs were added. -- `qlik-writing-guidelines` and `dita-markup-validation` invoked. -- Adjacent in-source follow-up notes are present for all unresolved `[ASSUMED-*]` placeholders. +--- +name: talend-release-notes +description: "Use when drafting or updating Talend monthly release notes in DITA. Enforces structure, metadata, file naming, and map integration across all release-note product areas in docs-core." +--- + +# Talend release-notes drafting + +Use this skill to create or update Talend release notes in docs-core with consistent monthly structure across all products and subsystems. + +## When to use + +Invoke this skill when all of the following are true: +- The current repository is `docs-core`. +- The request is for Talend monthly release notes in `en/release-notes/`. + +Use the following signals as supporting evidence: +- The request includes month keys like `RYYYY-MM`. +- The Jira `fixVersion` field includes a monthly value matching `RYYYY-MM` or `8.0.1-RYYYY-MM`. +- The request names one or more Talend release-note product areas. + +### When to create release notes during documentation work + +This skill also applies when **documenting any product change** (new features, notable fixes, deprecations, removals, or other updates) that warrants a release note entry. If the Jira task links to a product code issue (e.g., QTDM-*, TDP-*, etc.) marked Done, and the change introduces user-facing functionality or impacts product usage, create or update the corresponding monthly release note entry in addition to updating the product documentation. If the required monthly release-note files do not exist, create them as part of this work. Release notes are mandatory for product documentation work. + +## Inputs + +Supported product areas include: +- Monthly wrapper and highlights video (`RYYYY-MM_c.dita`, `RYYYY-MM-highlights-video_c.dita`). +- Talend Studio (`RYYYY-MM_studio_c.dita`, plus child topics such as `..._studio_new-features...`, `..._studio_notable-fixes...`, `..._studio_deprecated-removed-items...`). +- Talend Runtime (`RYYYY-MM_runtime_c.dita`). +- Talend Remote Engine (`RYYYY-MM_talend-remote-engine_c.dita`). +- Talend Dynamic Engine (`RYYYY-MM_dynamic-engine_c.dita` or existing month-specific variant). +- Talend Cloud Management Console (`RYYYY-MM_cloud-management-console_c.dita`). +- Talend Cloud API Designer (`RYYYY-MM_talend-cloud-api-designer_c.dita`). +- Talend Administration Center (`RYYYY-MM_administration-center_c.dita`). +- Talend Cloud Migration Toolkit (`RYYYY-MM-cloud-migration-toolkit_c.dita`). +- Installers and software requirements (`RYYYY-MM_installers_r.dita`, `RYYYY-MM_software-requirements_r.dita`). +- Talend Data Catalog wrapper and children (`RYYYY-MMcatalog81.dita`, `RYYYY-MM-talend-data-catalog-application81_r.dita`, `RYYYY-MM-talend-data-catalog-bridges81_r.dita`). + +If the month is missing, use `[ASSUMED-MONTH]` in planning notes only, add an adjacent follow-up note, and ask for month confirmation before creating or renaming monthly files. + +### Follow-up note placement (required) + +When assumptions or missing data remain, write follow-up notes in the source DITA file being updated or created (not only in chat output). + +- Place each follow-up note immediately next to the corresponding `[ASSUMED-*]` placeholder in the same paragraph, list item, or table cell. +- Each follow-up note must include the exact data required to replace that placeholder. +- If multiple release-note files are updated, add adjacent follow-up notes in each file that contains unresolved placeholders. + +## Required outputs + +Create or update only the product files requested for that month under `en/release-notes/` and update `en/maps-guides/release-notes-80.ditamap` when new monthly topics are introduced. If a required monthly release-note file does not exist yet, create it using the nearest existing month as the template pattern for the same product area. Do not skip a required release-note entry only because the target monthly file is missing. + +The final output must include: +- The updated monthly release-note file set for requested product area(s). +- Any required update to `en/maps-guides/release-notes-80.ditamap` when new monthly topicrefs are added. +- In-source adjacent follow-up notes for all unresolved placeholders (`[ASSUMED-*]`) and the exact data needed to replace them. + +For a new monthly product topic, ensure: +- File naming follows existing monthly patterns for that product area. +- Topic `id` and `pageid` are month-aligned and consistent with nearby months. +- Parent/child topicref placement matches the structure used by adjacent month entries. + +When a month-level wrapper (`RYYYY-MM_c.dita`) or product parent topic for that month is missing, create the missing parent first, then add the child entry in the proper location. + +## Procedure + +### Step 1 - Collect source inputs + +1. Read Jira source content for each release-note entry (summary, description, acceptance details, and relevant comments). +2. Read Jira `fixVersion` values and confirm the monthly key (`RYYYY-MM` or `8.0.1-RYYYY-MM`). +3. If source details are incomplete, keep wording conservative, add `[ASSUMED-DETAILS]`, and record required confirmations in an adjacent follow-up note. +4. If product-area targeting is unclear, add `[ASSUMED-PRODUCT-AREA]` and ask for confirmation before creating new product-specific files. + +### Step 2 - Identify month and target section + +1. Parse the target month in `RYYYY-MM` format. +2. Locate the month node in `en/maps-guides/release-notes-80.ditamap`. +3. Reuse the nearest existing month as the structural pattern when adding a new month or new product subsection. +4. If the month node is missing in the map, create the month wrapper and add its topicref in chronological position. +5. If the month exists but the required product topic or child topic does not, create the missing file and add its topicref under the correct month parent. + +### Step 3 - Classify entries + +Classify each item using the destination topic structure: +- If the target topic already has named sections (for example, New features for Talend Studio), place entries in the matching section. +- If the target topic is a general concept topic, integrate entries in its existing section model without forcing new section names. +- If creating a new table-based topic, use clear section/table headings aligned with existing product patterns for that month. + +If classification is unclear, keep wording conservative and mark assumptions with `[ASSUMED-CLASSIFICATION]`. + +Classification decision rules: +- Determine classification from the **nature of the product change** in the linked implementation + ticket(s) and acceptance details, not from the Documentation Jira issue type. +- `new-features`: + Use when the capability is additive or newly available to users. + Typical cues: "now available", "new option", "support for", "can now". + Issue-type hint: task/story items with additive user impact usually belong here. +- `notable-fixes`: + Use when the entry restores expected behavior, corrects an error, or resolves a broken workflow. + Typical cues: "issue fixed", "no longer fails", "workaround removed". + Issue-type hint: bug/defect items with corrective user impact usually belong here. +- `deprecated-removed-items`: + Use when the entry announces deprecation, end-of-support intent, or removal of a capability. + Typical cues: "deprecated", "removed", "no longer supported", "replaced by". + Issue-type hint: if functionality is deprecated or removed, classify here regardless of issue type. +- `known-issues` subsection: + If an issue remains unresolved in the release and requires a workaround, place it in the known-issues + portion of the notable-fixes/known-issues topic for that month. +- When uncertain, compare with the previous two monthly files in the same product area and follow + the dominant pattern; if still ambiguous, add `[ASSUMED-CLASSIFICATION]` and record the missing confirmation in an adjacent follow-up note. + +### Step 4 - Draft DITA topics + +Draft according to the existing topic type for the product area: +- Use `` as the default topic type for release-note topics. +- When updating an existing release-note file that is already a ``, keep its current type unless a migration is explicitly requested. +- Keep section names and structure aligned with adjacent monthly files for the same product area. +- Keep content concise and user-focused. +- In all `` content, keep `` content to direct text or inline elements only; do not use block elements such as `

    ` inside ``. + +#### Highlights video topic conventions + +The highlights video topic (`RYYYY-MM-highlights-video_c.dita`) has a fixed structure identical every month. Copy the previous month's file content and update only: +- The topic `id` and `pageid` to the new month +- The Vidyard URL (two occurrences: `data` attribute in `` and the thumbnail `` value) + +The user must supply the Vidyard URL for the new release. If not provided, use `[ASSUMED-VIDYARD-URL]` as a placeholder and record it in an adjacent follow-up note. + +#### Talend Studio topics conventions + +**Child topics**: The Talend Studio monthly entry (`_studio_c.dita`) can have the following child topics, in this order: +1. Software requirements (`_studio_software-requirements_r.dita`) — not always present +2. New features (`_studio_new-features_c.dita`) +3. Notable fixes and known issues (`_studio_notable-fixes-known-issues_c.dita`) — not always present +4. Deprecated and removed features (`_studio_deprecated-removed-items_c.dita`) — not always present + +Create only the child topics relevant to the release. Always use an empty `` in child topics. Only populate it when a release has a single defining theme that affects all users (for example, a mandatory platform requirement). That is an exception, not the default. + +**Sections in child topics**: The standard section order is: +1. Shared features +2. Application Integration +3. Big Data +4. Continuous Integration +5. Data Integration +6. Data Mapper +7. Data Quality + +Include only the sections that have entries for the release. Do not generate empty sections as placeholders. + +**Writing guidelines — new features** + +Each entry uses a two-column `` with headers `Feature` and `Description`. + +- **Feature (first column)**: Use the following naming patterns: + - New version or option supported: **Support for XXX (to XXX)** — e.g., "Support for Kafka version 3.2.x" + - New functionality or check box: **New option (for XXX) to do XXX** — e.g., "New option for tFileInputExcel to customize the ratio between deflated and inflated bytes to detect zip bomb" + - Enhancement of an existing item: **Enhancement of XXX to XXX** — e.g., "Enhancement of tFileInputDelimited to support dynamic schema in Spark Jobs" + - For component-related features, list component names or family names depending on how many are affected — e.g., "New components to connect to Google Bigtable to store or retrieve data" +- **Description (second column)**: Answer the following questions, when applicable: + - What does this new feature do? + - Why is this new feature useful for the user? +- You can include a screenshot (with a red frame) using `` inside a ``, and a link to a scenario if one exists. + +**Writing guidelines — notable fixes and known issues** + +This topic uses **two distinct `` elements**: one for notable fixes (`id="notable-fixes"`), one for known issues (`id="known-issues"`). Both use headers `Issue` and `Description`. + +- **Issue (first column)**: Describe the issue only — do not explain how it is solved. Use the following naming patterns: + - General issue: **Issue(s) when/with XXX** or **XXX when/with XXX** — e.g., "Issues when using a flattening map with EDI 834 documents", "Slow refresh of Job design when moving JDBC components in case of large database tables" + - Job-related issue: **Job(s) fail(s) to XXX** or **XXX fail(s) to XXX** — e.g., "Jobs fail when tab characters are used as delimiters in CSV files" + - Studio error message: do not copy the full message; use **An error occurs when/with XXX** — e.g., "An error occurs when tDBOutput receives data of FLOAT type from tDBInput through a dynamic column" +- **Description (second column)**: Answer the following questions, when applicable: + - What was the issue? + - How has it been fixed? + - What is the workaround if it is not fixed yet (if any)? +- **Never link to a Jira ticket or filter.** Talend projects are private; external users cannot access them. + +**Writing guidelines — deprecated and removed features** + +This topic uses **two distinct `` elements**: one for deprecated features, one for removed features. Both use headers `Item` and `Description`. + +- **Item (first column)**: Name of the deprecated or removed item. +- **Description (second column)**: Answer the following questions, when applicable: + - What has been removed or deprecated? + - Does the deprecation or removal apply to something specific only? + - What is used instead of the removed or deprecated item? + +**Writing guidelines - upcoming major changes** + +Do not create a dedicated child topic for upcoming major changes. Instead, add a `
    ` at the end of the application parent topic (for example, `_studio_c.dita`). Do not use ``; the section title is sufficient to signal importance. Do not use the phrase "breaking changes" in the title, but you may use it in the body text. + +#### Talend Dynamic Engine topic conventions + +The Dynamic Engine release-note topic is a single `` file (not split into child topics). Use a non-empty `` summarizing the top 1–3 themes in one sentence. + +Include only the sections that have content for the release, in this order: + +1. `upcoming-changes` — forward-looking warnings for the next release; name the target release period in the section title (e.g., "Upcoming changes in R2026-08"); omit if none +2. `new-features` — `` with `Feature` and `Description` columns; one row per feature or release milestone; use `` for version strings, keys, and commands +3. `maintenance-releases` — `` with `Release` and `Description` columns; link each row to its detailed changelog when one exists; omit if none +4. `known-limitations` — state the limitation, scope, and workaround together; prefer a two-column `` with `Impact scope` and `Workaround` when there are multiple entries; omit if none +5. `deprecated-and-removed-items` — same structure as `new-features`; if an item is removed without replacement, state that explicitly; omit if none + +#### Talend Catalog conventions +- Use `` for `RYYYY-MMcatalog81.dita` wrapper. +- Keep `` concise and aligned with existing monthly wrappers. +- Use `` for new `application81` and `bridges81` entries. +- When updating existing `application81` or `bridges81` files that are ``, keep their current type unless a migration is explicitly requested. + +**Bridge naming standards** + +- For import bridges, use the official bridge name only (for example, `Qlik Sense`, not `Qlik Sense import`). +- For export bridges, append `export` to the official bridge name (for example, `Erwin Data Modeler export`). +- Validate bridge names against Meta Integration Supported Tools: `https://metaintegration.net/Products/MIMB/SupportedTools.html`. + +**Catalog entry structure** + +- For both `application81` and `bridges81` topics, use two sections with two-column simple tables: + - `New features and improvements` with headers `Feature` and `Description`. + - `Notable fixes` with headers `Issue` and `Description`. +- Keep each description concise and specific; target short, user-focused entries. + +**Catalog file naming and metadata patterns** + +- Wrapper concept: `RYYYY-MMcatalog81.dita` + - Topic `id`: `rYYYY-MMcatalog81` + - `pageid`: `rYYYY-MM-catalog` +- Application reference: `RYYYY-MM-talend-data-catalog-application81_r.dita` + - Topic `id`: `rYYYY-MM-talend-data-catalog-application81_r` + - `pageid`: `rYYYY-MM-talend-data-catalog-application81` +- Bridges reference: `RYYYY-MM-talend-data-catalog-bridges81_r.dita` + - Topic `id`: `rYYYY-MM-talend-data-catalog-bridges81_r` + - `pageid`: `rYYYY-MM-talend-data-catalog-bridges81` + +Follow adjacent monthly files for exact casing, delimiters, and conref usage when existing repository patterns differ. + +### Step 5 - Apply naming and metadata rules + +Validate: +- File names, topic `id`, and `pageid` follow monthly conventions. +- Existing taxonomy conrefs are preserved. +- Metadata is aligned with adjacent monthly topics. +- Product naming is consistent with established release-note wording (for example: Talend Studio, Talend Runtime, Talend Remote Engine). + +### Step 6 - Update release-notes map + +In `en/maps-guides/release-notes-80.ditamap`: +1. Locate `RYYYY-MM_c.dita`. +2. Insert new product topicrefs only when new files are created for that month. +3. Preserve product ordering and nesting based on adjacent months. +4. For Catalog additions, nest `application81` and `bridges81` under `RYYYY-MMcatalog81.dita`. +5. Preserve existing indentation and order. +6. If the month node does not exist, add it and include all newly created in-scope product topicrefs needed for the requested entry. + +### Step 7 - Validate output + +1. Invoke `qlik-writing-guidelines` for style and clarity checks. +2. Invoke `dita-markup-validation` to validate DITA structure. +3. Fix validation issues before final output. + +## Constraints + +- Do not invent unsupported features, version numbers, or issue details. +- Do not modify `en/archive-release-notes/`. +- Keep changes scoped to the requested release notes. +- Record unresolved details as specific placeholders in `[ASSUMED-*]` format with adjacent in-source follow-up notes. + +## Completion checklist + +- Target month and product area(s) identified. +- Only in-scope product files updated. +- Existing topic type and section model respected. +- Map updated only when new monthly topicrefs were added. +- `qlik-writing-guidelines` and `dita-markup-validation` invoked. +- Adjacent in-source follow-up notes are present for all unresolved `[ASSUMED-*]` placeholders.