Dot AI Changelog Fragment

Create Changelog Fragment

Create a towncrier changelog fragment for release notes when completing PRD work. This should be included in the PR so the fragment is reviewed along with the code changes.

Workflow

Step 1: Identify the PRD

If not already known from context, ask: "Which PRD should I create release notes for?"

Look for:

• PRD mentioned in recent conversation
• PRD referenced in current branch name (e.g., feature/prd-320-*)
• PRD file path provided by user

Step 2: Read the PRD Thoroughly

Read the entire PRD file to extract:

• Problem Statement: What user pain point was solved, why it mattered
• Solution Overview: What the feature does, how it works
• User Impact: Specific benefits, what users can now do
• Key Capabilities: Individual features, options, or modes added
• Technical Details: Configuration options, environment variables, commands
• Documentation Updates: Which docs were added or updated (check Milestones section)

Step 3: Determine Fragment Type

Read pyproject.toml to see the available fragment types. Each [[tool.towncrier.type]] section has:

• A comment above it describing when to use that type
• A directory field (the type identifier used in the filename, e.g., feature for .feature.md)

First, ask the breaking question — before matching the change to any other type. Determine whether this change is breaking as this project defines it: does it break compatibility with a prior release, or otherwise require existing users to take action to keep working? Read the project's breaking-type comment in pyproject.toml for the project-specific definition — it may be broader than an API/CLI change (for example a wire-protocol, on-disk-format, or other cross-process/compatibility contract, including a change that stays structurally compatible but shifts meaning). When the change matches that definition — or you are unsure and it plausibly could — prefer the breaking type. Under-classifying a breaking change is costly: it ships with the wrong version bump and with no breaking-change entry to warn users.

Otherwise, choose the type that best matches the PRD based on those descriptions.

Step 4: Write the Fragment

Create file: changelog.d/[issue-id].[type].md

IMPORTANT: Use flat structure, NOT subdirectories!

• ✅ Correct: changelog.d/329.feature.md
• ❌ Wrong: changelog.d/feature/329.md

Naming convention:

• issue-id: GitHub issue number from PRD (e.g., 320)
• type: Type identifier from step 3 (e.g., feature, bugfix, misc)

Content format:

## [Feature Title]

[Opening sentence: What this feature is and the problem it solves]

[Key capabilities paragraph: Specific things users can now do, with concrete examples]

[Configuration/usage paragraph if applicable: How to enable or use the feature]

[Documentation link if docs were updated]

Documentation links: If the PRD includes documentation updates, link to the relevant page on devopstoolkit.ai. The URL pattern is:

• https://devopstoolkit.ai/docs/{project}/{path}
• Where {project} is: mcp (dot-ai), controller (dot-ai-controller), ui (dot-ai-ui), or stack (dot-ai-stack)
• And {path} maps from the docs folder (e.g., docs/guides/mcp-recommendation-guide.md → guides/mcp-recommendation-guide)

Example: changelog.d/142.feature.md

## Multi-Cluster Management

Manage multiple Kubernetes clusters from a single dot-ai instance. Previously, each cluster required its own dot-ai deployment, making it difficult to compare configurations or apply consistent patterns across environments.

The `query` tool now accepts a `--cluster` flag to target specific clusters, and results indicate which cluster each resource belongs to. The `recommend` tool can generate manifests targeting different clusters with environment-specific customizations. Cross-cluster searches let you find resources across all connected clusters simultaneously—useful for tracking down where a particular workload is deployed. Cluster health aggregation shows a unified view of all clusters in the `version` output.

Configure additional clusters by adding kubeconfig contexts to `ADDITIONAL_KUBECONFIGS` (comma-separated paths). Each context becomes available as a cluster target. The default cluster remains the current kubeconfig context when no `--cluster` flag is specified.

See the [Multi-Cluster Setup Guide](https://devopstoolkit.ai/docs/mcp/setup/multi-cluster-setup) for configuration details and examples.

Step 5: Confirm Creation

Show the user:

1. The fragment file path created
2. The content written
3. Reminder to commit and push with the PR

Guidelines

• User-focused: Describe what users gain, not implementation details
• Specific: Include concrete examples of what each capability does
• Complete: Cover all major features added, not just the headline
• Present tense: "Tools now return..." not "Added support for..."
• No diary style: "Multi-Cluster Management" not "Added multi-cluster support"
• Include configuration: Mention environment variables, commands, or setup steps
• Link to docs: If PRD updated documentation, link to the specific page on devopstoolkit.ai