aria-knowledge

/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 v2.18.0 skill that writes externally; embeds Rule 22 advisory preamble per ADR-016.

Runtime Gate (per ADR-094)

Canonical resolution: This is the Claude Code variant. 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 this skill — aria-knowledge (Code) is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. The Cowork variant is namespaced-only: /aria-cowork:sync-decisions.

Before Step 0: Check that the Bash tool is available in this session. If Bash is NOT available (you are running in Claude Cowork or another non-Code runtime), surface the following notification and wait for explicit user confirmation:

⚠️ Runtime mismatch — you invoked aria-knowledge's /sync-decisions from a non-Code runtime.

This skill requires connected ~~docs WRITE MCPs (Notion, Confluence, Google Docs), which are typically only present in Cowork. The Cowork-native variant has working MCP write access. Use /aria-cowork:sync-decisions.

Use /aria-cowork:sync-decisions instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke aria-cowork:sync-decisions with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the cowork 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-knowledge) 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 available, proceed to Step 0.

Step 0: Resolve Config

Read ~/.claude/aria-knowledge.local.md and extract knowledge_folder. If the file doesn't exist, stop: "aria-knowledge is not configured. Run /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).

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 Claude Code's MCP config (or Cowork Settings → Connectors). 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-knowledge.local.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-knowledge-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-knowledge.local.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-knowledge's PreToolUse hook gates Edit/Write but does NOT catch MCP write tools — Rule 22 here is text-only discipline per ADR-016.

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 Notion/Confluence; plaintext if Google Doc; etc.>

--- End preview ---

Ready to write? (yes / no / edit)

Step 5: Per-Decision Go-Gate

Wait for the user's explicit response:

• yes / go: proceed to Step 6 for THIS decision.
• no / skip: mark this decision as skipped in the sync log; move to the next candidate.
• edit: ask the user what to change in the preview content, regenerate, re-present, ask again.
• yes to all writes (literal): authorize this AND all remaining decisions in the candidate list without per-decision confirmation. This is the ONLY way to batch — explicit user opt-in per ADR-016. The exact phrase "yes to all writes" must appear in the user's reply; partial forms like "yes to all" or "yes all" do NOT trigger the batc