artifact-analysis

# 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`      | list of strings    | no       | auto-discover | Directories and/or explicit files. When absent, auto-discover (see below).          |
| `output_dir` | absolute path      | no       | derived       | Where `plan.md`, `findings/`, and `report.md` land.                                 |
| `refresh`    | bool               | no       | `false`       | When true, allow overwriting a prior run in the same `output_dir`.                  |

The skill does not parse caller-specific structures. Callers pass an intent string and/or a path list.

### Auto-discovery

When `paths` is absent or empty, scan beagle's conventional knowledge locations:

- `.beagle/concepts/` — concept specs and analysis folders.
- `.planning/` — roadmap, state, and phase artifacts.
- `docs/` — project documentation.
- Top-level files matching `README*`, `BRIEF*`, `OVERVIEW*`, `CONTEXT*`, `CLAUDE.md`, `AGENTS.md`.

Resolved paths (includ