Apply feedback-driven changes to a UX spec and update it in Confluence
68%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./plugins/ux-spec-process/skills/spec-updater/SKILL.mdThis skill writes to Confluence via updateConfluencePage. Confluence writes are a hard-stop gate. Follow this every run, no exceptions:
dry_run defaults to TRUE. The first action is always a preview: show the full BEFORE/AFTER diff per affected section and state exactly what will be written and to which page (page title + ID/URL). No write happens on this pass.dry_run: false only after that explicit yes.[AI DRAFT] until a human has reviewed it. Carry the label through the draft; it is removed only on human sign-off.updateConfluencePage (or any Confluence write) without steps 1–3 satisfied. If in doubt, stop and ask.This mirrors the
defense-ux-contextskill's Output Rules (Confluence) verbatim in intent: confirm → draft → second confirm to publish →[AI DRAFT]. If this skill's behavior ever diverges fromdefense-ux-context,defense-ux-contextwins.
Invoke with claude-sonnet-4-6. Phase 8 is targeted diff work — not full-pipeline reasoning. Escalate to Opus only if feedback requires re-scoping or threat-model re-evaluation.
Takes feedback (review comments, stakeholder notes, Jira tickets, or direct instructions) and applies targeted changes to an existing UX spec in Confluence. This is the Phase 8 (Spec Maintenance) workhorse — the skill you use when the spec already exists and needs to evolve.
This skill handles the full loop: read the current spec from Confluence, understand the requested changes, generate the updated content, and write it back to Confluence with a version message.
The skill reads the existing spec from Confluence using the page ID or URL you provide.
The skill accepts feedback in any format:
For each change, the skill:
This step never runs unconfirmed. The skill first produces a dry-run preview (default dry_run: true), states exactly what will change and on which page, and waits for the user's explicit "yes". Only then does it update the page as a draft (content labeled [AI DRAFT]) with a version message summarizing what changed. Publishing is a separate action requiring a second explicit confirmation. See the Write-Safety Gate at the top of this skill.
{
"confluence_page_id": "string (the page ID of the spec to update)",
"confluence_cloud_id": "string (your Atlassian cloud ID)",
"feedback": "string (the changes to apply — any format)",
"feedback_source": "string (optional — where the feedback came from: 'review', 'jira', 'slack', 'inline_comments', 'direct')",
"dry_run": "boolean (optional, default TRUE — when true (the safe default), show the BEFORE/AFTER changes and the target page WITHOUT writing to Confluence. Only set to false AFTER the user gives explicit confirmation on the dry-run preview)",
"update_revision_history": "boolean (optional, default true — add entry to the Revision History section, located by heading)"
}{
"sections_modified": ["string (section numbers/names that were changed)"],
"changes_summary": "string (human-readable summary of all changes made)",
"revision_entry": "string (the entry added to the Revision History section)",
"confluence_url": "string (link to the updated page)",
"warnings": ["string (any issues encountered — ambiguous feedback, sections not found, etc.)"]
}You are a senior UX spec editor for Mattermost, a security-focused collaboration platform used by DoD and defense contractors.
Your task is to apply targeted changes to an existing UX spec based on the provided feedback. You must:
1. READ the current spec content carefully before making any changes.
2. IDENTIFY which sections are affected by each piece of feedback.
3. APPLY changes precisely — modify only what needs to change, preserve everything else.
4. MAINTAIN the prescriptive style of the spec:
- Use "must", "will", "does not" — never "should", "could", "may"
- Every setting must have: label text, help text, default value, behavior
- Every error state must have: exact trigger condition and exact error message text
- Mobile behavior must be explicitly stated for every flow
5. FLAG anything ambiguous with [TBD: reason] — never guess at UI specifics.
6. UPDATE the Revision History with a dated entry describing the changes.
7. PRESERVE deprecated explorations — if removing a previously specified approach, move it
to the Deprecated Explorations section with strikethrough and reason, don't delete it.
Reference sections BY NAME, not by fixed number — the template's optional sections shift
the numbering between specs, so a hardcoded "Section 13" is unreliable. Locate sections by
their heading text (e.g. "Roles & Permissions", "Edge Cases", "Accessibility", "Revision
History", "Deprecated Explorations").
Rules:
- Never delete content without moving it to the Deprecated Explorations section first.
- If feedback contradicts an existing section, flag the contradiction and ask for resolution
rather than silently overwriting.
- If feedback requires changes to the Roles & Permissions matrix, the Edge Cases table, or
the Compliance appendix, update those sections too — don't just update the prose.
- If the change affects mobile behavior, explicitly update mobile documentation.
- If the change affects accessibility, update the Accessibility section.
- WRITE-SAFETY: never call updateConfluencePage without satisfying the Write-Safety Gate
(dry-run preview → explicit user confirmation → draft only → second confirm to publish →
[AI DRAFT] label). dry_run is TRUE until the user confirms the preview.
Output format:
For each section you modify, show:
[SECTION: Section Name] ← identify by heading text, not a fixed number
[BEFORE]: (relevant excerpt of current content)
[AFTER]: (updated content)
[REASON]: (which feedback item drove this change)
This is the DRY-RUN PREVIEW. Also state plainly: the target page (title + ID/URL) and that
nothing has been written yet. Then STOP and wait for the user's explicit "yes" before any
write. Only after that confirmation do you provide the full updated page content for the
Confluence draft write-back (and request a second confirmation before any publish).Input:
feedback: "Change the error message when a user is denied channel access from
'You do not have permission to view this channel' to 'Channel access restricted.
Contact your administrator to request access.' Also add a 'Request Access' button
that opens a pre-filled message to the channel admin."
confluence_page_id: "123456789"What happens:
[AI DRAFT] draftInput:
feedback: |
MUST-FIX:
1. Missing loading state for attribute sync operation (Section 3.1)
2. Error message for LDAP timeout doesn't specify retry behavior (Section 4.2)
SHOULD-FIX:
3. Add keyboard shortcut for toggling attribute panel (Section 5)
OUT OF SCOPE:
4. Batch attribute editing for multiple channels — defer to Phase 2
confluence_page_id: "123456789"
feedback_source: "review"What happens:
Input:
feedback: "Remove the auto-translation toggle from the channel header and move it to channel settings instead"
confluence_page_id: "987654321"
# dry_run omitted → defaults to TRUE; no write happens on this passWhat happens:
dry_run: false to write the [AI DRAFT] draft; publishing then needs a second explicit confirmationHere is the concrete sequence of tool calls this skill makes:
Step 1: Read the spec
→ getConfluencePage(cloudId, pageId, contentFormat: "markdown")
Step 2: Parse and plan changes
→ (Internal — analyze feedback against spec content)
→ If feedback_source is "inline_comments":
→ getConfluencePageInlineComments(cloudId, pageId)
Step 3: Generate updates + DRY-RUN PREVIEW (default; no write)
→ (Internal — produce BEFORE/AFTER for each section, located by heading text)
→ Present preview: name the target page (title + ID/URL), show the diff, label content [AI DRAFT]
→ STOP. Wait for the user's explicit "yes" before any write.
Step 4: Write back as DRAFT — ONLY after explicit confirmation (dry_run: false)
→ updateConfluencePage(cloudId, pageId, body: updatedContent, // draft, content carries [AI DRAFT]
versionMessage: "[AI DRAFT] Spec update: [summary of changes]")
→ Do NOT publish in this step.
Step 5: Publish — ONLY on a SECOND explicit confirmation
→ Surface publishing as its own ask; never auto-publish.
Step 6: Resolve inline comments (if feedback came from comments)
→ (Designer manually resolves comments after reviewing the update)No
updateConfluencePagecall may execute until Step 3's preview has been confirmed by the user. Publishing requires the additional confirmation in Step 5.
This is the conversion contract for getting a finished spec out of markdown and into Confluence. The publish allowlist is exactly two things: the canonical Phase-7 spec (07-spec.md) and Phase-8 maintenance updates to it. Nothing else publishes. Pre-spec artifacts (Phases 1–6) and the internal validation siblings (07-spec-edge-cases.md, 07-spec-traceability.md) stay local — only 07-spec.md publishes.
Confluence stores pages as XHTML "storage format," not markdown. Two supported paths, in order of preference:
updateConfluencePage / createConfluencePage accept a markdown body representation — pass the markdown directly and let Confluence convert to storage format. This is the path the Execution Flow above uses (getConfluencePage(..., contentFormat: "markdown") round-trips cleanly). Use it whenever the spec's markdown is within the subset Confluence converts losslessly.| Markdown construct | Confluence storage-format target | Notes |
|---|---|---|
Headings #–###### | <h1>–<h6> | The spec's skim-layer H1/H2/H3 carry over; keep the [AI DRAFT] label in the title and lead. |
Paragraphs, bold, italic, inline code | <p>, <strong>, <em>, <code> | Straightforward. |
| Tables (traceability matrix, roles/permissions, decisions) | <table><tbody><tr><th>/<td> | Header row → <th>. Confluence renders these as native sortable tables. Keep self-resolving glosses inline (FR-10 (admins bulk-assign…)), never bare codes. |
Fenced code blocks ``` | <ac:structured-macro ac:name="code"> with <ac:plain-text-body><![CDATA[ … ]]> | Set the language parameter when known. CDATA-wrap to preserve <, >, &. |
Callouts / admonitions (BLUF, [VERIFY WITH PM], blockers) | <ac:structured-macro ac:name="info"> / name="note" / name="warning" | BLUF → info; [VERIFY WITH PM] and open questions → note; P1 blockers → warning. Pin these near the top so the skim layer survives. |
| Status badges (P1/P2/P3, draft) | <ac:structured-macro ac:name="status"> with a colour + title param | Always pair colour with the text title (P1/P2/P3) — never colour alone (carries the WCAG color+text rule into Confluence). |
| Links (Figma, sibling specs, Jira) | <a href="…"> or <ac:link> for intra-Confluence | Figma/external → plain <a>. Cross-spec → <ac:link><ri:page ri:content-title="…"/></ac:link>. |
Repository-relative links (dedup citations like ../02-research.md#anchor, 05-flows/x.md) | <ac:link> to the published page, OR delinked plain text | These point at local, unpublished pre-spec artifacts — a raw relative href is a dead link in Confluence. Rewrite each: if the target maps to a published Confluence page, emit <ac:link><ri:page ri:content-title="…"/> (optionally #anchor); otherwise strip the link and keep the quoted gist as plain text. Never emit a repository-relative <a href>. |
| Images / diagram exports | <ac:image><ri:attachment ri:filename="…"/></ac:image> | Any diagram or image that the published 07-spec.md references is attached as an image export (PNG/SVG) — Confluence renders the static attachment. |
Pre-export preflight: scan the draft for repository-relative links (../NN-*.md, NN-*/...md, #anchor into a sibling file) and resolve every one per the Repository-relative links row before the dry-run preview — rewrite to an <ac:link> where a published target exists, otherwise delink to plain text. The preview must show the already-converted content, so the user approves exactly what gets written. A draft still carrying an unresolved repository-relative link is not export-ready.
Round-trip rule: read the existing page with contentFormat: "markdown", edit in markdown, write back via the markdown representation when path (1) is lossless; switch to storage-format XHTML only for the blocks in the table that need it. Locate sections by heading text (never a fixed number), per the system prompt.
The export changes only the format conversion, never the write safety. Every Milestone-A gate from the Write-Safety Gate section above still applies verbatim, in order:
dry_run: true default) — show BEFORE/AFTER per section and name the target page (title + ID/URL); for a NEW publish, show the full converted page and the target space/parent. No write on this pass.createConfluencePage/updateConfluencePage writes a draft; never publish in the same step.[AI DRAFT] label — carried through title, lead, and version message until human sign-off removes it.All format conversion — including the repository-relative-link rewrite/delink above — is performed while generating the content, before the dry-run preview. The preview therefore shows the fully converted result, and the draft write persists that exact same content, so the user approves precisely what is written to Confluence.
| Scenario | Workflow |
|---|---|
| Got raw feedback from a review session | Run feedback-synthesizer first → pipe its output as the feedback input to spec-updater |
| Need to check if update introduced new edge cases | Run edge-case-hunter on the updated spec after applying changes |
| Need to verify update didn't break PRD traceability | Run traceability-checker on the updated spec after applying changes |
| Feedback includes security concerns | Run threat-modeler on the affected sections before applying changes |
| Multiple rounds of feedback on the same spec | Run spec-updater sequentially — each run reads the latest version from Confluence |
dry_run defaults to TRUE; no Confluence write executes until the user explicitly confirms the dry-run preview[AI DRAFT] until human-reviewedmattermost/mattermost-ai-marketplace
c58fe0e
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.