--- name: confluence-sync-decision-log description: "📖 CONFLUENCE: Sync decision log — scan Fireflies, Slack & Jira for new decisions, then propose precise additions and status updates to a project's Confluence Decision Log. Use whenever asked to update, review, or audit a project's decision log. Triggers include: \"update the decision log\", \"check what's new for the decision log\", \"scan for decisions since last update\", \"what decisions have been made recently\", \"sync the decision log\", \"audit the decision log\", \"zaktualizuj decision log\", or any time new decisions or major updates on a project need to be captured in Confluence. Proposes all changes with full rationale for review — nothing is written to Confluence without explicit approval." --- # Confluence Decision Log Sync Skill ## Purpose Automate the discovery of new decisions and decision updates for any project, then propose precise, well-formatted changes to a Confluence Decision Log — before writing anything. All changes require explicit approval before being committed. --- ## Step 0: Resolve project context If not already clear from conversation, ask: 1. **Project name** — which project's decision log to update 2. **Confluence Decision Log page** — URL or page ID (or search for it) 3. **Scan window** — default: since the page was last modified **Page discovery** (if not provided): ``` CQL: title ~ "Decision Log" AND space = "" ORDER BY lastModified DESC ``` ### If no Decision Log page is found If the CQL search returns no results **and** the user hasn't provided a URL or page ID, do not proceed to Step 1. Instead: 1. **Inform the user clearly:** > "I couldn't find a Decision Log page in the `` space on Confluence. Would you like me to create one, or would you prefer to create it yourself and share the link?" 2. **If the user wants Claude to create it**, propose the page before creating anything: - Show the full table structure (columns: ID, Decision Title, Status, Approval Required, Decision Date, Decision Maker, Rationale) - Confirm the target Confluence space and parent page (ask if unknown) - Ask: *"Shall I create this page in `` under ``?"* - Only after explicit confirmation: call `createConfluencePage` with the standard table as the body (ADF format), then proceed to Step 1 using the newly created page. 3. **If the user prefers to create it manually**, provide the standard table structure (see **Decision Log Table Structure** section below) as a reference, and ask them to share the URL or page ID once it's ready. **Never skip this gate and proceed to Step 1 with no page.** --- ## Key Constants (shared) - **Confluence Cloud ID:** use the Atlassian Cloud ID from your project context (e.g. `yourorg.atlassian.net`). If not set, ask the user before querying Confluence. --- ## What Qualifies as a Decision Log Entry A decision or update **belongs in the log** if it: - Has meaningful impact on scope, cost, timeline, or architecture - Requires client approval or involves a vendor/partner commitment - Is irreversible or hard to change once made - Creates a dependency on another team (client dev, logistics, legal, or a partner) - Changes the status of an existing pending item (approved / declined / new info) **Does NOT belong:** day-to-day UX micro-decisions, implementation details, internal process tweaks, or clarifications that don't affect the above criteria. --- ## Execution Workflow ### Step 1: Read the current Decision Log Fetch the Confluence page in **ADF format** (`contentFormat: "adf"`): ``` getConfluencePage(pageId, contentFormat: "adf") ``` From the response, capture: - The **full raw ADF body** — treat this as sacred; it will be used as the base for all writes - The **version number** — needed for the update call - The `version.createdAt` timestamp — this is the **cutoff date** for scanning - The existing decision table: parse out each row's ID, title, and status for reference **The ADF body must never be reconstructed or paraphrased.** It is copied verbatim into every write call and only the specific targeted nodes are modified. ### Step 2: Determine the scan window Use `version.createdAt` from the Confluence page as the `fromDate` for Fireflies and the `oldest` timestamp for Slack. Convert to: - ISO 8601 for Fireflies: e.g. `"2026-05-06"` - Unix timestamp for Slack `oldest` param: e.g. `1746576000` ### Step 3: Scan Fireflies Search for meetings related to the project: ``` fireflies_get_transcripts(keyword="", fromDate=, limit=10, scope="all") ``` Try alternative keywords if the primary returns no results (e.g. project alias, client name). For each meeting found, read the summary (`fireflies_get_summary`). Focus on: - Decisions made or confirmed - Status changes on known open items - New blockers or risks that should be tracked - Any mentions of vendors, partners, payments, integrations, legal ### Step 4: Scan Slack channels Scan project-related channels with `oldest: `, `limit: 50`. If channel IDs aren't known, search: ``` slack_search_channels(query="") ``` Look for channels like `#proj-`, `#-operational`, `#-mgmt`, etc. Also run a targeted search for high-signal content: ``` query: " decision OR agreed OR confirmed OR approved OR declined after:" ``` For any message matching these signals, read the full thread — decisions are frequently confirmed or reversed in replies, not in the original message: ``` slack_read_thread(channel_id: "", thread_ts: "") ``` ### Step 5: Synthesise findings Cross-reference everything found against the existing Decision Log. For each finding, classify: - **NEW DECISION** — a net-new item not yet in the log - **STATUS UPDATE** — an existing Pending item has been approved, declined, or has important new info - **UPDATE ADDITION** — an existing entry needs a new "Update (DD.MM.YY):" line appended to its rationale cell For **status updates** and **update additions**, always reference the specific Decision ID from the table's sequential integer ID column (e.g. 11). ### Step 6: Present proposed changes Before touching Confluence, present all findings as a clear summary: ``` ## Proposed Decision Log Changes ### NEW ENTRIES **[NEW] Decision: ** Status: Pending / Approved / Declined Decision Maker: <name or TBC> Date: <DD.MM.YY or TBC> Rationale: <1-2 sentence summary> Source: <Fireflies meeting title | Slack #channel | date> ### UPDATES TO EXISTING ENTRIES **D-<ID> — <Decision Title>** (currently: <status>) Proposed change: [Status change to X] / [Add update text] Update text: "Update <DD.MM.YY>: <text>" Source: <source> ### NO ACTION NEEDED - <Decision title>: no new developments found ``` Always include a **"Sources scanned"** section at the end listing all Fireflies meetings and Slack channels checked, with date range. Ask: *"Shall I apply all of these, or would you like to modify any before I write to Confluence?"* ### Step 7: Write to Confluence (only after explicit approval) **The golden rule: the ADF body fetched in Step 1 is the ground truth. Every write operation starts from that exact body and modifies only the approved nodes. Nothing else changes.** #### 7a. Locate target nodes in the ADF The ADF body is a nested JSON structure. The decision table is a `table` node inside `content`. Each row is a `tableRow` with `tableCell` children. Columns map to: ID, Title, Status, Approval Required, Decision Date, Decision Maker, Rationale. To apply an **update addition** to an existing row: 1. Find the `tableRow` whose first cell contains the matching decision ID (e.g. `"3"`) 2. Locate the **last** `tableCell` in that row — this is the Rationale cell 3. Find the last `paragraph` node inside that cell 4. **Append** a new `paragraph` node after it with the update text formatted as bold prefix + plain text: ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Update DD.MM.YY: ", "marks": [{ "type": "strong" }] }, { "type": "text", "text": "<update text here>" } ] } ``` To apply a **status change** to an existing row: 1. Find the `tableRow` for the matching decision ID 2. Locate the third `tableCell` (Status column) 3. Replace only the `status` inline node within it. Match the casing and color of existing status nodes in the document — do not invent new color codes. To **add a new row**: 1. Locate the closing of the `table` node 2. Append a complete new `tableRow` before it, matching the column structure of existing rows exactly. Use plain `text` nodes for all cells. For the Status cell, use the same `status` inline node structure as existing rows. #### 7b. Construct the write payload Take the **full ADF body from Step 1 verbatim**. Apply only the surgical node modifications described in 7a. Do not reformat, reorder, or touch any other node. Call `updateConfluencePage` with: - `contentFormat: "adf"` - `body`: the modified ADF JSON (full document, with only targeted nodes changed) - `versionMessage`: `"Decision Log update <today's date> — automated scan"` **Never submit the body in markdown format** — doing so will strip Confluence-native elements (status lozenges, smart links, inline images) from untouched rows. #### 7c. Verify After writing, fetch the page again and confirm: - The targeted rows contain the new update text / status - The untouched rows are byte-for-byte identical to what was fetched in Step 1 - The version number incremented by 1 If any untouched row differs, report the discrepancy to the user before proceeding. --- ## Decision Log Table Structure (standard) | Column | Notes | |---|---| | ID | Sequential integer | | Decision Title | Short, descriptive title | | Status | `approved` / `Pending` / `declined` — match casing and color of existing entries | | Approval Required | Leave blank for new entries | | Decision Date | `DD.MM.YY` format or blank if pending | | Decision Maker | Name or blank if pending | | Rationale (Summary) / Link | Full narrative + `**Update DD.MM.YY:** text` lines + links | --- ## Writing Quality Standards ### Decision Titles A good title answers: *"What was decided?"* — not *"What was discussed?"* - Aim for 5–10 words. Specific, outcome-oriented. - Start with the subject of the decision, not the domain. | ❌ Bad | ✅ Good | |---|---| | Authentication | JWT chosen over session tokens for auth | | Payment provider discussion | Stripe selected as primary payment provider | | Timeline | MVP delivery moved to June 15 | | Partner API | Partner API integration deferred to Phase 2 | ### Rationale Text Every entry should answer three questions in 2–4 sentences: 1. **What** was decided (restate briefly — the title is short, the rationale can expand) 2. **Why** — the reasoning, constraint, or evidence that drove the decision 3. **What was NOT chosen** — the alternative considered, if any (this is what prevents re-litigation) - ✅ Good: "The team selected Stripe over Adyen after comparing integration complexity and fee structures. Stripe's pre-built components reduce frontend work by ~2 weeks and are already familiar to the dev team. Adyen was considered but requires a longer onboarding process that doesn't fit the current timeline." - ❌ Bad: "Stripe was chosen for payment processing." **Rationale length:** 2–4 sentences for a new entry. Update lines should be 1–2 sentences max. ### Update Lines When appending an update to an existing entry: - Format: `**Update DD.MM.YY:** [what changed, who confirmed it]` - Include what prompted the update (new info, client approval, change of scope) - **Never rewrite the existing rationale text** — only append new paragraph nodes after it - ✅ Good: `**Update 12.05.26:** Client approved Stripe integration in call on 11.05. Contract signing expected by end of week.` - ❌ Bad: `**Update 12.05.26:** Update to the previous decision.` --- ## Decision Criteria Quick Reference When evaluating whether something is a Decision Log item, ask: 1. Does it change what we're building, how we're building it, or who is responsible? 2. Does the client need to sign off, or have they already? 3. Could it block another team if not resolved? 4. Is it a vendor, partner, or legal commitment? 5. Would not having it documented cause confusion or re-work later? If 2+ of these are true → it belongs in the log.