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"). Use Grep/Glob.
• Web research. Use web-research.
• Comparative evaluation of two implementations or source credibility adjudication. Use llm-judge.
• Rewriting or editing the scanned documents. Use humanize-beagle or the file tools.
• 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 subagents — spawn 1-3 parallel subagents over non-overlapping slices of the resolved paths. Each 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, 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 tooling (Read, Glob, Grep) is assumed present in the Claude Code 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 is absent.
• Resolved paths — every path that will actually be scanned, with a note next to any entry that came from auto-discovery vs. caller-specified.
• Slices — how the resolved paths are partitioned across 1-3 subagents. Slices are non-overlapping.
• Per-slice briefs — one paragraph per slice summarizing