artifact-analysis

What this skill does

# 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 (including any auto-discovery) are listed verbatim in `plan.md` so the caller can see exactly which files were included.

### Intent modes

- **`intent` present** — extraction is targeted to what is relevant to the intent. Off-topic material goes into `Raw Detail Worth Preserving` only when it is a specific quote or metric worth keeping.
- **`intent` absent** — generic-salient-extraction mode. Subagents extract anything structurally important (insights, decisions, technical constraints, user/market context) without an interpretive filter.

## Output location

If the caller passes `output_dir`, use it verbatim. Otherwise derive the default:

```
.beagle/analysis/<slug>/
```

**Slug derivation** (stable so re-running the same input on the same day lands on the same folder):

1. If `intent` is present, slug from the intent string: lowercase, strip punctuation, collapse whitespace to single hyphens, truncate to 60 characters on a word boundary (cut at the last hyphen before 60; if no hyphen exists before position 60, hard-cut at 60).
2. If `intent` is absent, slug from the first scanned path's basename using the same rules.
3. Prepend `YYYY-MM-DD-`.

**Re-run protection.** Before writing anything, check whether `output_dir` already contains `plan.md` or `report.md`. If it does and `refresh` is not `true`, refuse with a message naming the existing folder. When `refresh: true`, archive the prior contents into `<output_dir>/.archive-<timestamp>/` before starting fresh. See `references/failure-modes.md`.

Callers embedding artifact-analysis in a concept-folder convention (e.g. `prfaq-beagle`) pass `output_dir` explicitly so the analysis sits next to its consumer: `.beagle/concepts/<concept-slug>/analysis/`.

## The scan plan (`plan.md`)

The plan is written before any subagent runs. It is the audit trail, not a review gate — the skill does not pause for user confirmation.

`plan.md` contains:

- **Intent** — the input string, verbatim, or `"generic salient extraction"` when intent