
contributor-writing
- GitHub stars
- 47
Install
/plugin install contributor-writing@shopware-ai-coding-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add shopwareLabs/ai-coding-tools.
Contents
Discovered from sourceSkills 5
ADR Writing
Mode Detection
- Creation: "create", "write", "new", "draft"
- Validation: "validate", "check", "verify", "review"
Front Matter
---
title: Short descriptive title
date: YYYY-MM-DD
area: core
tags: [relevant, tags]
---
title(required): Short, descriptive. Do NOT repeat as a Markdown#headingdate(required):YYYY-MM-DDarea(required): One of:core,checkout,admin,storefront,inventory,framework,discovery,infrastructure,processtags(required): Lowercase technical terms, YAML arrayauthors,status(optional)
Required Coverage
Every ADR must address all 8 items:
- Complete description of the requirements
- All technical domains affected
- All affected logic in the system
- Pseudocode for new logic
- All public APIs to be created or changed
- How developers can extend the new APIs and what business cases you see
- The reason for the decision
- All consequences and their impact on developers
Writing Principles
- Audience: Shopware developers familiar with the codebase — no need to explain DAL, Symfony, Vue, Criteria, SalesChannelContext
- Voice: Direct, informal, developer-to-developer
- Factual over promotional: Describe what changes and why ("simplifies the caching logic", "removes manual transaction handling"). Never use marketing language ("greatly enhanced", "stands to benefit significantly"). Quantitative claims only when backed by explicit data the author provides — never estimate or guess numbers
- Prose for reasoning, plain bullets only for discrete independent items
- One decision per ADR
- Rationale focus: The "why" is the most valuable part
Load references/writing-style.md for voice examples, table/diagram guidance
Creation Workflow
Step 1: Gather Context
AskUserQuestion to collect: topic/title, area (present enum), tags, scope (single vs multi-domain).
If topic already provided, infer what you can before asking.
Step 2: Select Structure
Load references/structure-patterns.md for templates and examples
Single domain → Context / Decision / Consequences:
## Context
[Problem, background, constraints — problem before solution]
## Decision
[What was decided, pseudocode, public API definitions]
## Consequences
[Developer impact, backward compatibility, migration path]
Multi-domain → Domain-by-domain:
##heading per domain- 1-2 sentences on relevance, then Problems (what logic to touch and why), then Solutions (how to change it with pseudocode)
- Extendability section
- Consequences section
Additional sections when appropriate: Extendability, Considered Alternatives, Backward Compatibility, Security Considerations.
Step 3: Draft ADR
- Front matter with today's date (use
date +%Y-%m-%dvia Bash) - Context first — always explain problem before solution
- Address all 8 required coverage items
- Load
references/code-in-adrs.mdwhen writing code sections - Load
references/shopware-patterns.mdfor feature flags, cross-references, audience-specific consequences - Load
references/writing-rules-anti-ai-slop.mdto internalize style constraints and anti-slop rules
Step 4: Self-Validate
Verify all 8 required coverage items are addressed. If gaps exist, ask user for missing information.
Also ask about optional concerns: feature flag gating, backward compatibility implications, alternative approaches considered, related ADRs to cross-reference.
Step 5: Validate and Write
- Anti-slop validation pass — load
references/writing-rules-anti-ai-slop.md, then check the draft literally (not from memory):- First: search the draft text for em dash (—) and en dash (–) characters. Remove every instance. This is the most common violation and must be checked first as a literal character search, not a mental scan.
- Then re-read each sentence against: banned vocabulary, banned sentence patterns, colon/semicolon overuse, sentence rhythm, concreteness, tone
- If any violations found, rewrite the affected sentences and re-check
- Filename:
YYYY-MM-DD-kebab-case-title.md - Write to
adr/directory if it exists, otherwise ask user for target directory - Confirm creation with file path
Validation Workflow
Step 1: Load and Parse
Read file, parse YAML front matter, identify ## section headings.
Step 2: Check Front Matter
Verify: title present, date valid YYYY-MM-DD, area from allowed enum, tags lowercase array, no # heading duplicating title.
Step 3: Check Content
Load references/validation-checklist.md for detailed criteria
Load references/writing-rules-anti-ai-slop.md for anti-slop checks
Check all 8 required coverage items, structure compliance, writing style, anti-slop rules, code quality, Shopware-specific patterns.
Step 4: Generate Report
ADR Validation Report
=====================
File: [filename]
Title: [title]
Front Matter: [✓/✗]
[issues if any]
Required Coverage: [✓/⚠/✗]
[per-item breakdown]
Structure: [✓/⚠]
[type detected, issues]
Style: [✓/⚠]
[issues if any]
Anti-Slop: [✓/⚠]
[issues if any]
Shopware Patterns: [✓/⚠]
[issues if any]
Recommendations:
1. [actionable items]
Error Handling
- No ADR directory: Ask user for target path
- File exists (creation): Ask to overwrite or rename
- Invalid front matter (validation): Report parsing errors
- Missing file (validation): Report not found
Commit Message Generation
Generate conventional commit messages for Shopware core. Squash merge titles (title-only) for trunk merges and full commit messages (title + body) for branch work.
Output scope: Presents formatted commit message text. Does not create commits, write files, or modify git state.
Phase 1 — Detect Mode and Gather Context
Determine what we're generating — a squash merge title or a branch commit message.
- Parse user input:
- Commit ref provided (SHA, HEAD, HEAD~3, etc.) -> branch mode, resolve to SHA
- Branch ref, "squash", "current branch", or "merge commit" -> squash mode
- Nothing specific -> branch mode, use HEAD
- Gather the diff:
- Branch mode:
git show <sha> --name-status --format=''andgit show <sha> --format='' - Squash mode: Continue to step 3
- Branch mode:
- Squash mode only — detect base branch: Load
references/branch-and-pr-detection.mdand execute Steps 1-4. Route ascommit-message-writing. - Squash mode only — get branch diff:
git diff <base>...HEAD --statandgit diff <base>...HEADgit log <base>..HEAD --oneline
Phase 2 — Analyze and Generate
Type Detection
Analyze the diff to determine the commit type. Priority-ordered decision tree:
- Revert commit? ->
revert - Only docs (*.md, docblocks, inline comments)? ->
docs - Only formatting/whitespace changes? ->
style - Only test files? ->
test - Only build/dependency files (composer.json, package.json, Dockerfile)? ->
build - Only CI config (.github/workflows/, .gitlab-ci.yml)? ->
ci - Adds new user-facing functionality? ->
feat - Fixes broken behavior? ->
fix - Performance improvement (caching, query optimization, reduced allocations)? ->
perf - Code restructuring without behavior change? ->
refactor - Otherwise ->
chore
When ambiguous (e.g., both feat and fix equally present), ask the user:
AskUserQuestion(
question="This branch contains both new functionality and bug fixes. Which type best represents the primary purpose?",
options=[
{label: "feat", description: "The main goal is new functionality"},
{label: "fix", description: "The main goal is correcting broken behavior"}
]
)
Scope Detection
Delegate to references/scope-inference.md. Pass the list of changed file paths and the base branch (for commit history lookup in squash mode) or HEAD~20 (for branch mode).
Breaking Change Detection
Scan the diff for breaking changes:
- API signature changes (required parameters added, removed, or reordered)
- Public methods or classes removed or renamed
- Return types changed on public methods
- Database schema breaking changes (column removal, type change)
- Default behavior changed in ways that affect existing callers
If detected, add the ! marker after scope in the output.
Subject
Craft the subject line. Apply references/writing-rules.md.
- Imperative mood, lowercase, no period, max 72 characters total
- Informed by the diff (truth) and commit messages (intent context, squash mode only)
- Specific: name the component and behavior, not abstract descriptions
- No PR number (GitHub adds it during squash merge)
- No AI/tool attribution
Body (Branch Mode Only)
Craft the body. Apply references/writing-rules.md.
- WHY-not-WHAT: explain motivation, root cause, trade-offs
- Blank line between subject and body
- Single continuous lines per paragraph (no hard-wrapping)
- Concrete: class names, config keys, method signatures
- If breaking: include
BREAKING CHANGE:footer with brief description
Phase 3 — Validate and Present
Before presenting, validate the generated message against references/writing-rules.md:
- Em dash check: Literally search the generated text for
—and–. Replace any found. - Banned vocabulary: Scan for words from the banned list. Replace with plain alternatives.
- Subject rules: Verify imperative mood, lowercase, no period, within 72 characters, no attribution.
- Body rules (branch mode): Verify WHY-not-WHAT, no diff restatement, concrete specifics.
Squash mode:
type(scope): subject
Branch mode:
type(scope): subject
Body explaining why this change was made.
Or with breaking change:
type(scope)!: subject
Body explaining why this change was made.
BREAKING CHANGE: brief description of what breaks.
After the message, show brief reasoning (one line each):
- Type:
feat— adds new maxLength parameter to attribute entity fields - Scope:
dal— all changes within DataAbstractionLayer, matches trunk history
Done. No file writes, no git operations beyond read-only commands.
Feature-Branch PR Description Drafting
Draft a PR title (conventional commit format) and description (narrative prose with topical subsections) for PRs targeting non-trunk feature branches. Analyzes the diff against the target branch, detects related PRs in the chain, and asks targeted questions for missing context.
Output scope: Presents formatted title + description text. Does not create or update PRs on GitHub. Does not write to any files.
Phase 1 — Assess Branch State
Determine what we're working with: branch, target, PR status, diff, and chain.
- Load
references/branch-and-pr-detection.mdand execute Steps 1-4. Route asfeature-branch-pr-writing. - Get the diff:
- If a PR exists: read its diff and changed files from GitHub (a GitHub MCP server, the
ghCLI, or the API — whatever the session has) - If no PR: run
git diff <target>...HEAD --statandgit log <target>..HEAD --oneline
- If a PR exists: read its diff and changed files from GitHub (a GitHub MCP server, the
- Chain detection: list PRs targeting the same feature branch (via the same GitHub access). Record titles, numbers, merge state, and any cross-references in bodies. Identify predecessor/successor relationships.
- Present a brief assessment to the user: branch name, target branch, PR status (exists / doesn't exist / has existing description), change magnitude (files touched, lines changed, areas affected), related PRs in the chain.
Phase 2 — Analyze Changes
Understand the full story of the branch relative to the target.
- Synthesize the full branch scope from the diff, commits, and file changes. Understand the totality: features, fixes, cleanups, refactors.
- Determine scope: map file paths to Shopware areas. This informs the conventional commit scope for the title.
| File path pattern | Scope |
|---|---|
src/Core/Checkout/Cart/ | cart |
src/Core/Checkout/Order/ | order |
src/Core/Checkout/Promotion/ | promotion |
src/Core/Content/Product/ | product |
src/Core/Content/Media/ | media |
src/Core/Content/Category/ | category |
src/Core/Content/Cms/ | cms |
src/Core/Content/Mail/ | mail |
src/Core/Framework/DataAbstractionLayer/ | dal |
src/Core/Framework/App/ | app-system |
src/Core/System/SystemConfig/ | system-config |
src/Core/System/NumberRange/ | number-range |
src/Storefront/ | storefront |
src/Administration/ | admin |
src/Elasticsearch/ | elasticsearch |
For changes spanning multiple areas, use the scope of the primary story. If no specific scope fits, omit the parenthetical scope entirely: fix: description.
- Identify narrative candidates. A branch often contains multiple threads. Present them to the user:
"This branch contains: (a) ..., (b) .... What's the primary story?"
- The user confirms or reframes the story. This drives the title's type/scope and which aspects get depth vs. a brief mention.
- Assess description depth based on the confirmed story's complexity.
- Leverage session context: if the user has been debugging, implementing, or discussing in the current session, use that knowledge. Don't re-ask what's already known.
Phase 3 — Gather Context
Fill the gaps. Ask targeted questions only for information not in the diff, chain detection, or session context.
- Inventory what's known from the diff, chain, and session:
- Why the change was made (motivation)
- What changed (from diff)
- Which prior PRs established the pattern
- Related PRs (blocked by, follows, follow-up)
- Design alternatives considered
- Trade-offs or limitations
- Tracking issue
- Ask only what's missing, one question at a time:
- "What triggered this change?"
- "Which prior PR established the pattern being followed?"
- "Are there PRs blocked by this one?"
- "Were there design alternatives you considered and rejected?"
- "Should reviewers know about any deliberate trade-offs or limitations?"
- "Is there a tracking issue for this feature?"
- Skip questions the session already answers. If the user has been working on this and the session contains motivation, design decisions, and chain context, go straight to drafting.
- Load
references/writing-rules.mdto internalize style constraints and anti-slop rules.
Phase 4 — Draft
Generate the conventional commit title and narrative description.
- Load
references/description-examples.mdfor sizing calibration - Generate the title:
<type>(<scope>): <description>
| Type | When to use |
|---|---|
fix | Bug fix |
feat | New feature or capability |
refactor | Code restructuring with no behavioral change |
perf | Performance improvement |
chore | Maintenance, dependency updates, tooling |
docs | Documentation only |
test | Test additions or corrections |
style | Code style (formatting, semicolons, etc.) |
Title description rules: imperative mood, lowercase first letter, no period, under ~60 characters after type/scope. Describe the behavioral change, not the implementation.
- Draft the description:
- Opening context paragraph: state the prior situation, what this PR does about it, and reference predecessor PRs in the chain when applicable.
- Topical
###subsections: each covers one concern or aspect of the change. Choose headers based on what the PR actually does, not from a fixed list. Good: "Event-based type override", "DI decentralization". Bad: "Changes", "What changed", "Updates". - Tables for structured mappings (file moves, new classes with locations, config key changes, loader-to-route delegations).
## Referencessection at the end with cross-references:Ref #issue,Blocked by #PR,Follows #PR,Follow-up: #PR. Never useclosesorfixes.
- Self-check each subsection: state in one sentence what contract it describes (what goes in, what comes out, why it exists). If you can't collapse the subsection to one contract-level sentence, it's restating the diff. Rewrite.
- Diagram reasoning (two steps):
- Would the reviewer understand this better by seeing it than reading about it? If no, skip.
- If yes: can it fit one focused diagram, or should it split by concern? A single diagram that tries to show everything is as hard to follow as the prose it replaced.
- Scale length to complexity:
- Small (~2 paragraphs, 2 subsections): single-concern refactors, review feedback fixes.
- Medium (~3 paragraphs, 3-4 subsections, tables): multi-file features following established patterns, structural moves.
- Large (~6+ paragraphs, 6+ subsections, tables, potentially diagrams): new subsystems with multiple integration points.
- Determine the tier from the story's complexity, not the diff size.
- Present the full draft to the user: title clearly labeled, then the description formatted as GitHub markdown
Phase 5 — Validate and Present
Verify the draft against anti-slop rules, then deliver.
- Anti-slop validation pass — load
references/writing-rules.md, then check the draft literally (not from memory):- First: search the draft text for em dash (—) and en dash (–) characters. Remove every instance. This is the most common violation and must be checked first as a literal character search, not a mental scan.
- Second: for each subsection, verify it states a contract, not implementation steps. If a paragraph walks through method internals a reviewer will see in the diff, compress to contract level.
- Then re-read each sentence against: banned vocabulary, banned sentence patterns, banned formats, colon/semicolon overuse, sentence rhythm, tone
- If any violations found, rewrite the affected sentences and re-check the rewritten sentences
- Output the title — clearly labeled, in conventional commit format
- Output the description — as GitHub-rendered markdown (no hard line wraps, let lines run to natural length)
- Flag any assumptions: inferred chain relationships, guessed issue numbers, trade-off decisions the user should verify
- If the user wants changes, revise and present again
- Do not create PRs, update PRs, or write to any files. The user takes the output and uses it as they see fit.
Boundaries
- Never create or update PRs on GitHub
- Never write to any files
- Never auto-commit
- Only present formatted text output for the user to use
- Works on feature branches targeting non-trunk branches only
PR Description Drafting
Draft a PR title (conventional commit format) and description (Shopware's 5-section template) by analyzing the full branch scope, leveraging session context, and asking targeted questions for missing context.
Output scope: Presents formatted title + description text. Does not create or update PRs on GitHub. Does not write to any files.
Phase 1 — Assess Branch State
Determine what we're working with — branch, PR status, and diff.
- Load
references/branch-and-pr-detection.mdand execute Steps 1-4. Route aspr-description-writing. - Get the diff:
- If a PR exists: read its diff and changed files from GitHub (a GitHub MCP server, the
ghCLI, or the API — whatever the session has) - If no PR: run
git diff trunk...HEAD --statandgit log trunk..HEAD --oneline
- If a PR exists: read its diff and changed files from GitHub (a GitHub MCP server, the
- Present a brief assessment to the user: branch name, PR status (exists / doesn't exist / has existing description), change magnitude (files touched, lines changed, areas affected)
Phase 2 — Analyze Changes
Understand the full story of the branch — not just individual file changes.
- Synthesize the full branch scope from the diff, commits, and file changes. Understand the totality: features, fixes, cleanups, refactors — everything that happened on this branch.
- Determine scope: map file paths to Shopware areas (Core, Storefront, Administration, App System, etc.). This informs the conventional commit scope for the title.
- Identify the narrative candidates. A branch often contains multiple threads — a feature plus cleanup plus a fix discovered along the way. Present these to the user:
"This branch contains: (a) a new endpoint for X, (b) a fix for null handling in Y, (c) cleanup of unused imports. What's the primary story?"
- The user confirms or reframes the story. This drives the title's type/scope and which aspects get depth vs. a brief mention. If secondary threads remain (cleanup, test improvements, incidental fixes), offer them as an "Additional Changes" section: "The test cleanup / refactor / fix isn't part of the main story. Want it mentioned in an Additional Changes section at the end?" Only offer when the secondary work has educational value (practices not widely known in the project) or touches files a reviewer might otherwise question.
- Assess description depth based on the confirmed story:
- Bug fix → root cause analysis in Why, reproduction steps important
- New feature → usage context in What, scope boundaries valuable
- Breaking change → migration guidance needed
- Performance → quantified improvement expected
- Leverage session context: if the user has been debugging, implementing, or discussing in the current session, use that knowledge. Don't re-ask what's already known.
Phase 3 — Gather Context
Fill the gaps — ask targeted questions only for information not in the diff or session context.
- Inventory what's known from the diff and session:
- Why the change was made (motivation)
- What changed (from diff)
- How to reproduce the issue/behavior
- Related issues or PRs
- Breaking changes or deprecations
- Ask only what's missing, one question at a time:
- "What triggered this change? Bug report, user complaint, or internal decision?"
- "Is there a GitHub issue for this?"
- "How would someone reproduce the original problem?"
- "Is this behind a feature flag?"
- "Are there downstream PRs or related changes in other repos?"
- "Should reviewers know about any deliberate trade-offs or limitations?"
- Skip questions the session already answers. If the user just spent time debugging and the session contains root cause, reproduction, and fix rationale — go straight to drafting.
- Load
references/writing-rules.mdto internalize style constraints and anti-slop rules.
Phase 4 — Draft
Generate the conventional commit title and full PR description.
- Load
references/pr-description-examples.mdfor sizing calibration - Load
references/template-structure.mdfor output format - Generate the title:
<type>(<scope>): <description>— type from the confirmed story, scope from file path analysis, description short and imperative - Draft description sections 1-4 following the template structure and writing rules
- Self-check each section: state in one sentence what contract it describes (what goes in, what comes out, why it exists). If you can't collapse the section to one contract-level sentence, it's restating the diff. Rewrite.
- Calibrate total density for sections 1-3 combined based on explanation complexity:
- Small (< 20 lines): Self-explanatory from title + a few sentences. Simple constraints, obvious fixes, straightforward config.
- Medium (20-50 lines): Needs context not obvious from the diff. Non-trivial root causes, behavioral changes with reproduction, features needing usage explanation. Most PRs land here.
- Large (50+ lines): Complete new feature with new integration points — the kind of change that justifies a presentation. New API surfaces, new subsystems, architectural decisions.
- Determine the tier from the story, not the diff size. A 2-line fix requiring trace through three code paths is medium, not small.
- Add enhancements where they genuinely help reviewers (see template-structure.md for rules)
- If the user opted in during Phase 2, draft an "Additional Changes" section after section 4 (see template-structure.md for format)
- Present the full draft to the user: title clearly labeled, then all description sections formatted as GitHub markdown
Phase 5 — Validate and Present
Verify the draft against anti-slop rules, then deliver.
- Anti-slop validation pass — load
references/writing-rules.md, then check the draft literally (not from memory):- First: search the draft text for em dash (—) and en dash (–) characters. Remove every instance. This is the most common violation and must be checked first as a literal character search, not a mental scan.
- Second: for each section, verify it states a contract, not implementation steps. If a paragraph walks through method internals a reviewer will see in the diff, compress to contract level.
- Then re-read each sentence against: banned vocabulary, banned sentence patterns, banned formats, colon/semicolon overuse, sentence rhythm, tone
- If any violations found, rewrite the affected sentences and re-check the rewritten sentences
- Output the title — clearly labeled, in conventional commit format
- Output the description — full template with all sections as GitHub-rendered markdown (not commit message format: no hard line wraps, let lines run to natural length)
- Flag any assumptions: inferred reproduction steps, guessed issue numbers, trade-off decisions the user should verify
- If the user wants changes, revise and present again
- Do not create PRs, update PRs, or write to any files. The user takes the output and uses it as they see fit.
Boundaries
- Never create or update PRs on GitHub
- Never write to any files
- Never auto-commit
- Only present formatted text output for the user to use
- Works on feature branches only — not on
trunk
Release Info Drafting
Draft entries for RELEASE_INFO-6.x.md and UPGRADE-6.x.md in the Shopware core repository. The skill auto-generates the mechanical "what changed" from code analysis but requires human input for "why external developers should care."
File write scope: Edit only RELEASE_INFO-6.*.md and UPGRADE-6.*.md. Read everything else.
Phase 1 — Detect Target Files
Parse .danger.php in the repo root to get the canonical file names CI enforces.
- Read
.danger.php - Look for lines matching
matches('RELEASE_INFO-— extract the file name from the string argument (e.g.,RELEASE_INFO-6.7.md) - Look for lines matching
matches('UPGRADE-or referencingUPGRADE-in failure messages — extract the file name (e.g.,UPGRADE-6.8.md) - Fallback: If parsing fails, glob for
RELEASE_INFO-6.*.mdandUPGRADE-6.*.mdin the repo root. Pick the file with the highest version number. - Last resort: Ask the user for the file names.
Verify both files exist before proceeding.
Phase 2 — Analyze Branch Scope
Understand the full story of the branch, not just individual changes.
- Get the full diff against
trunk:- If a PR exists, use the PR diff and PR files tools
- Otherwise, run
git diff trunk...HEAD --statandgit log trunk..HEAD --oneline
- Use session context — what the user has been working on and why
- Synthesize the narrative: a PR may touch features, fixes, and cleanups. Identify what's most important — what's the story of these changes?
- Classify using the decision tree below
- If the changes are not externally relevant: tell the user with reasoning, offer to proceed anyway
Classification Decision Tree
Step 1 — Is this externally relevant?
Skip if ALL are true:
- No public API changes (no new/changed/removed public methods, interfaces, routes)
- No behavioral changes visible to extensions or integrations
- No new features, extension points, or config options
- No deprecation annotations added
- Only test files, internal refactoring, or non-critical bug fixes
Step 2 — Which files need entries?
| Signal in diff | RELEASE_INFO | UPGRADE |
|---|---|---|
| New public feature / extension point | Yes | No |
| New/changed config option | Yes | No |
Deprecation added (@deprecated) | Yes | Yes (next major) |
| Method/class removed | No | Yes |
| Method signature changed (breaking) | Possibly | Yes |
| Behavioral change (non-breaking but notable) | Yes | No |
| Behavioral change (breaking) | Yes | Yes |
| Critical bug fix | Yes | No |
| New API endpoint | Yes | No |
| API endpoint removed/changed | Yes | Yes |
Step 3 — Present classification to user:
"Based on the branch changes, this looks like [classification]. I'd suggest entries in [file(s)]. Does that match your intent?"
The user can override — they know the story better than the diff.
Phase 3 — Gather Context
- After the user confirms the classification, ask targeted questions the skill cannot infer from code. Ask only what's needed — skip questions the session context already answers:
- "Why should external developers care about this change?"
- "Are there migration steps needed?" (only if UPGRADE entry required)
- "Is this behind a feature flag?"
- Load
references/writing-rules.mdfor style guidance - Read 2-3 existing entries from the target category in the target file for voice and density calibration
Phase 4 — Draft Entries
- Load
references/entry-examples.mdfor sizing calibration - Load
references/file-structure.mdfor heading hierarchy and placement rules - Scan all categories in the entire target file (not just the upcoming section) to discover the full category set
- Propose a category based on file paths changed. Present the full category list and let the user confirm or pick a different one.
- Draft the entry/entries:
- Size to the magnitude of change (see entry-examples.md for tiers)
- Follow the writing rules (see writing-rules.md)
- Match the voice and density of recent entries in the same file
- Present the draft(s) to the user for review. Show each entry clearly with its target file and category.
Phase 5 — Validate and Write
- Anti-slop validation pass — load
references/writing-rules.md, then check the draft literally (not from memory):- First: search the draft text for em dash (—) and en dash (–) characters. Remove every instance. This is the most common violation and must be checked first as a literal character search, not a mental scan.
- Then re-read each sentence against: banned vocabulary, banned sentence patterns, banned formats, colon/semicolon overuse, sentence rhythm, tone
- If any violations found, rewrite the affected sentences and re-check the rewritten sentences
- On user approval, use
Editto insert the entry under the correct heading in the correct file - Place as the last entry in the target category section
- If both RELEASE_INFO and UPGRADE need entries, write both
- After writing, show the diff so the user can verify placement
Do not commit. The user decides when to commit.
Boundaries
- Never touch
changelog/_unreleased/— warn the user if files exist there (old format rejected by CI) - Never create new version headings — write into existing sections only
- Never auto-commit or create PRs
- Only operates in repositories that contain
RELEASE_INFO-6.*.mdfiles
Sponsors
Details
- Marketplace
- shopwareLabs/ai-coding-tools
- Source
- plugins/contributor-writing
- Category
- Community