extract-doc

/extract-doc — Extract Insights from a Doc to Intake Backlog

Pull knowledge-worthy items from a single connected ~~docs source (Notion page, Google Doc, Confluence page, Box doc, Egnyte file) into intake/insights-backlog.md. Unlike /intake doc (which captures the doc itself as one structured artifact for later reaction), /extract-doc decomposes the doc into N intake entries — one per insight, decision, or question worth surfacing at audit.

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 /extract-doc 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:extract-doc. Do NOT match bare /extract-doc — 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 /extract-doc from a runtime with shell access.

This skill is Cowork-native because it depends on ~~docs MCPs (Notion, Google Docs, Confluence) 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 /extract-doc will at least surface the same gate.

Use /extract-doc instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke extract-doc (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 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>/intake/insights-backlog.md exists. If not, stop with: "Insights backlog not found. Run /aria-setup to repair the knowledge folder structure."

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.

Step 1: Probe Connected MCPs

Check Claude's available tool list for ~~docs MCPs:

• ~~docs (notion, atlassian, box, egnyte, google docs): if connected, available for doc fetch.

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

No required MCPs connected for /extract-doc. Connect one of: Notion, Atlassian (Confluence), Box, Egnyte, or Google Docs (when available) 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: Parse Input

The user provides one of:

• A Notion page URL — https://www.notion.so/<workspace>/<title>-<id> or notion.so/<id>
• A Confluence page URL — https://<org>.atlassian.net/wiki/spaces/<space>/pages/<id>/<title>
• A Google Docs URL — https://docs.google.com/document/d/<doc-id>/... (if google docs MCP wired; placeholder URL in v1.0.0 .mcp.json)
• A Box file URL — https://app.box.com/file/<file-id>
• An Egnyte file URL — https://<org>.egnyte.com/...
• A bare doc/page ID — opaque string the connected MCP can resolve

Optionally followed by tags (e.g., engineering postmortem, cs onboarding).

Source-type detection:

| Input shape | Routes to | |---|---| | Contains notion.so or www.notion.so | ~~docs (notion) | | Contains atlassian.net/wiki | ~~docs (atlassian) | | Contains docs.google.com/document | ~~docs (google docs) | | Contains app.box.com/file | ~~docs (box) | | Contains egnyte.com | ~~docs (egnyte) | | Ambiguous | Ask user which ~~docs MCP holds the doc |

If the detected-source's MCP is not connected, output a specific fallback notice:

This doc looks like a [Notion / Confluence / etc.] page but the [vendor] MCP is not connected. Connect [vendor] via Cowork Settings → Connectors and retry, or paste the doc URL of a different format. Skipping this run.

Step 3: Fetch Doc Content

Call the connected MCP's page/doc-fetch tool with the resolved ID:

• Notion: notion.fetch or pages.retrieve + blocks.children.list for body.
• Atlassian: confluence.pages.get (or equivalent) — request body in storage/representation that preserves headings + lists.
• Google Docs: documents.get — extract text content + structure.
• Box / Egnyte: file content fetch + text extraction (skip binary attachments).

Gather:

• Doc title
• Author (last editor) + last-edited timestamp (if exposed)
• Workspace / space / parent context (e.g., "Notion → Engineering → 2026 Q2")
• Body content as structured text (preserve headings, lists, links — flatten complex blocks)

Limit: if the doc is >20KB of extracted text, fetch the first 20KB + note the truncation in the entry metadata. The user can re-invoke with a section anchor (#heading) for the tail.

Step 4: Extract Insights

Read the doc body and identify knowledge-worthy items — discrete propositions worth surfacing at next /audit-knowledge. Each candidate should be a single self-contained claim, decision, lesson, or question.

For each candidate, classify into one of the standard intake categories:

| Category | Use when | |---|---| | insight | Observation about how something works, or a learning | | decision | A choice that was made + rationale | | extraction | A pattern, recipe, or how-to worth promoting later | | idea | A "we should consider X" proposition | | reference | A useful URL or external resource named in the doc |

Quality bar: skip items that are project-status updates, ephemeral context, or items already obviously in the knowledge folder. Default to fewer-but-stronger — extracting 3 strong items beats 12 weak ones.

Step 5: Stage to Backlog + Report

For each extracted item, append a new entry to <knowledge_folder>/intake/insights-backlog.md (or decisions-backlog.md / extraction-backlog.md per category; ideas go to intake/ideas/<date>-<slug>.md per v2.11.0 per-file convention).

Standard intake entry format (mirrors /extract skill output):

## <one-line claim or title>

- **Source:** [<doc-title>](<doc-url>) ([<vendor>])
- **Date captured:** <YYYY-MM-DD>
- **Project tags:** <from input args + auto-detected from doc work