/artifact-analysis

name: artifact-analysis
description: "Use when the user wants a cited, structured read of local documents and project knowledge. Triggers on: \"analyze these docs\", \"scan my project for context\", \"read the docs folder\", \"summarize what's in .beagle/concepts/\", \"extract context from docs/\", \"what's in this folder\", \"go read everything in X and tell me what's there\". Also invoked programmatically by other beagle skills (prfaq-beagle Ignition, brainstorm-beagle reference points, strategy-interview context grounding) via the companion contract. Does NOT trigger on codebase lookups (\"find this function\", \"search the repo\"), web research (use web-research), LLM-as-judge evaluation (use llm-judge), or document editing (use humanize-beagle). Produces a written scan plan, parallel-subagent findings, and a cited synthesis report on disk — never inline prose, never unsourced claims."

Artifact Analysis

Turn a set of local paths (or a beagle project's conventional knowledge locations) into a cited, structured extraction of insights, context, decisions, and raw detail.

The deliverable is always on disk: a written scan plan the caller can audit, one findings file per slice, and a synthesized report with path-anchored citations. Nothing returns as inline prose, and no claim ships without a source path + verbatim excerpt behind it.

When to use

• A user asks for a local-document read — "analyze the docs folder", "scan the project for context", "extract what's in .beagle/concepts/".
• Another beagle skill invokes this one programmatically as a grounding companion (see `references/companion-contract.md`).
• The caller wants auditable output: a plan written before extraction, findings files per slice, and a citation-backed synthesis report.

When NOT to use

• Codebase lookups ("where is this function defined", "grep for this symbol"). Search the codebase instead.
• Web research. Use [web-research](../web-research/SKILL.md).
• Comparative evaluation of two implementations or source credibility adjudication. Use [llm-judge](../llm-judge/SKILL.md).
• Rewriting or editing the scanned documents. Use humanize-beagle ([../../../beagle-docs/skills/humanize-beagle/SKILL.md](../../../beagle-docs/skills/humanize-beagle/SKILL.md)) or edit the files directly.
• PDF / image OCR / format conversion. First version reads plain text and markdown only.
• Paywalled or authentication-gated remote sources. This is a local-filesystem primitive.
• Coaching, challenge, or reshaping of the caller's question. That belongs to the caller.

Workflow

Four steps, in order. No step is skippable.

Hard gates

Advance to the next step only when the **pass condition** is true—confirm using files under `output_dir` (and tool output), not memory.

| After | Pass condition | | --- | --- | | `plan.md` written | `plan.md` exists and includes intent, resolved paths, slices, per-slice briefs, skip patterns, budgets applied, and synthesis approach (same fields as **The scan plan (`plan.md`)**). | | Subagent dispatch | Either the **empty corpus** path was taken (no subagents; `plan.md` documents zero readable documents) **or** every slice listed in `plan.md` has `findings/<slice-slug>.md` on disk. | | `report.md` written | `report.md` exists; headings match `references/report-template.md` (seven sections plus `## Sources`). | | Before return to caller | Every row of `references/failure-modes.md` → **Verification checklist (orchestrator runs at end)** is checked off, *or* any failed check is recorded under `## Gaps & Limitations` in `report.md` as that failure-modes file prescribes. |

1. **Write `plan.md`** — resolved paths (with any auto-discovery applied), intent summary (when provided), per-slice briefs, skip patterns, and how findings will be synthesized. 2. **Dispatch slices** — **if the agent supports subagents**, spawn 1-3 parallel subagents over non-overlapping slices of the resolved paths; **otherwise** process the same slices sequentially yourself — identical output. Each slice writes `findings/<slice-slug>.md` under `output_dir`. 3. **Synthesize `report.md`** — fold findings into the seven fixed sections with path-anchored citations. 4. **Verify before returning** — satisfy the last **Hard gates** row; execute the numbered checklist in `references/failure-modes.md` (**Verification checklist (orchestrator runs at end)**). Any check that fails becomes an entry in `Gaps & Limitations` per that file—do not return a deliverable with silent checklist failures.

Receive paths + optional intent ──→ Auto-discover if paths empty
                                   ↓
                                 Write plan.md (no user-confirmation pause)
                                   ↓
                                 Dispatch subagents (up to 3 parallel)
                                   ↓
                                 Collect findings/<slice>.md files
                                   ↓
                                 Synthesize report.md
                                   ↓
                                 Return paths to caller

Unlike [web-research](../web-research/SKILL.md), artifact-analysis does **not** pause for a plan review gate. Local scanning is cheap; `plan.md` is written for auditability so a reader weeks later can tell what each subagent was told. Unlike web-research, there is no fail-fast on missing tools — filesystem search (read, glob, grep) is assumed present in the agent's environment.

Inputs

| Field | Type | Required | Default | Purpose | | ------------ | ------------------ | -------- | ------------- | ----------------------------------------------------------------------------------- | | `intent` | string | no | — | What the caller is looking for / why. When absent, the skill extracts anything structurally important. | | `paths` | lis