sync-decisions

/sync-decisions — Mirror Decisions to External Docs

Read approved decisions from <knowledge_folder>/decisions/ and write them out to a connected ~~docs MCP destination (a Notion page, Confluence space, Google Doc, etc.). The only v1.0.0 skill that writes externally; embeds Rule 22 advisory preamble per ADR-016.

Step 0: Resolve config

The default knowledge folder is ~/Projects/knowledge/ (expand ~ to your home directory's absolute path). Read <knowledge_folder>/aria-config.md and extract knowledge_folder (the absolute path).

If aria-config.md doesn't exist, stop with: "aria-cowork is not configured. Run /aria-setup to get started."

Verify <knowledge_folder>/decisions/ exists. If not, stop: "No decisions/ folder found. Nothing to sync."

Lazily create <knowledge_folder>/logs/sync-decisions.md if it doesn't exist (used by Step 7 for sync history).

For all subsequent file operations in this skill, use the absolute path from knowledge_folder directly. Cowork resolves absolute paths via the persistent grant from claude_desktop_config.json per ADR-008. aria-knowledge in Code uses the same absolute path to reach the same files.

Runtime Gate (per ADR-094)

Canonical resolution: This is the Claude Cowork variant — namespaced-only. When both plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare /sync-decisions resolves to aria-knowledge's variant — Code is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. To reach this skill, use the namespaced form: /aria-cowork:sync-decisions. Do NOT match bare /sync-decisions — that belongs to aria-knowledge.

Before Step 0: Check whether the Bash tool is available in this session. If Bash IS available (you are running in Claude Code or another runtime with shell access), surface the following notification and wait for explicit user confirmation:

⚠️ Runtime mismatch — you invoked aria-cowork's /sync-decisions from a runtime with shell access.

This skill is Cowork-native because it depends on ~~docs WRITE MCPs (Notion, Confluence, Google Docs) typically only connected in Cowork. If you're in Code and DO have these MCPs configured there, fine to proceed; otherwise the canonical aria-knowledge variant at /sync-decisions will at least surface the same gate.

Use /sync-decisions instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke sync-decisions (the bare-slash canonical, which routes to aria-knowledge when both ports are loaded) with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the aria-knowledge variant takes over and runs to completion. This is the default-yes path — auto-redirect is the helpful action.
• n / no — Proceed with this (aria-cowork) variant anyway despite the runtime mismatch. The user has explicitly opted in.
• No response / any other reply — Treat as "do not proceed" and exit cleanly without running either variant.

This gate applies even when mode = auto per ADR-094 §Part 3. Auto mode's "implicit-yes on all gates" rule is suspended for the runtime-mismatch check — auto trusts that the user invoked the correct variant, and this gate enforces that precondition. All other auto-mode gates remain bypassed. The friction cost is now low: on y, the auto-redirect runs the correct variant with the original args.

If Bash is NOT available (normal Cowork runtime), proceed to Step 0.

Step 1: Probe Connected MCPs

Check Claude's available tool list for ~~docs MCPs that support WRITE operations:

• ~~docs (notion, atlassian, box, egnyte, google docs): if connected, check the MCP's exposed tools — ~~docs MCPs that only expose read_page / search_pages are READ-ONLY for this skill's purpose. Need a write surface (create_page, update_page, append_block_children, or equivalent).

If NO ~~docs MCP with write capability is connected, output the standard fallback notice and stop:

No required MCPs connected for /sync-decisions. This skill writes externally — needs a ~~docs MCP with write capability (page creation or block append). Connect Notion, Atlassian (Confluence), Box, Egnyte, or Google Docs via Cowork Settings → Connectors (or Claude Code's .mcp.json for the Code surface). See [CONNECTORS.md](../../CONNECTORS.md). Skipping this run.

Per ADR-015.

Step 2: Enumerate Decisions to Sync

Determine which decisions are candidates based on args:

| Arg | Candidates | |---|---| | (none) | All decisions whose synced_to_~~docs: frontmatter field is absent OR older than file's last-modified time | | <decision-slug> | Just the named decision (e.g., /sync-decisions 069-karpathy-4-line-foundation) | | --all | Every decision in decisions/, regardless of prior sync state | | --since YYYY-MM-DD | Decisions modified or created on/after that date |

Read each candidate decision file from <knowledge_folder>/decisions/. Cache them in working memory.

If zero candidates: report "No decisions need syncing" and stop.

Step 3: Resolve Sync Target

Determine the destination on the ~~docs MCP side. Args + heuristics:

| Source of target | Used when | |---|---| | --target <space-or-page-url> from args | User specified | | sync_target: frontmatter field on the decision | Decision specifies own target | | default_sync_target from aria-config.md (if set) | User has a global default | | Ask user interactively | None of above resolved |

If target resolution requires asking the user, present:

Which destination?

- (a) Existing page URL: paste the ~~docs page URL where decisions should be appended
- (b) New top-level page: I'll create `aria-cowork-decisions` (or a name you provide) in the workspace root
- (c) Cancel this sync run

Decision-specific syncs (where decisions/<slug>.md has its own `sync_target:` field) override this; this prompt only fires for decisions without a per-file target.

If no target resolvable + no interactive answer, abort with clear message: "No sync target resolvable. Set default_sync_target in aria-config.md or invoke with --target <url>."

Step 4: Rule 22 Advisory Preamble (per ADR-016)

For EACH candidate decision, walk through this checklist:

Before each external write — Rule 22 advisory checklist

This skill writes to an external system. aria-cowork has no hooks (per ADR-004); Rule 22 here is text-only discipline (Layer 1 + Layer 3 per aria-cowork v0.2.5's "Principles transfer, enforcement doesn't" framing).

1. **State the change in one sentence.** "Writing decision <slug> to <target-url-or-page-title>."

2. **Why this destination?** Is this the right audience for this decision content? Could it leak into a view the user didn't intend (public workspace, wrong project, wrong channel)?

3. **Reversibility check.** Can the user edit/delete the write from <vendor> after it lands? (For Notion / Confluence / Google Docs: YES, user can edit at destination. For Box / Egnyte: depends on workspace permissions. Note any constraint explicitly.)

4. **Surface for explicit go.** Present the full proposed write content + destination. Wait for explicit user `yes` / `go` before calling the write tool.

Concretely: for each decision, surface this block to the user:

Decision: <slug>
Source file: decisions/<slug>.md
Destination: <target-url-or-page-title> on <vendor>
Operation: <create new page | append to existing page | update existing page>
Reversibility: <user can edit at destination: yes/no/constrained>

--- Proposed write content (preview) ---

<the full decision content as it will appear externally — markdown if Not