{"id":"7d292c00-d511-411e-99f5-584bf9b9a507","entityType":"agent","slug":"clawhub-anderskev-artifact-analysis","name":"Artifact Analysis","canonicalUrl":"https://www.xpersona.co/agent/clawhub-anderskev-artifact-analysis","canonicalPath":"/agent/clawhub-anderskev-artifact-analysis","generatedAt":"2026-10-12T18:16:24.511Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:52:27.079Z","emptyReason":null},"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\",...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 988 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17b1fzefm8nj8j1sdkzrze7gn83pfrg:artifact-analysis","sourceUrl":"https://clawhub.ai/anderskev/artifact-analysis","homepage":"https://clawhub.ai/anderskev/skills/artifact-analysis","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/anderskev/artifact-analysis","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/anderskev/skills/artifact-analysis","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Artifact Analysis technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:52:27.079Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:52:27.079Z","emptyReason":null},"stars":null,"forks":null,"downloads":988,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.1","tractionLabel":"988 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:52:27.010Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T21:52:27.079Z","lastCrawledAt":"2026-10-11T21:52:27.010Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T21:52:27.011Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.1","createdAt":"2026-06-01T02:21:44.440Z","changelog":"artifact-analysis 1.0.1 - Improved compatibility: Workflow now supports sequential slice processing if subagents are unavailable, ensuring identical output. - Clarified NOT-to-use conditions by specifying codebase search alternatives and linking to other skills for specific scenarios. - Updated references for subagent handling and related skill documentation. - Removed outdated or redundant file (skill-card.md).","fileCount":9,"zipByteSize":21363},{"version":"1.0.0","createdAt":"2026-04-22T04:09:57.803Z","changelog":"Initial release of artifact-analysis skill. - Provides a structured, citation-backed analysis of local documents and project knowledge. - Produces all output on disk: creates a scan plan, parallel subagent findings, and a synthesized report, each with sources. - Supports intent-driven or generic extraction over user-specified paths or auto-discovered project knowledge folders. - Strictly does not process codebase lookups, web searches, document editing, OCR, or remote sources—local plain text and markdown only. - Enforces an auditable four-step workflow with verification and failure-mode reporting. - Designed for invocation by users or programmatically by other beagle skills; never returns inline prose.","fileCount":9,"zipByteSize":21427}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17b1fzefm8nj8j1sdkzrze7gn83pfrg:artifact-analysis","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17b1fzefm8nj8j1sdkzrze7gn83pfrg:artifact-analysis` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/anderskev/artifact-analysis before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T18:16:24.508Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-anderskev-artifact-analysis/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:52:27.079Z","emptyReason":null},"readme":"Skill: Artifact Analysis\n\nOwner: anderskev\n\nSummary: 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\",...\n\nTags: latest:1.0.1\n\nVersion history:\n\nv1.0.1 | 2026-06-01T02:21:44.440Z | auto\n\nartifact-analysis 1.0.1\n\n- Improved compatibility: Workflow now supports sequential slice processing if subagents are unavailable, ensuring identical output.\n- Clarified NOT-to-use conditions by specifying codebase search alternatives and linking to other skills for specific scenarios.\n- Updated references for subagent handling and related skill documentation.\n- Removed outdated or redundant file (skill-card.md).\n\nv1.0.0 | 2026-04-22T04:09:57.803Z | auto\n\nInitial release of artifact-analysis skill.\n\n- Provides a structured, citation-backed analysis of local documents and project knowledge.\n- Produces all output on disk: creates a scan plan, parallel subagent findings, and a synthesized report, each with sources.\n- Supports intent-driven or generic extraction over user-specified paths or auto-discovered project knowledge folders.\n- Strictly does not process codebase lookups, web searches, document editing, OCR, or remote sources—local plain text and markdown only.\n- Enforces an auditable four-step workflow with verification and failure-mode reporting.\n- Designed for invocation by users or programmatically by other beagle skills; never returns inline prose.\n\nArchive index:\n\nArchive v1.0.1: 9 files, 21363 bytes\n\nFiles: references/citation-schema.md (3427b), references/companion-contract.md (6862b), references/failure-modes.md (5153b), references/report-template.md (4814b), references/skip-patterns.md (2250b), references/subagent-brief.md (4934b), skill-card.md (2060b), SKILL.md (17647b), _meta.json (136b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: artifact-analysis\ndescription: \"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.\"\n---\n\n# Artifact Analysis\n\nTurn 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.\n\nThe 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.\n\n## When to use\n\n- A user asks for a local-document read — \"analyze the docs folder\", \"scan the project for context\", \"extract what's in .beagle/concepts/\".\n- Another beagle skill invokes this one programmatically as a grounding companion (see `references/companion-contract.md`).\n- The caller wants auditable output: a plan written before extraction, findings files per slice, and a citation-backed synthesis report.\n\n## When NOT to use\n\n- Codebase lookups (\"where is this function defined\", \"grep for this symbol\"). Search the codebase instead.\n- Web research. Use [web-research](../web-research/SKILL.md).\n- Comparative evaluation of two implementations or source credibility adjudication. Use [llm-judge](../llm-judge/SKILL.md).\n- 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.\n- PDF / image OCR / format conversion. First version reads plain text and markdown only.\n- Paywalled or authentication-gated remote sources. This is a local-filesystem primitive.\n- Coaching, challenge, or reshaping of the caller's question. That belongs to the caller.\n\n## Workflow\n\nFour steps, in order. No step is skippable.\n\n### Hard gates\n\nAdvance to the next step only when the **pass condition** is true—confirm using files under `output_dir` (and tool output), not memory.\n\n| After | Pass condition |\n| --- | --- |\n| `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`)**). |\n| 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. |\n| `report.md` written | `report.md` exists; headings match `references/report-template.md` (seven sections plus `## Sources`). |\n| 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. |\n\n1. **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.\n2. **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`.\n3. **Synthesize `report.md`** — fold findings into the seven fixed sections with path-anchored citations.\n4. **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.\n\n```\nReceive paths + optional intent ──→ Auto-discover if paths empty\n                                   ↓\n                                 Write plan.md (no user-confirmation pause)\n                                   ↓\n                                 Dispatch subagents (up to 3 parallel)\n                                   ↓\n                                 Collect findings/<slice>.md files\n                                   ↓\n                                 Synthesize report.md\n                                   ↓\n                                 Return paths to caller\n```\n\nUnlike [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.\n\n## Inputs\n\n| Field        | Type               | Required | Default       | Purpose                                                                             |\n| ------------ | ------------------ | -------- | ------------- | ----------------------------------------------------------------------------------- |\n| `intent`     | string             | no       | —             | What the caller is looking for / why. When absent, the skill extracts anything structurally important. |\n| `paths`      | list of strings    | no       | auto-discover | Directories and/or explicit files. When absent, auto-discover (see below).          |\n| `output_dir` | absolute path      | no       | derived       | Where `plan.md`, `findings/`, and `report.md` land.                                 |\n| `refresh`    | bool               | no       | `false`       | When true, allow overwriting a prior run in the same `output_dir`.                  |\n\nThe skill does not parse caller-specific structures. Callers pass an intent string and/or a path list.\n\n### Auto-discovery\n\nWhen `paths` is absent or empty, scan beagle's conventional knowledge locations:\n\n- `.beagle/concepts/` — concept specs and analysis folders.\n- `.planning/` — roadmap, state, and phase artifacts.\n- `docs/` — project documentation.\n- Top-level files matching `README*`, `BRIEF*`, `OVERVIEW*`, `CONTEXT*`, `CLAUDE.md`, `AGENTS.md`.\n\nResolved paths (including any auto-discovery) are listed verbatim in `plan.md` so the caller can see exactly which files were included.\n\n### Intent modes\n\n- **`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.\n- **`intent` absent** — generic-salient-extraction mode. Subagents extract anything structurally important (insights, decisions, technical constraints, user/market context) without an interpretive filter.\n\n## Output location\n\nIf the caller passes `output_dir`, use it verbatim. Otherwise derive the default:\n\n```\n.beagle/analysis/<slug>/\n```\n\n**Slug derivation** (stable so re-running the same input on the same day lands on the same folder):\n\n1. 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).\n2. If `intent` is absent, slug from the first scanned path's basename using the same rules.\n3. Prepend `YYYY-MM-DD-`.\n\n**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`.\n\nCallers 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/`.\n\n## The scan plan (`plan.md`)\n\nThe plan is written before any subagent runs. It is the audit trail, not a review gate — the skill does not pause for user confirmation.\n\n`plan.md` contains:\n\n- **Intent** — the input string, verbatim, or `\"generic salient extraction\"` when intent is absent.\n- **Resolved paths** — every path that will actually be scanned, with a note next to any entry that came from auto-discovery vs. caller-specified.\n- **Slices** — how the resolved paths are partitioned across 1-3 subagents. Slices are non-overlapping.\n- **Per-slice briefs** — one paragraph per slice summarizing what that subagent is told to extract. Derived mechanically from the spec so a reader of `plan.md` can predict what each subagent was told.\n- **Skip patterns** — the denylist applied to this run (see `references/skip-patterns.md`).\n- **Budgets applied** — subagent count for this run (1-3) and the skim threshold in effect (see Budget defaults below).\n- **Synthesis approach** — how the per-slice findings will combine into `report.md`.\n\nReport: `Wrote plan.md` and proceed to dispatch. No pause, no gate.\n\n## Subagent dispatch\n\nUp to 3 subagents run concurrently over non-overlapping slices. Each gets a mechanically-derived brief built from `plan.md` — no interpretation drift between the plan and the briefs. The brief template lives in `references/subagent-brief.md`.\n\nEach subagent:\n\n- Scans its assigned slice of paths, honoring skim strategies (sharded-doc: read index first; large-doc: TOC/headings first) and skip patterns.\n- Writes `findings/<slice-slug>.md` under `output_dir`.\n- Returns one terse status line to the orchestrator (path + status), never inline findings.\n\nThe orchestrator waits for all subagents to finish, then verifies every expected findings file exists before synthesis. A missing file is a silent failure, recorded in `Gaps & Limitations` — see `references/failure-modes.md`.\n\n### Skim strategies\n\nSubagents do not read everything end-to-end. They apply:\n\n- **Sharded documents** (folder with `index.md` plus multiple sub-files) — read `index.md` first, then only the sub-files the index points to as relevant.\n- **Large documents** (single file > ~50 pages or > ~2000 lines) — read the TOC, executive summary, and section headings first; pull full content only from sections relevant to the intent (or structurally important when intent is absent). The findings file records which sections were skimmed vs. read fully.\n- **Short documents** (single file, moderate size) — read end-to-end.\n\n### Skip patterns\n\nSensitive, binary, and vendor/build paths are skipped silently without the caller re-specifying them. The default denylist lives in `references/skip-patterns.md`. Each subagent records the paths it skipped under the `paths_skipped` frontmatter field so the audit trail shows exactly what was excluded.\n\n## Citations\n\nEvery claim in a findings file and in `report.md` carries a citation. The shape lives in `references/citation-schema.md`. At a glance:\n\n- **Required fields:** `path` (relative to the scanned root when possible), `excerpt` (a verbatim quoted string from the document).\n- **Optional fields:** `lines` (line range or single line, only when the subagent naturally has them — never synthesized), `heading` (the nearest enclosing heading), `document_type`.\n\nInline references use `[^n]` footnotes; the full citation sits in the numbered `Sources` section at the bottom of the report.\n\n## Synthesis (`report.md`)\n\nThe report has a fixed seven-section layout, in this order. Every section is required, every time — even when a section is thin, the report includes a bullet saying so.\n\n1. `## Documents Found` — each included path with a one-line note on its relevance.\n2. `## Key Insights` — the highest-signal observations from the corpus, grouped by theme.\n3. `## User / Market Context` — users, customers, competition, market data surfaced from the documents.\n4. `## Technical Context` — platforms, constraints, integrations, dependencies.\n5. `## Ideas & Decisions` — each tagged `accepted`, `rejected`, or `open` with rationale. Rejected ideas are preserved deliberately so future work does not re-propose them.\n6. `## Raw Detail Worth Preserving` — specific quotes, data points, metrics, and other detail that would be lost to summarization.\n7. `## Gaps & Limitations` — what the corpus could not establish; which paths were empty, skipped, or unreadable; which subagents failed.\n\n`Gaps & Limitations` is required even when the scan looks complete. Honest accounting of what was and was not in the corpus is part of the product. The full literal skeleton the skill copies from lives in `references/report-template.md`.\n\n## Failure modes\n\n- **Partial success** — one or more subagents fail. The skill continues with what succeeded and enumerates each failed slice under `Gaps & Limitations`, including the last-known brief and the stub-file reason.\n- **Empty corpus** — path resolution (auto-discovery + explicit paths) yields zero readable documents. The skill writes `plan.md` and a minimal `report.md` with a single \"no documents found\" bullet under `Gaps & Limitations`, does not spawn subagents, and returns cleanly to the caller. Callers decide how to proceed.\n- **Silent-failure detection** — every subagent writes at least a stub `findings/<slice-slug>.md` with `status:` frontmatter (`ok`, `empty`, `failed`) before returning. Missing file after dispatch = silent failure, recorded in `Gaps & Limitations`.\n- **Re-run protection** — covered under \"Output location\" above; details in `references/failure-modes.md`.\n\nUnlike [web-research](../web-research/SKILL.md), artifact-analysis does **not** fail-fast on missing tools. Filesystem search (read, glob, grep) is assumed present in the agent's environment. If it is somehow absent, the skill will surface that as a subagent failure under partial-success rather than aborting the whole run.\n\nFull rules and the structured error shape live in `references/failure-modes.md`.\n\n## Budget defaults\n\nTunable knobs, not hard-coded invariants:\n\n| Knob                    | Default        |\n| ----------------------- | -------------- |\n| Parallel subagents      | 1-3            |\n| Slice overlap           | none (enforced) |\n| Skim threshold (large)  | > ~2000 lines or > ~50 pages |\n\nA caller that needs narrower or broader scope overrides by passing a more specific `paths` list — one path per subagent forces narrower slicing; a single folder lets the skill partition internally.\n\n## Companion invocation contract\n\nOther beagle skills invoke this one via a small, documented contract. The minimal call passes only `intent`; the full call adds `paths`, `output_dir`, and `refresh`.\n\nWorked examples for the three known callers (`prfaq-beagle`, `brainstorm-beagle`, `strategy-interview`) plus the success and refusal return shapes live in `references/companion-contract.md`. Callers are expected to honor the contract verbatim rather than invent parallel invocation styles.\n\n## Tone\n\nThis skill is a tone-neutral primitive. It does not:\n\n- Coach the caller on which documents matter.\n- Adjudicate document quality or claim credibility (that is `llm-judge`'s job).\n- Reshape the caller's intent into a different question.\n- Adopt a posture (hardcore, Socratic, warm) — that is the caller's job.\n- Editorialize in findings or the report.\n\nIf the caller is a coaching skill (`prfaq-beagle`, `brainstorm-beagle`), the coaching happens before and after this skill runs. Inside this skill, the intent is treated as final.\n\n## Out of scope\n\n- Scanning paywalled or authentication-gated remote sources. Use the file tools to extract content first, then pass paths in.\n- LLM-as-judge evaluation of document quality or claim credibility. Use `llm-judge`.\n- Coaching, challenge, or opinionated reshaping of the intent.\n- Rewriting or editing the scanned documents. Read-only by design.\n- Binary / image OCR, PDF text extraction, or format conversion. First version reads plain text and markdown only.\n- Multi-language analysis. English-only today.\n- Caching or re-use of prior findings across invocations.\n- Long-running or scheduled scans.\n\n## Reference files\n\n- `references/subagent-brief.md` — template the orchestrator mechanically fills from `plan.md` when dispatching each subagent.\n- `references/citation-schema.md` — required and optional citation fields, footnote convention, and a well-formed example.\n- `references/report-template.md` — literal `report.md` skeleton with all seven fixed sections.\n- `references/failure-modes.md` — partial-success, empty-corpus, silent-failure detection, and re-run protection rules.\n- `references/companion-contract.md` — programmatic invocation shape with worked examples for `prfaq-beagle`, `brainstorm-beagle`, and `strategy-interview`.\n- `references/skip-patterns.md` — default denylist (sensitive, binary/media, vendor/build) applied to every run.\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn79190nfmdb20hk6xjhzt2zv583844x\",\n  \"slug\": \"artifact-analysis\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1780280504440\n}\n\nFile v1.0.1:references/citation-schema.md\n\n# Citation Schema\n\nEvery claim in a findings file and in `report.md` carries a citation. The shape is small on purpose — enough metadata to verify without re-reading the full document, not so much that subagents start fabricating fields.\n\n## Required fields\n\n- **`path`** — the document the claim was drawn from. Relative to the scanned root when possible (e.g. `docs/architecture.md`); absolute only when the path lives outside the scanned tree.\n- **`excerpt`** — a verbatim quoted string from the document that supports the claim. Keep it short enough to read at a glance (typically 1-3 sentences), long enough to stand on its own.\n\nIf either required field is missing or would have to be fabricated, do not include the citation. Drop the claim or mark it as unverified in `Gaps & Limitations`.\n\n## Optional fields\n\nInclude only when the subagent naturally has them. Never synthesize.\n\n- **`lines`** — line range (`L42-L58`) or single line (`L42`) where the excerpt appears. Include when reading a text/markdown file with stable line numbers. Omit for documents where line granularity is ambiguous (prose documents without visible line numbers, transcluded markdown, rendered output). Never guess.\n- **`heading`** — the nearest enclosing heading, copied verbatim. Useful for anchoring the reader in long documents.\n- **`document_type`** — one of:\n  - `spec` — specification, requirements doc, or formal brief.\n  - `adr` — architecture decision record.\n  - `readme` — README, overview, or project-root context doc.\n  - `planning` — roadmap, state, phase, or plan artifact.\n  - `concept` — beagle concept spec or analysis.\n  - `transcript` — meeting notes, interview transcript, or chat log.\n  - `other` — anything that does not fit.\n\nOmit fields you do not have. An incomplete citation with two real fields beats a five-field citation with three guessed values.\n\n## Footnote convention\n\nIn findings and in `report.md`, claims use `[^n]` inline footnote markers:\n\n```markdown\nThe skill must not pause for user confirmation before spawning subagents[^3].\n```\n\nThe numbered `Sources` section at the bottom of `report.md` lists each citation in order, matching the footnote number. Numbering is global across the report, not per-section.\n\n## Example — well-formed citation block\n\nIn `report.md`, the `Sources` section entries look like this:\n\n```markdown\n[^1]: **Path**: .beagle/concepts/artifact-analysis/spec.md\n      **Excerpt**: \"Partial-success behavior: if a subagent fails, the skill continues with the remaining findings and records the failure explicitly under Gaps & Limitations.\"\n      **Lines**: L29\n      **Heading**: Requirements\n      **Document type**: spec\n\n[^2]: **Path**: docs/architecture.md\n      **Excerpt**: \"All long-running jobs run on the worker queue, never the request thread.\"\n      **Heading**: Background Processing\n      **Document type**: readme\n```\n\nCitation `[^2]` omits `Lines` because the subagent did not have a stable line-number anchor. That is correct behavior — omit rather than guess.\n\n## Incomplete-metadata policy\n\nIf a claim is genuinely load-bearing but the document lacks a clear line number or heading, keep the citation with the required fields (`path` + `excerpt`) only. Do not invent a line number to satisfy a schema slot. If the absence makes the claim hard to verify, note the uncertainty in `Gaps & Limitations` rather than citing confidently.\n\nFile v1.0.1:references/companion-contract.md\n\n# Companion Invocation Contract\n\nOther beagle skills invoke `artifact-analysis` via this contract. It is small on purpose — no required inputs (!), three optional parameters for scoping and one for overwrite control, two return shapes.\n\nCallers are expected to honor the contract verbatim rather than invent parallel invocation styles. If a new caller needs behavior that the contract does not support, extend the contract here first, not in the calling skill.\n\n## Minimal call\n\n```yaml\n# No parameters at all — auto-discover every beagle knowledge location, generic-salient-extraction mode.\n```\n\nWith no inputs, the skill scans `.beagle/concepts/`, `.planning/`, `docs/`, and top-level README/brief/overview files, applies the default skip denylist, and extracts anything structurally important. Output lands at `.beagle/analysis/<YYYY-MM-DD>-<first-path-basename>/`.\n\n## Full call\n\n```yaml\nintent: \"competitive and technical grounding for PRFAQ on AI coding-assistant pricing\"\npaths:\n  - .beagle/concepts/ai-coding-pricing/\n  - docs/\noutput_dir: \"/abs/path/.beagle/concepts/ai-coding-pricing/analysis/\"\nrefresh: false\n```\n\n## Input semantics\n\n- **`intent`** — one string describing what the caller wants. When present, extraction is weighted toward relevance to the intent. When absent, the skill runs in generic-salient-extraction mode. Tone-neutral; the skill does not reshape the intent.\n- **`paths`** — directories and/or explicit files. When absent or empty, the skill auto-discovers beagle's conventional knowledge locations (see SKILL.md §Auto-discovery). When present, only the listed paths are scanned — auto-discovery does not run.\n- **`output_dir`** — absolute path. Callers embedding artifact-analysis in their own concept folder (e.g. `prfaq-beagle`) pass this explicitly so the analysis sits next to its consumer.\n- **`refresh`** — when `true`, a prior run in `output_dir` is archived to `<output_dir>/.archive-<timestamp>/` before the new run starts. See `failure-modes.md` for the archive rule.\n\n## Return shapes\n\nThis skill returns one of two shapes. Callers that invoke multiple beagle companions should handle the union of error codes across all companions they call — sibling companions (e.g. `web-research`) may return different error codes (notably `web-tools-unavailable`).\n\n- **success** — artifacts written. An empty-corpus run still returns this shape with a minimal `report.md`; the caller detects empty-corpus by reading the report, not by catching an error.\n- **error: `prior-run-present`** — `output_dir` already holds a prior run and `refresh` is false; nothing written.\n\n### Success\n\n```yaml\nplan: \"<output_dir>/plan.md\"\nreport: \"<output_dir>/report.md\"\nfindings_dir: \"<output_dir>/findings/\"\n```\n\nThe caller receives absolute paths. All evidence lives on disk — nothing returns inline.\n\n### Success with empty corpus\n\nEmpty-corpus is **not** an error. When path resolution yields zero readable documents, the skill still returns the Success shape above: `plan.md` exists (with an empty `Resolved paths` list), `report.md` exists (with every section present plus a `Gaps & Limitations` entry explaining no readable documents were found), and `findings_dir` exists (empty). Callers detect empty-corpus by reading `report.md`, not by catching an error.\n\n### Refused (prior run present, no refresh)\n\n```yaml\nerror: \"prior-run-present\"\ndetail: \"<output_dir> already contains plan.md or report.md. Pass refresh: true to archive and overwrite.\"\n```\n\nThe caller decides whether to retry with `refresh: true`, pick a different `output_dir`, or surface the refusal to its user.\n\n## Worked examples\n\n### `prfaq-beagle` — Ignition grounding\n\nThe PRFAQ's Ignition phase needs competitive and technical grounding from the user's own documents (PRDs, briefs, prior decisions). PRFAQ passes:\n\n```yaml\nintent: \"competitive and technical grounding for PRFAQ on AI coding-assistant pricing\"\npaths: []  # empty → auto-discover .beagle/concepts/, .planning/, docs/\noutput_dir: \"/abs/path/.beagle/concepts/ai-coding-pricing/analysis/\"\nrefresh: false\n```\n\nEmpty `paths` triggers auto-discovery so PRFAQ does not have to know where the user keeps briefs. `output_dir` lands inside the PRFAQ concept folder so the audit trail travels with the concept.\n\n### `brainstorm-beagle` — reference-point grounding\n\nMid-brainstorm, the user says \"go read the docs folder and tell me what we already decided.\" Brainstorm calls:\n\n```yaml\nintent: \"prior decisions and reference points relevant to the current idea\"\npaths:\n  - docs/\n  - .beagle/concepts/\noutput_dir: \"/abs/path/.beagle/concepts/task-sub-tasks/analysis/\"\nrefresh: false\n```\n\nExplicit `paths` keeps the scan narrow. `output_dir` lands inside the brainstorm concept folder so the reference points can link straight to `report.md`.\n\n### `strategy-interview` — context grounding\n\nDuring strategy interview Phase 1 discovery, the user needs a structured read of prior strategy artifacts. Strategy-interview calls:\n\n```yaml\nintent: \"background context for platform-team H1 2026 strategy discovery\"\npaths:\n  - .beagle/strategy/\n  - docs/\noutput_dir: \"/abs/path/.beagle/strategy/platform-team-h1-2026/analysis/\"\nrefresh: false\n```\n\n`output_dir` lands inside the strategy interview's working-state folder so the analysis sits alongside `state.md`, `evidence.md`, and `composition.md`.\n\n### Standalone user — \"analyze these docs\"\n\nA user types \"read everything in docs/ and tell me what's there\" with no prior context. The skill is triggered directly and runs:\n\n```yaml\n# Triggered by user chatter. No intent passed → generic-salient-extraction mode.\npaths:\n  - docs/\n# output_dir defaults to .beagle/analysis/<YYYY-MM-DD>-docs/\n```\n\nThe user gets a `report.md` they can open immediately — no caller-specific wrapping.\n\n## Non-obligations\n\nThe contract is explicit about what this skill does **not** do:\n\n- **No intent reshaping.** The caller hands in an intent (or nothing). The skill does not argue with it, sharpen it, or reframe it.\n- **No coaching posture.** `artifact-analysis` is tone-neutral. Callers that need a coaching tone (`prfaq-beagle`'s hardcore coach, `brainstorm-beagle`'s thinking partner) apply that tone before and after, not inside.\n- **No inline findings.** Every deliverable is a file. Callers that want inline prose should summarize from `report.md` themselves.\n- **No cross-run caching.** Each invocation stands alone. Callers that need caching build it themselves at the call site.\n- **No doc editing or rewriting.** Read-only by design.\n\n## Extending the contract\n\nIf a new caller needs behavior not covered here, add a field to the input table in SKILL.md first, document it in this file with a worked example, then update caller skills to use it. Parallel-invocation styles fragment the contract and re-introduce the reason this skill exists.\n\nFile v1.0.1:references/failure-modes.md\n\n# Failure Modes\n\nFour failure cases the skill handles explicitly. Silent failures are the worst kind — every rule below exists to make a failure visible to the caller and preserve what succeeded.\n\nUnlike web-research, artifact-analysis does **not** fail-fast on missing tools. Filesystem search (read, glob, grep) is assumed present in the agent's environment. If it is somehow absent, that surfaces as a per-subagent failure under partial-success rather than aborting the whole run.\n\n## Partial success\n\nOne or more subagents fail; others return valid findings.\n\n**Behavior:** continue with the successful findings. Do not abort the run.\n\nIn `report.md`, under `Gaps & Limitations`, enumerate every failed slice:\n\n- Name the slice.\n- Include the subagent's last-known brief (or a one-line summary of what it was asked to scan).\n- Include the `reason` line from the stub findings file (see \"Silent-failure detection\" below).\n\nExample:\n\n```markdown\n## Gaps & Limitations\n\n- **Slice \"planning-folder\"** (status: failed) — subagent returned \"Read timeout on .planning/phase-3/PLAN.md after 3 retries\". Caller may retry this slice alone, or re-run with `refresh: true` after investigating the file.\n```\n\n## Empty corpus\n\nPath resolution (auto-discovery + explicit paths) yields zero readable documents after the skip denylist is applied.\n\n**Behavior:** do not spawn subagents. Return cleanly.\n\nThe skill writes:\n\n- `plan.md` with an empty `Resolved paths` list and a note that no readable documents were found.\n- `report.md` with every section present but containing a single bullet each, plus a `Gaps & Limitations` entry:\n\n```markdown\n## Gaps & Limitations\n\n- No readable documents found under the resolved paths. The caller passed <paths> and auto-discovery surfaced <auto-discovered paths>; every entry was either absent, empty, or matched the skip denylist. Pass a broader `paths` list, or point at a different folder.\n```\n\nReturning cleanly lets callers handle \"no documents found\" gracefully (e.g. fall back to asking the user to paste content) rather than crashing on an expected-but-uncommon state.\n\n## Silent-failure detection (stub-file rule)\n\nContext exhaustion and tool errors can cause a subagent to return without producing any output file. The orchestrator has no way to distinguish that from \"the subagent finished but the file is missing for some other reason\" — so the contract requires every subagent to write at least a stub file before returning.\n\n**Contract (enforced by `subagent-brief.md`):**\n\n- Every subagent writes `findings/<slice-slug>.md` with a `status:` frontmatter field: `ok`, `empty`, or `failed`.\n- On `empty` or `failed`, the file includes a one-line `reason:` field.\n- On `ok`, `reason` is omitted.\n\n**Orchestrator check, post-dispatch:**\n\nFor every expected slice, test that the findings file exists. For any missing file, record a silent-failure entry under `Gaps & Limitations`:\n\n```markdown\n- **Slice \"<name>\"** — subagent returned without producing a findings file (likely context exhaustion or tool error). Last known brief: \"<brief summary>\".\n```\n\nThis is why \"legitimately empty\" results must use `status: empty` with a reason rather than writing nothing — so empty-but-ok is never confused with silent context loss.\n\n## Re-run protection\n\nEach run is supposed to be self-contained and auditable. Silently overwriting a prior run destroys the audit trail; silently appending produces incoherent findings.\n\n**Rule:** before writing anything to `output_dir`, check whether it already contains `plan.md` or `report.md`.\n\n- **If it does and `refresh` is not `true`:** refuse with a message naming the existing folder.\n\n  ```\n  Refusing to write: <output_dir> already contains a prior analysis run. Pass `refresh: true` to archive and overwrite, or choose a different output_dir.\n  ```\n\n- **If it does and `refresh: true`:** move the existing contents to `<output_dir>/.archive-<YYYYMMDD-HHMMSS>/` first, then proceed with a fresh run. The archive preserves the audit trail.\n\n- **If it does not:** proceed normally.\n\nThis rule applies even when the default slug matches a prior run on the same day — stable slugs are a feature (callers can re-derive the folder), but the user must explicitly opt in to overwriting.\n\n## Verification checklist (orchestrator runs at end)\n\nBefore returning success to the caller, verify:\n\n- [ ] `plan.md` exists at `<output_dir>/plan.md`.\n- [ ] `findings/<slice-slug>.md` exists for every slice in `plan.md` (unless the empty-corpus path was taken).\n- [ ] Every findings file has `status:` frontmatter.\n- [ ] Every `status: empty` or `status: failed` file has a `reason:` line.\n- [ ] `report.md` exists at `<output_dir>/report.md`.\n- [ ] `report.md` has all seven top-level sections in order: `Documents Found`, `Key Insights`, `User / Market Context`, `Technical Context`, `Ideas & Decisions`, `Raw Detail Worth Preserving`, `Gaps & Limitations`.\n- [ ] `report.md` has a `Sources` section and every `[^n]` footnote in the body has a matching entry.\n\nAny check that fails becomes an entry in `Gaps & Limitations` — the run does not silently produce a broken deliverable.\n\nFile v1.0.1:references/report-template.md\n\n# Synthesis Skeleton\n\nThe synthesis document, saved as `report.md` under the run's output directory, uses a fixed seven-section layout. Sections appear in this order, every time, even when one is short. `Gaps & Limitations` is required even when findings look complete — honest accounting of what could not be established is part of the product.\n\nCopy the skeleton below into the synthesis file and fill each section.\n\n## Layout\n\n```markdown\n# Analysis: <intent, verbatim from plan.md — or \"Generic extraction of <slug>\" when intent is absent>\n\n## Documents Found\n\n- `<relative path 1>` — <one-line note on what this document covers and why it was included>\n- `<relative path 2>` — <...>\n- `<relative path N>` — <...>\n\nInclude every path that was actually scanned (end-to-end or skimmed). Paths that were under the skip denylist go in `Gaps & Limitations`, not here.\n\n## Key Insights\n\nGroup by theme. Every claim carries a [^n] footnote.\n\n### <Theme 1>\n\n<Bullets or short paragraphs. Each factual claim has a footnote.>\n\n### <Theme 2>\n\n<...>\n\n### <Theme N>\n\n<...>\n\n## User / Market Context\n\n<Users, customers, competition, market data surfaced from the documents. Footnote every specific claim. If the corpus does not contain user/market content, write a single bullet: \"No user/market content surfaced by this scan.\" — do not delete the section.>\n\n## Technical Context\n\n<Platforms, constraints, integrations, dependencies, operational considerations. Footnote every specific claim. If the corpus does not contain technical content, write a single bullet noting so — do not delete the section.>\n\n## Ideas & Decisions\n\nEvery idea carries a tag — `accepted`, `rejected`, or `open` — and rationale. Preserve rejected ideas so future work does not re-propose them.\n\n- **[accepted]** <idea> — <rationale from the document> [^n]\n- **[rejected]** <idea> — <rationale for rejection> [^n]\n- **[open]** <idea> — <what is still undecided> [^n]\n\n## Raw Detail Worth Preserving\n\nSpecific quotes, metrics, and data points that would be lost to summarization. Each entry is a verbatim excerpt (or near-verbatim with explicit ellipsis) plus a footnote.\n\n- \"<quote>\" [^n]\n- \"<data point>\" [^n]\n\n## Gaps & Limitations\n\n- <What the corpus could not establish, and why. One bullet per gap.>\n- <Any path that was empty, unreadable, or skipped via the denylist — name the path and the reason.>\n- <Any subagent that failed or returned empty — name the slice and the reason from its stub file.>\n- <Claims that were dropped because the citation would have had to be fabricated.>\n\nThis section is never empty. If the scan was clean, include at minimum a bullet naming what follow-up reading would sharpen the picture.\n\n## Sources\n\n[^1]: **Path**: <relative path>\n      **Excerpt**: \"<verbatim quote>\"\n      **Lines**: <optional, omit if absent>\n      **Heading**: <optional, omit if absent>\n      **Document type**: <optional, omit if absent>\n\n[^2]: **Path**: <...>\n      **Excerpt**: \"<...>\"\n\n[^n]: <...>\n```\n\n## Rules\n\n- **Title line** uses the intent verbatim from `plan.md`. When intent is absent, use `Generic extraction of <slug>`.\n- **`Documents Found`** lists every included path (read or skimmed). Skipped paths go in `Gaps & Limitations`.\n- **`Key Insights`** groups by theme, not by source document. If one theme only came from one document, that is fine — one bullet, one footnote.\n- **`User / Market Context`, `Technical Context`, `Raw Detail Worth Preserving`** — never delete these sections. If the corpus has nothing to say, include a single bullet saying so. Prefer `\"No <section> content surfaced by this scan.\"` over synthesized content — an empty placeholder is correct when the corpus is thin; fabricated content is not.\n- **`Ideas & Decisions`** preserves rejected ideas with the rationale for rejection, not just accepted ones. This is the feature, not a nice-to-have.\n- **`Gaps & Limitations`** is never empty. At minimum, name what follow-up reading would sharpen the answer.\n- **`Sources`** uses global numbering — `[^1]` through `[^n]` across the whole document, not per-section. Citation shape per `citation-schema.md`.\n\n## Sourcing discipline\n\n- Every bullet in `Key Insights`, `User / Market Context`, `Technical Context`, and `Ideas & Decisions` that makes a specific factual claim carries a footnote. Broad synthesis statements can stand without a footnote only if they summarize cited claims elsewhere in the document.\n- `Raw Detail Worth Preserving` is 100% cited — every entry is an excerpt with a footnote.\n- If a claim cannot be cited, either drop it or move it to `Gaps & Limitations` as something the corpus did not establish.\n- `Sources` entries match every `[^n]` used in the body. Orphan citations (listed in `Sources` but never referenced) should be removed.\n\nFile v1.0.1:references/skip-patterns.md\n\n# Default Skip Patterns\n\nThe subagent's default denylist. Applied without the caller re-specifying. Every skipped path is recorded under the `paths_skipped` frontmatter field so the audit trail shows exactly what was excluded.\n\nThree groups: sensitive, binary/media, vendor/build.\n\n## Sensitive\n\nSecrets, credentials, and user-level config. Never scanned.\n\n- `.env`, `.env.*`\n- `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.crt`, `*.cer`\n- `.aws/`, `.ssh/`, `.gnupg/`\n- `credentials.*`, `secrets.*`\n- `*.htpasswd`, `*.netrc`\n\n## Binary / media\n\nFormats the first version does not parse. Passed over without an error.\n\n- Images: `*.png`, `*.jpg`, `*.jpeg`, `*.gif`, `*.webp`, `*.ico`, `*.svg`, `*.bmp`, `*.tiff`\n- Documents: `*.pdf`, `*.docx`, `*.doc`, `*.pptx`, `*.ppt`, `*.xlsx`, `*.xls`\n- Archives: `*.zip`, `*.tar`, `*.tar.gz`, `*.tgz`, `*.gz`, `*.bz2`, `*.xz`, `*.7z`, `*.rar`\n- Audio/video: `*.mp3`, `*.wav`, `*.flac`, `*.ogg`, `*.mp4`, `*.mov`, `*.mkv`, `*.avi`, `*.webm`\n- Databases: `*.sqlite`, `*.sqlite3`, `*.db`\n- Binaries: `*.exe`, `*.dll`, `*.so`, `*.dylib`, `*.a`, `*.o`, `*.class`, `*.jar`\n\n## Vendor / build\n\nGenerated output and vendored dependencies. Noise, not signal.\n\n- `.git/`\n- `node_modules/`\n- `.venv/`, `venv/`, `env/`\n- `__pycache__/`, `*.pyc`\n- `dist/`, `build/`, `out/`, `target/`\n- `coverage/`, `.coverage`\n- `.next/`, `.nuxt/`, `.svelte-kit/`\n- `.cache/`, `.parcel-cache/`\n- `vendor/`, `Pods/`\n- `.DS_Store`, `Thumbs.db`\n\n## Rules\n\n- **Silent skip, audited record.** Subagents do not stop to explain why a path was skipped. Every skipped path lands in `paths_skipped`.\n- **Case-insensitive extension matching.** `.ENV` is skipped just like `.env`.\n- **Directory patterns match as prefixes.** `node_modules/` skips everything under it.\n- **No runtime extension.** The denylist is read-only during a run. A caller that wants to scan a normally-skipped path passes it explicitly in `paths` — the brief records it, and the subagent reads it. (Explicit caller intent overrides the default.)\n- **Sensitive list is non-overridable.** `.env`, `*.pem`, `*.key`, and credential files are always skipped even when explicitly passed. If a caller needs those contents, they paste them in directly rather than routing through this skill.\n\nFile v1.0.1:references/subagent-brief.md\n\n# Subagent Brief Template\n\nThe orchestrator builds one brief per slice, mechanically, from `plan.md`. Every subagent gets the same shape so a caller reading `plan.md` can predict what each subagent was told.\n\nFill the template verbatim — no paraphrasing, no interpretation drift. Subagents return one terse status line to the orchestrator; all findings land in the output file.\n\n## Template\n\n```\nYou are one of up to 3 parallel artifact-analysis subagents. Scan a single slice of paths and write findings to disk.\n\nSlice: <slice name, copied from plan.md>\nIntent: <intent string, verbatim from plan.md — or \"generic salient extraction\" if absent>\nPaths to scan:\n  - <path 1 from plan.md for this slice>\n  - <path 2 from plan.md for this slice>\n  - <...>\n\nWhat to extract:\n  - Key insights — structurally important observations, decisions, and themes\n  - User / market context — users, customers, competition, market data\n  - Technical context — platforms, constraints, integrations, dependencies\n  - Ideas & decisions — tagged accepted / rejected / open (preserve rejected ideas with rationale)\n  - Raw detail worth preserving — specific quotes, metrics, and data points\n  - Gaps — what the corpus could not establish; empty/unreadable paths\n\n  When intent is present, weight extraction toward what is relevant to that intent. When intent is absent, extract anything structurally important without an interpretive filter.\n\nSkim strategy:\n  - Sharded documents (folder with index.md plus multiple files): read index.md first, then only the sub-files the index points to as relevant.\n  - Large documents (single file > ~2000 lines or > ~50 pages): read the TOC, executive summary, and section headings first; pull full content only from relevant sections. Record skimmed-vs-read status per file.\n  - Short documents: read end-to-end.\n\nSkip patterns: apply the default denylist from references/skip-patterns.md (sensitive, binary/media, vendor/build). Record every skipped path under the paths_skipped frontmatter field.\n\nOutput path: <output_dir>/findings/<slice-slug>.md\n\nCitation rules: every claim carries a [^n] footnote. Citations use source path (relative to the scanned root when possible) + verbatim excerpt. Include lines and heading only when the subagent naturally has them; never synthesized or guessed. See references/citation-schema.md for the full shape.\n\nRequired frontmatter on the output file:\n---\nstatus: ok | empty | failed\nslice: <slice name>\nbrief_hash: <hash of this brief, supplied by the orchestrator>\nstarted_at: <ISO timestamp>\nfinished_at: <ISO timestamp>\npaths_read: [<paths read end-to-end>]\npaths_skimmed: [<paths where only TOC/index/headings were consumed>]\npaths_skipped: [<paths skipped via the default denylist>]\nreason: <one line — required when status is empty or failed, omit otherwise>\n---\n\nPartial-failure protocol: always write the output file, even if the subagent fails or finds nothing. Use status: failed with a one-line reason on tool errors or exhaustion. Use status: empty with a reason when the slice is legitimately empty (\"all paths under this slice were under the skip denylist\" or \"all files were unreadable\"). Never exit without writing the file — absence of the file is treated as a silent failure.\n\nReturn: a single status line in this exact shape, and nothing else:\n<path-to-findings-file> <status>\n\nExample: /abs/path/findings/planning-folder.md ok\n```\n\n## Orchestrator responsibilities\n\n- **Build `<slice-slug>`** by the same rule as the run slug in SKILL.md (lowercase, punctuation stripped, whitespace → hyphens, truncated to 60 chars on a word boundary). Keep it stable across runs so `refresh: true` can match archived prior files.\n- **Compute `brief_hash`** over the filled-in brief text before dispatch so the findings file's provenance is verifiable.\n- **Guarantee non-overlapping slices.** The orchestrator partitions resolved paths before building briefs; no path appears in more than one slice.\n- **Verify every expected file exists** after all subagents return. Any missing file = silent failure per `failure-modes.md`.\n- **Never merge findings into one file.** Synthesis happens later, in `report.md`.\n\n## Subagent responsibilities\n\n- **Write the output file even on failure.** Absence is treated as silent context exhaustion.\n- **Do not reshape the intent or the slice.** If the brief is wrong, flag it in `reason` and return `status: failed` — do not silently pivot to a different scope.\n- **Apply skim strategies.** Do not read a 2000-line file end-to-end when the TOC tells you only three sections are relevant. Record the skim/read decision in the frontmatter path lists.\n- **Apply skip patterns silently.** Every skipped path goes in `paths_skipped` — no need to note it in the findings body.\n- **No inline returns.** The only thing that crosses back to the orchestrator is the status line. All evidence lives in the findings file.\n\nFile v1.0.1:skill-card.md\n\n## Description:\n\nReads local documents and project knowledge into an auditable scan plan, per-slice findings, and a cited synthesis report on disk.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[anderskev](https://clawhub.ai/user/anderskev)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to scan local plain-text or Markdown project materials and produce auditable, path-cited analysis artifacts for downstream planning or documentation work.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The security summary flags possible exposure of sensitive credential-file contents during local document analysis.\n\nMitigation: Review before installing, use explicit paths and output_dir values, avoid no-parameter auto-discovery on private projects, and provide only sanitized, redacted excerpts when skipped sensitive files are needed.\n\n## Reference(s):\n\n- [Artifact Analysis ClawHub Skill Page](https://clawhub.ai/anderskev/skills/artifact-analysis)\n- [Citation Schema](references/citation-schema.md)\n- [Companion Invocation Contract](references/companion-contract.md)\n- [Failure Modes](references/failure-modes.md)\n- [Synthesis Skeleton](references/report-template.md)\n- [Default Skip Patterns](references/skip-patterns.md)\n- [Subagent Brief Template](references/subagent-brief.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, guidance]\n\n**Output Format:** [Markdown files with path-anchored citations]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes plan.md, findings files, and report.md under an output directory; reports are citation-backed and stored on disk rather than returned inline.]\n\n## Skill Version(s):\n\n1.0.1 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.0: 9 files, 21427 bytes\n\nFiles: references/citation-schema.md (3427b), references/companion-contract.md (6862b), references/failure-modes.md (5160b), references/report-template.md (4814b), references/skip-patterns.md (2354b), references/subagent-brief.md (4934b), skill-card.md (2433b), SKILL.md (17386b), _meta.json (136b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: artifact-analysis\ndescription: \"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.\"\n---\n\n# Artifact Analysis\n\nTurn 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.\n\nThe 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.\n\n## When to use\n\n- A user asks for a local-document read — \"analyze the docs folder\", \"scan the project for context\", \"extract what's in .beagle/concepts/\".\n- Another beagle skill invokes this one programmatically as a grounding companion (see `references/companion-contract.md`).\n- The caller wants auditable output: a plan written before extraction, findings files per slice, and a citation-backed synthesis report.\n\n## When NOT to use\n\n- Codebase lookups (\"where is this function defined\", \"grep for this symbol\"). Use Grep/Glob.\n- Web research. Use `web-research`.\n- Comparative evaluation of two implementations or source credibility adjudication. Use `llm-judge`.\n- Rewriting or editing the scanned documents. Use `humanize-beagle` or the file tools.\n- PDF / image OCR / format conversion. First version reads plain text and markdown only. `beagle-core:docling` is the future path.\n- Paywalled or authentication-gated remote sources. This is a local-filesystem primitive.\n- Coaching, challenge, or reshaping of the caller's question. That belongs to the caller.\n\n## Workflow\n\nFour steps, in order. No step is skippable.\n\n### Hard gates\n\nAdvance to the next step only when the **pass condition** is true—confirm using files under `output_dir` (and tool output), not memory.\n\n| After | Pass condition |\n| --- | --- |\n| `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`)**). |\n| 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. |\n| `report.md` written | `report.md` exists; headings match `references/report-template.md` (seven sections plus `## Sources`). |\n| 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. |\n\n1. **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.\n2. **Dispatch subagents** — spawn 1-3 parallel subagents over non-overlapping slices of the resolved paths. Each writes `findings/<slice-slug>.md` under `output_dir`.\n3. **Synthesize `report.md`** — fold findings into the seven fixed sections with path-anchored citations.\n4. **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.\n\n```\nReceive paths + optional intent ──→ Auto-discover if paths empty\n                                   ↓\n                                 Write plan.md (no user-confirmation pause)\n                                   ↓\n                                 Dispatch subagents (up to 3 parallel)\n                                   ↓\n                                 Collect findings/<slice>.md files\n                                   ↓\n                                 Synthesize report.md\n                                   ↓\n                                 Return paths to caller\n```\n\nUnlike `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.\n\n## Inputs\n\n| Field        | Type               | Required | Default       | Purpose                                                                             |\n| ------------ | ------------------ | -------- | ------------- | ----------------------------------------------------------------------------------- |\n| `intent`     | string             | no       | —             | What the caller is looking for / why. When absent, the skill extracts anything structurally important. |\n| `paths`      | list of strings    | no       | auto-discover | Directories and/or explicit files. When absent, auto-discover (see below).          |\n| `output_dir` | absolute path      | no       | derived       | Where `plan.md`, `findings/`, and `report.md` land.                                 |\n| `refresh`    | bool               | no       | `false`       | When true, allow overwriting a prior run in the same `output_dir`.                  |\n\nThe skill does not parse caller-specific structures. Callers pass an intent string and/or a path list.\n\n### Auto-discovery\n\nWhen `paths` is absent or empty, scan beagle's conventional knowledge locations:\n\n- `.beagle/concepts/` — concept specs and analysis folders.\n- `.planning/` — roadmap, state, and phase artifacts.\n- `docs/` — project documentation.\n- Top-level files matching `README*`, `BRIEF*`, `OVERVIEW*`, `CONTEXT*`, `CLAUDE.md`, `AGENTS.md`.\n\nResolved paths (including any auto-discovery) are listed verbatim in `plan.md` so the caller can see exactly which files were included.\n\n### Intent modes\n\n- **`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.\n- **`intent` absent** — generic-salient-extraction mode. Subagents extract anything structurally important (insights, decisions, technical constraints, user/market context) without an interpretive filter.\n\n## Output location\n\nIf the caller passes `output_dir`, use it verbatim. Otherwise derive the default:\n\n```\n.beagle/analysis/<slug>/\n```\n\n**Slug derivation** (stable so re-running the same input on the same day lands on the same folder):\n\n1. 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).\n2. If `intent` is absent, slug from the first scanned path's basename using the same rules.\n3. Prepend `YYYY-MM-DD-`.\n\n**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`.\n\nCallers 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/`.\n\n## The scan plan (`plan.md`)\n\nThe plan is written before any subagent runs. It is the audit trail, not a review gate — the skill does not pause for user confirmation.\n\n`plan.md` contains:\n\n- **Intent** — the input string, verbatim, or `\"generic salient extraction\"` when intent is absent.\n- **Resolved paths** — every path that will actually be scanned, with a note next to any entry that came from auto-discovery vs. caller-specified.\n- **Slices** — how the resolved paths are partitioned across 1-3 subagents. Slices are non-overlapping.\n- **Per-slice briefs** — one paragraph per slice summarizing what that subagent is told to extract. Derived mechanically from the spec so a reader of `plan.md` can predict what each subagent was told.\n- **Skip patterns** — the denylist applied to this run (see `references/skip-patterns.md`).\n- **Budgets applied** — subagent count for this run (1-3) and the skim threshold in effect (see Budget defaults below).\n- **Synthesis approach** — how the per-slice findings will combine into `report.md`.\n\nReport: `Wrote plan.md` and proceed to dispatch. No pause, no gate.\n\n## Subagent dispatch\n\nUp to 3 subagents run concurrently over non-overlapping slices. Each gets a mechanically-derived brief built from `plan.md` — no interpretation drift between the plan and the briefs. The brief template lives in `references/subagent-brief.md`.\n\nEach subagent:\n\n- Scans its assigned slice of paths, honoring skim strategies (sharded-doc: read index first; large-doc: TOC/headings first) and skip patterns.\n- Writes `findings/<slice-slug>.md` under `output_dir`.\n- Returns one terse status line to the orchestrator (path + status), never inline findings.\n\nThe orchestrator waits for all subagents to finish, then verifies every expected findings file exists before synthesis. A missing file is a silent failure, recorded in `Gaps & Limitations` — see `references/failure-modes.md`.\n\n### Skim strategies\n\nSubagents do not read everything end-to-end. They apply:\n\n- **Sharded documents** (folder with `index.md` plus multiple sub-files) — read `index.md` first, then only the sub-files the index points to as relevant.\n- **Large documents** (single file > ~50 pages or > ~2000 lines) — read the TOC, executive summary, and section headings first; pull full content only from sections relevant to the intent (or structurally important when intent is absent). The findings file records which sections were skimmed vs. read fully.\n- **Short documents** (single file, moderate size) — read end-to-end.\n\n### Skip patterns\n\nSensitive, binary, and vendor/build paths are skipped silently without the caller re-specifying them. The default denylist lives in `references/skip-patterns.md`. Each subagent records the paths it skipped under the `paths_skipped` frontmatter field so the audit trail shows exactly what was excluded.\n\n## Citations\n\nEvery claim in a findings file and in `report.md` carries a citation. The shape lives in `references/citation-schema.md`. At a glance:\n\n- **Required fields:** `path` (relative to the scanned root when possible), `excerpt` (a verbatim quoted string from the document).\n- **Optional fields:** `lines` (line range or single line, only when the subagent naturally has them — never synthesized), `heading` (the nearest enclosing heading), `document_type`.\n\nInline references use `[^n]` footnotes; the full citation sits in the numbered `Sources` section at the bottom of the report.\n\n## Synthesis (`report.md`)\n\nThe report has a fixed seven-section layout, in this order. Every section is required, every time — even when a section is thin, the report includes a bullet saying so.\n\n1. `## Documents Found` — each included path with a one-line note on its relevance.\n2. `## Key Insights` — the highest-signal observations from the corpus, grouped by theme.\n3. `## User / Market Context` — users, customers, competition, market data surfaced from the documents.\n4. `## Technical Context` — platforms, constraints, integrations, dependencies.\n5. `## Ideas & Decisions` — each tagged `accepted`, `rejected`, or `open` with rationale. Rejected ideas are preserved deliberately so future work does not re-propose them.\n6. `## Raw Detail Worth Preserving` — specific quotes, data points, metrics, and other detail that would be lost to summarization.\n7. `## Gaps & Limitations` — what the corpus could not establish; which paths were empty, skipped, or unreadable; which subagents failed.\n\n`Gaps & Limitations` is required even when the scan looks complete. Honest accounting of what was and was not in the corpus is part of the product. The full literal skeleton the skill copies from lives in `references/report-template.md`.\n\n## Failure modes\n\n- **Partial success** — one or more subagents fail. The skill continues with what succeeded and enumerates each failed slice under `Gaps & Limitations`, including the last-known brief and the stub-file reason.\n- **Empty corpus** — path resolution (auto-discovery + explicit paths) yields zero readable documents. The skill writes `plan.md` and a minimal `report.md` with a single \"no documents found\" bullet under `Gaps & Limitations`, does not spawn subagents, and returns cleanly to the caller. Callers decide how to proceed.\n- **Silent-failure detection** — every subagent writes at least a stub `findings/<slice-slug>.md` with `status:` frontmatter (`ok`, `empty`, `failed`) before returning. Missing file after dispatch = silent failure, recorded in `Gaps & Limitations`.\n- **Re-run protection** — covered under \"Output location\" above; details in `references/failure-modes.md`.\n\nUnlike `web-research`, artifact-analysis does **not** fail-fast on missing tools. Filesystem tooling (Read, Glob, Grep) is assumed present in the Claude Code environment. If it is somehow absent, the skill will surface that as a subagent failure under partial-success rather than aborting the whole run.\n\nFull rules and the structured error shape live in `references/failure-modes.md`.\n\n## Budget defaults\n\nTunable knobs, not hard-coded invariants:\n\n| Knob                    | Default        |\n| ----------------------- | -------------- |\n| Parallel subagents      | 1-3            |\n| Slice overlap           | none (enforced) |\n| Skim threshold (large)  | > ~2000 lines or > ~50 pages |\n\nA caller that needs narrower or broader scope overrides by passing a more specific `paths` list — one path per subagent forces narrower slicing; a single folder lets the skill partition internally.\n\n## Companion invocation contract\n\nOther beagle skills invoke this one via a small, documented contract. The minimal call passes only `intent`; the full call adds `paths`, `output_dir`, and `refresh`.\n\nWorked examples for the three known callers (`prfaq-beagle`, `brainstorm-beagle`, `strategy-interview`) plus the success and refusal return shapes live in `references/companion-contract.md`. Callers are expected to honor the contract verbatim rather than invent parallel invocation styles.\n\n## Tone\n\nThis skill is a tone-neutral primitive. It does not:\n\n- Coach the caller on which documents matter.\n- Adjudicate document quality or claim credibility (that is `llm-judge`'s job).\n- Reshape the caller's intent into a different question.\n- Adopt a posture (hardcore, Socratic, warm) — that is the caller's job.\n- Editorialize in findings or the report.\n\nIf the caller is a coaching skill (`prfaq-beagle`, `brainstorm-beagle`), the coaching happens before and after this skill runs. Inside this skill, the intent is treated as final.\n\n## Out of scope\n\n- Scanning paywalled or authentication-gated remote sources. Use the file tools to extract content first, then pass paths in.\n- LLM-as-judge evaluation of document quality or claim credibility. Use `llm-judge`.\n- Coaching, challenge, or opinionated reshaping of the intent.\n- Rewriting or editing the scanned documents. Read-only by design.\n- Binary / image OCR, PDF text extraction, or format conversion. First version reads plain text and markdown only; `beagle-core:docling` is the future path.\n- Multi-language analysis. English-only today.\n- Caching or re-use of prior findings across invocations.\n- Long-running or scheduled scans.\n\n## Reference files\n\n- `references/subagent-brief.md` — template the orchestrator mechanically fills from `plan.md` when dispatching each subagent.\n- `references/citation-schema.md` — required and optional citation fields, footnote convention, and a well-formed example.\n- `references/report-template.md` — literal `report.md` skeleton with all seven fixed sections.\n- `references/failure-modes.md` — partial-success, empty-corpus, silent-failure detection, and re-run protection rules.\n- `references/companion-contract.md` — programmatic invocation shape with worked examples for `prfaq-beagle`, `brainstorm-beagle`, and `strategy-interview`.\n- `references/skip-patterns.md` — default denylist (sensitive, binary/media, vendor/build) applied to every run.\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn79190nfmdb20hk6xjhzt2zv583844x\",\n  \"slug\": \"artifact-analysis\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1776830997803\n}\n\nFile v1.0.0:references/citation-schema.md\n\n# Citation Schema\n\nEvery claim in a findings file and in `report.md` carries a citation. The shape is small on purpose — enough metadata to verify without re-reading the full document, not so much that subagents start fabricating fields.\n\n## Required fields\n\n- **`path`** — the document the claim was drawn from. Relative to the scanned root when possible (e.g. `docs/architecture.md`); absolute only when the path lives outside the scanned tree.\n- **`excerpt`** — a verbatim quoted string from the document that supports the claim. Keep it short enough to read at a glance (typically 1-3 sentences), long enough to stand on its own.\n\nIf either required field is missing or would have to be fabricated, do not include the citation. Drop the claim or mark it as unverified in `Gaps & Limitations`.\n\n## Optional fields\n\nInclude only when the subagent naturally has them. Never synthesize.\n\n- **`lines`** — line range (`L42-L58`) or single line (`L42`) where the excerpt appears. Include when reading a text/markdown file with stable line numbers. Omit for documents where line granularity is ambiguous (prose documents without visible line numbers, transcluded markdown, rendered output). Never guess.\n- **`heading`** — the nearest enclosing heading, copied verbatim. Useful for anchoring the reader in long documents.\n- **`document_type`** — one of:\n  - `spec` — specification, requirements doc, or formal brief.\n  - `adr` — architecture decision record.\n  - `readme` — README, overview, or project-root context doc.\n  - `planning` — roadmap, state, phase, or plan artifact.\n  - `concept` — beagle concept spec or analysis.\n  - `transcript` — meeting notes, interview transcript, or chat log.\n  - `other` — anything that does not fit.\n\nOmit fields you do not have. An incomplete citation with two real fields beats a five-field citation with three guessed values.\n\n## Footnote convention\n\nIn findings and in `report.md`, claims use `[^n]` inline footnote markers:\n\n```markdown\nThe skill must not pause for user confirmation before spawning subagents[^3].\n```\n\nThe numbered `Sources` section at the bottom of `report.md` lists each citation in order, matching the footnote number. Numbering is global across the report, not per-section.\n\n## Example — well-formed citation block\n\nIn `report.md`, the `Sources` section entries look like this:\n\n```markdown\n[^1]: **Path**: .beagle/concepts/artifact-analysis/spec.md\n      **Excerpt**: \"Partial-success behavior: if a subagent fails, the skill continues with the remaining findings and records the failure explicitly under Gaps & Limitations.\"\n      **Lines**: L29\n      **Heading**: Requirements\n      **Document type**: spec\n\n[^2]: **Path**: docs/architecture.md\n      **Excerpt**: \"All long-running jobs run on the worker queue, never the request thread.\"\n      **Heading**: Background Processing\n      **Document type**: readme\n```\n\nCitation `[^2]` omits `Lines` because the subagent did not have a stable line-number anchor. That is correct behavior — omit rather than guess.\n\n## Incomplete-metadata policy\n\nIf a claim is genuinely load-bearing but the document lacks a clear line number or heading, keep the citation with the required fields (`path` + `excerpt`) only. Do not invent a line number to satisfy a schema slot. If the absence makes the claim hard to verify, note the uncertainty in `Gaps & Limitations` rather than citing confidently.\n\nFile v1.0.0:references/companion-contract.md\n\n# Companion Invocation Contract\n\nOther beagle skills invoke `artifact-analysis` via this contract. It is small on purpose — no required inputs (!), three optional parameters for scoping and one for overwrite control, two return shapes.\n\nCallers are expected to honor the contract verbatim rather than invent parallel invocation styles. If a new caller needs behavior that the contract does not support, extend the contract here first, not in the calling skill.\n\n## Minimal call\n\n```yaml\n# No parameters at all — auto-discover every beagle knowledge location, generic-salient-extraction mode.\n```\n\nWith no inputs, the skill scans `.beagle/concepts/`, `.planning/`, `docs/`, and top-level README/brief/overview files, applies the default skip denylist, and extracts anything structurally important. Output lands at `.beagle/analysis/<YYYY-MM-DD>-<first-path-basename>/`.\n\n## Full call\n\n```yaml\nintent: \"competitive and technical grounding for PRFAQ on AI coding-assistant pricing\"\npaths:\n  - .beagle/concepts/ai-coding-pricing/\n  - docs/\noutput_dir: \"/abs/path/.beagle/concepts/ai-coding-pricing/analysis/\"\nrefresh: false\n```\n\n## Input semantics\n\n- **`intent`** — one string describing what the caller wants. When present, extraction is weighted toward relevance to the intent. When absent, the skill runs in generic-salient-extraction mode. Tone-neutral; the skill does not reshape the intent.\n- **`paths`** — directories and/or explicit files. When absent or empty, the skill auto-discovers beagle's conventional knowledge locations (see SKILL.md §Auto-discovery). When present, only the listed paths are scanned — auto-discovery does not run.\n- **`output_dir`** — absolute path. Callers embedding artifact-analysis in their own concept folder (e.g. `prfaq-beagle`) pass this explicitly so the analysis sits next to its consumer.\n- **`refresh`** — when `true`, a prior run in `output_dir` is archived to `<output_dir>/.archive-<timestamp>/` before the new run starts. See `failure-modes.md` for the archive rule.\n\n## Return shapes\n\nThis skill returns one of two shapes. Callers that invoke multiple beagle companions should handle the union of error codes across all companions they call — sibling companions (e.g. `web-research`) may return different error codes (notably `web-tools-unavailable`).\n\n- **success** — artifacts written. An empty-corpus run still returns this shape with a minimal `report.md`; the caller detects empty-corpus by reading the report, not by catching an error.\n- **error: `prior-run-present`** — `output_dir` already holds a prior run and `refresh` is false; nothing written.\n\n### Success\n\n```yaml\nplan: \"<output_dir>/plan.md\"\nreport: \"<output_dir>/report.md\"\nfindings_dir: \"<output_dir>/findings/\"\n```\n\nThe caller receives absolute paths. All evidence lives on disk — nothing returns inline.\n\n### Success with empty corpus\n\nEmpty-corpus is **not** an error. When path resolution yields zero readable documents, the skill still returns the Success shape above: `plan.md` exists (with an empty `Resolved paths` list), `report.md` exists (with every section present plus a `Gaps & Limitations` entry explaining no readable documents were found), and `findings_dir` exists (empty). Callers detect empty-corpus by reading `report.md`, not by catching an error.\n\n### Refused (prior run present, no refresh)\n\n```yaml\nerror: \"prior-run-present\"\ndetail: \"<output_dir> already contains plan.md or report.md. Pass refresh: true to archive and overwrite.\"\n```\n\nThe caller decides whether to retry with `refresh: true`, pick a different `output_dir`, or surface the refusal to its user.\n\n## Worked examples\n\n### `prfaq-beagle` — Ignition grounding\n\nThe PRFAQ's Ignition phase needs competitive and technical grounding from the user's own documents (PRDs, briefs, prior decisions). PRFAQ passes:\n\n```yaml\nintent: \"competitive and technical grounding for PRFAQ on AI coding-assistant pricing\"\npaths: []  # empty → auto-discover .beagle/concepts/, .planning/, docs/\noutput_dir: \"/abs/path/.beagle/concepts/ai-coding-pricing/analysis/\"\nrefresh: false\n```\n\nEmpty `paths` triggers auto-discovery so PRFAQ does not have to know where the user keeps briefs. `output_dir` lands inside the PRFAQ concept folder so the audit trail travels with the concept.\n\n### `brainstorm-beagle` — reference-point grounding\n\nMid-brainstorm, the user says \"go read the docs folder and tell me what we already decided.\" Brainstorm calls:\n\n```yaml\nintent: \"prior decisions and reference points relevant to the current idea\"\npaths:\n  - docs/\n  - .beagle/concepts/\noutput_dir: \"/abs/path/.beagle/concepts/task-sub-tasks/analysis/\"\nrefresh: false\n```\n\nExplicit `paths` keeps the scan narrow. `output_dir` lands inside the brainstorm concept folder so the reference points can link straight to `report.md`.\n\n### `strategy-interview` — context grounding\n\nDuring strategy interview Phase 1 discovery, the user needs a structured read of prior strategy artifacts. Strategy-interview calls:\n\n```yaml\nintent: \"background context for platform-team H1 2026 strategy discovery\"\npaths:\n  - .beagle/strategy/\n  - docs/\noutput_dir: \"/abs/path/.beagle/strategy/platform-team-h1-2026/analysis/\"\nrefresh: false\n```\n\n`output_dir` lands inside the strategy interview's working-state folder so the analysis sits alongside `state.md`, `evidence.md`, and `composition.md`.\n\n### Standalone user — \"analyze these docs\"\n\nA user types \"read everything in docs/ and tell me what's there\" with no prior context. The skill is triggered directly and runs:\n\n```yaml\n# Triggered by user chatter. No intent passed → generic-salient-extraction mode.\npaths:\n  - docs/\n# output_dir defaults to .beagle/analysis/<YYYY-MM-DD>-docs/\n```\n\nThe user gets a `report.md` they can open immediately — no caller-specific wrapping.\n\n## Non-obligations\n\nThe contract is explicit about what this skill does **not** do:\n\n- **No intent reshaping.** The caller hands in an intent (or nothing). The skill does not argue with it, sharpen it, or reframe it.\n- **No coaching posture.** `artifact-analysis` is tone-neutral. Callers that need a coaching tone (`prfaq-beagle`'s hardcore coach, `brainstorm-beagle`'s thinking partner) apply that tone before and after, not inside.\n- **No inline findings.** Every deliverable is a file. Callers that want inline prose should summarize from `report.md` themselves.\n- **No cross-run caching.** Each invocation stands alone. Callers that need caching build it themselves at the call site.\n- **No doc editing or rewriting.** Read-only by design.\n\n## Extending the contract\n\nIf a new caller needs behavior not covered here, add a field to the input table in SKILL.md first, document it in this file with a worked example, then update caller skills to use it. Parallel-invocation styles fragment the contract and re-introduce the reason this skill exists.\n\nFile v1.0.0:references/failure-modes.md\n\n# Failure Modes\n\nFour failure cases the skill handles explicitly. Silent failures are the worst kind — every rule below exists to make a failure visible to the caller and preserve what succeeded.\n\nUnlike `web-research`, artifact-analysis does **not** fail-fast on missing tools. Filesystem tooling (Read, Glob, Grep) is assumed present in the Claude Code environment. If it is somehow absent, that surfaces as a per-subagent failure under partial-success rather than aborting the whole run.\n\n## Partial success\n\nOne or more subagents fail; others return valid findings.\n\n**Behavior:** continue with the successful findings. Do not abort the run.\n\nIn `report.md`, under `Gaps & Limitations`, enumerate every failed slice:\n\n- Name the slice.\n- Include the subagent's last-known brief (or a one-line summary of what it was asked to scan).\n- Include the `reason` line from the stub findings file (see \"Silent-failure detection\" below).\n\nExample:\n\n```markdown\n## Gaps & Limitations\n\n- **Slice \"planning-folder\"** (status: failed) — subagent returned \"Read timeout on .planning/phase-3/PLAN.md after 3 retries\". Caller may retry this slice alone, or re-run with `refresh: true` after investigating the file.\n```\n\n## Empty corpus\n\nPath resolution (auto-discovery + explicit paths) yields zero readable documents after the skip denylist is applied.\n\n**Behavior:** do not spawn subagents. Return cleanly.\n\nThe skill writes:\n\n- `plan.md` with an empty `Resolved paths` list and a note that no readable documents were found.\n- `report.md` with every section present but containing a single bullet each, plus a `Gaps & Limitations` entry:\n\n```markdown\n## Gaps & Limitations\n\n- No readable documents found under the resolved paths. The caller passed <paths> and auto-discovery surfaced <auto-discovered paths>; every entry was either absent, empty, or matched the skip denylist. Pass a broader `paths` list, or point at a different folder.\n```\n\nReturning cleanly lets callers handle \"no documents found\" gracefully (e.g. fall back to asking the user to paste content) rather than crashing on an expected-but-uncommon state.\n\n## Silent-failure detection (stub-file rule)\n\nContext exhaustion and tool errors can cause a subagent to return without producing any output file. The orchestrator has no way to distinguish that from \"the subagent finished but the file is missing for some other reason\" — so the contract requires every subagent to write at least a stub file before returning.\n\n**Contract (enforced by `subagent-brief.md`):**\n\n- Every subagent writes `findings/<slice-slug>.md` with a `status:` frontmatter field: `ok`, `empty`, or `failed`.\n- On `empty` or `failed`, the file includes a one-line `reason:` field.\n- On `ok`, `reason` is omitted.\n\n**Orchestrator check, post-dispatch:**\n\nFor every expected slice, test that the findings file exists. For any missing file, record a silent-failure entry under `Gaps & Limitations`:\n\n```markdown\n- **Slice \"<name>\"** — subagent returned without producing a findings file (likely context exhaustion or tool error). Last known brief: \"<brief summary>\".\n```\n\nThis is why \"legitimately empty\" results must use `status: empty` with a reason rather than writing nothing — so empty-but-ok is never confused with silent context loss.\n\n## Re-run protection\n\nEach run is supposed to be self-contained and auditable. Silently overwriting a prior run destroys the audit trail; silently appending produces incoherent findings.\n\n**Rule:** before writing anything to `output_dir`, check whether it already contains `plan.md` or `report.md`.\n\n- **If it does and `refresh` is not `true`:** refuse with a message naming the existing folder.\n\n  ```\n  Refusing to write: <output_dir> already contains a prior analysis run. Pass `refresh: true` to archive and overwrite, or choose a different output_dir.\n  ```\n\n- **If it does and `refresh: true`:** move the existing contents to `<output_dir>/.archive-<YYYYMMDD-HHMMSS>/` first, then proceed with a fresh run. The archive preserves the audit trail.\n\n- **If it does not:** proceed normally.\n\nThis rule applies even when the default slug matches a prior run on the same day — stable slugs are a feature (callers can re-derive the folder), but the user must explicitly opt in to overwriting.\n\n## Verification checklist (orchestrator runs at end)\n\nBefore returning success to the caller, verify:\n\n- [ ] `plan.md` exists at `<output_dir>/plan.md`.\n- [ ] `findings/<slice-slug>.md` exists for every slice in `plan.md` (unless the empty-corpus path was taken).\n- [ ] Every findings file has `status:` frontmatter.\n- [ ] Every `status: empty` or `status: failed` file has a `reason:` line.\n- [ ] `report.md` exists at `<output_dir>/report.md`.\n- [ ] `report.md` has all seven top-level sections in order: `Documents Found`, `Key Insights`, `User / Market Context`, `Technical Context`, `Ideas & Decisions`, `Raw Detail Worth Preserving`, `Gaps & Limitations`.\n- [ ] `report.md` has a `Sources` section and every `[^n]` footnote in the body has a matching entry.\n\nAny check that fails becomes an entry in `Gaps & Limitations` — the run does not silently produce a broken deliverable.\n\nFile v1.0.0:references/report-template.md\n\n# Synthesis Skeleton\n\nThe synthesis document, saved as `report.md` under the run's output directory, uses a fixed seven-section layout. Sections appear in this order, every time, even when one is short. `Gaps & Limitations` is required even when findings look complete — honest accounting of what could not be established is part of the product.\n\nCopy the skeleton below into the synthesis file and fill each section.\n\n## Layout\n\n```markdown\n# Analysis: <intent, verbatim from plan.md — or \"Generic extraction of <slug>\" when intent is absent>\n\n## Documents Found\n\n- `<relative path 1>` — <one-line note on what this document covers and why it was included>\n- `<relative path 2>` — <...>\n- `<relative path N>` — <...>\n\nInclude every path that was actually scanned (end-to-end or skimmed). Paths that were under the skip denylist go in `Gaps & Limitations`, not here.\n\n## Key Insights\n\nGroup by theme. Every claim carries a [^n] footnote.\n\n### <Theme 1>\n\n<Bullets or short paragraphs. Each factual claim has a footnote.>\n\n### <Theme 2>\n\n<...>\n\n### <Theme N>\n\n<...>\n\n## User / Market Context\n\n<Users, customers, competition, market data surfaced from the documents. Footnote every specific claim. If the corpus does not contain user/market content, write a single bullet: \"No user/market content surfaced by this scan.\" — do not delete the section.>\n\n## Technical Context\n\n<Platforms, constraints, integrations, dependencies, operational considerations. Footnote every specific claim. If the corpus does not contain technical content, write a single bullet noting so — do not delete the section.>\n\n## Ideas & Decisions\n\nEvery idea carries a tag — `accepted`, `rejected`, or `open` — and rationale. Preserve rejected ideas so future work does not re-propose them.\n\n- **[accepted]** <idea> — <rationale from the document> [^n]\n- **[rejected]** <idea> — <rationale for rejection> [^n]\n- **[open]** <idea> — <what is still undecided> [^n]\n\n## Raw Detail Worth Preserving\n\nSpecific quotes, metrics, and data points that would be lost to summarization. Each entry is a verbatim excerpt (or near-verbatim with explicit ellipsis) plus a footnote.\n\n- \"<quote>\" [^n]\n- \"<data point>\" [^n]\n\n## Gaps & Limitations\n\n- <What the corpus could not establish, and why. One bullet per gap.>\n- <Any path that was empty, unreadable, or skipped via the denylist — name the path and the reason.>\n- <Any subagent that failed or returned empty — name the slice and the reason from its stub file.>\n- <Claims that were dropped because the citation would have had to be fabricated.>\n\nThis section is never empty. If the scan was clean, include at minimum a bullet naming what follow-up reading would sharpen the picture.\n\n## Sources\n\n[^1]: **Path**: <relative path>\n      **Excerpt**: \"<verbatim quote>\"\n      **Lines**: <optional, omit if absent>\n      **Heading**: <optional, omit if absent>\n      **Document type**: <optional, omit if absent>\n\n[^2]: **Path**: <...>\n      **Excerpt**: \"<...>\"\n\n[^n]: <...>\n```\n\n## Rules\n\n- **Title line** uses the intent verbatim from `plan.md`. When intent is absent, use `Generic extraction of <slug>`.\n- **`Documents Found`** lists every included path (read or skimmed). Skipped paths go in `Gaps & Limitations`.\n- **`Key Insights`** groups by theme, not by source document. If one theme only came from one document, that is fine — one bullet, one footnote.\n- **`User / Market Context`, `Technical Context`, `Raw Detail Worth Preserving`** — never delete these sections. If the corpus has nothing to say, include a single bullet saying so. Prefer `\"No <section> content surfaced by this scan.\"` over synthesized content — an empty placeholder is correct when the corpus is thin; fabricated content is not.\n- **`Ideas & Decisions`** preserves rejected ideas with the rationale for rejection, not just accepted ones. This is the feature, not a nice-to-have.\n- **`Gaps & Limitations`** is never empty. At minimum, name what follow-up reading would sharpen the answer.\n- **`Sources`** uses global numbering — `[^1]` through `[^n]` across the whole document, not per-section. Citation shape per `citation-schema.md`.\n\n## Sourcing discipline\n\n- Every bullet in `Key Insights`, `User / Market Context`, `Technical Context`, and `Ideas & Decisions` that makes a specific factual claim carries a footnote. Broad synthesis statements can stand without a footnote only if they summarize cited claims elsewhere in the document.\n- `Raw Detail Worth Preserving` is 100% cited — every entry is an excerpt with a footnote.\n- If a claim cannot be cited, either drop it or move it to `Gaps & Limitations` as something the corpus did not establish.\n- `Sources` entries match every `[^n]` used in the body. Orphan citations (listed in `Sources` but never referenced) should be removed.\n\nFile v1.0.0:references/skip-patterns.md\n\n# Default Skip Patterns\n\nThe subagent's default denylist. Applied without the caller re-specifying. Every skipped path is recorded under the `paths_skipped` frontmatter field so the audit trail shows exactly what was excluded.\n\nThree groups: sensitive, binary/media, vendor/build.\n\n## Sensitive\n\nSecrets, credentials, and user-level config. Never scanned.\n\n- `.env`, `.env.*`\n- `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.crt`, `*.cer`\n- `.aws/`, `.ssh/`, `.gnupg/`\n- `credentials.*`, `secrets.*`\n- `*.htpasswd`, `*.netrc`\n\n## Binary / media\n\nFormats the first version does not parse. Passed over without an error. `beagle-core:docling` is the future path for richer parsing (PDF / DOCX / PPTX) when a caller needs it.\n\n- Images: `*.png`, `*.jpg`, `*.jpeg`, `*.gif`, `*.webp`, `*.ico`, `*.svg`, `*.bmp`, `*.tiff`\n- Documents: `*.pdf`, `*.docx`, `*.doc`, `*.pptx`, `*.ppt`, `*.xlsx`, `*.xls`\n- Archives: `*.zip`, `*.tar`, `*.tar.gz`, `*.tgz`, `*.gz`, `*.bz2`, `*.xz`, `*.7z`, `*.rar`\n- Audio/video: `*.mp3`, `*.wav`, `*.flac`, `*.ogg`, `*.mp4`, `*.mov`, `*.mkv`, `*.avi`, `*.webm`\n- Databases: `*.sqlite`, `*.sqlite3`, `*.db`\n- Binaries: `*.exe`, `*.dll`, `*.so`, `*.dylib`, `*.a`, `*.o`, `*.class`, `*.jar`\n\n## Vendor / build\n\nGenerated output and vendored dependencies. Noise, not signal.\n\n- `.git/`\n- `node_modules/`\n- `.venv/`, `venv/`, `env/`\n- `__pycache__/`, `*.pyc`\n- `dist/`, `build/`, `out/`, `target/`\n- `coverage/`, `.coverage`\n- `.next/`, `.nuxt/`, `.svelte-kit/`\n- `.cache/`, `.parcel-cache/`\n- `vendor/`, `Pods/`\n- `.DS_Store`, `Thumbs.db`\n\n## Rules\n\n- **Silent skip, audited record.** Subagents do not stop to explain why a path was skipped. Every skipped path lands in `paths_skipped`.\n- **Case-insensitive extension matching.** `.ENV` is skipped just like `.env`.\n- **Directory patterns match as prefixes.** `node_modules/` skips everything under it.\n- **No runtime extension.** The denylist is read-only during a run. A caller that wants to scan a normally-skipped path passes it explicitly in `paths` — the brief records it, and the subagent reads it. (Explicit caller intent overrides the default.)\n- **Sensitive list is non-overridable.** `.env`, `*.pem`, `*.key`, and credential files are always skipped even when explicitly passed. If a caller needs those contents, they paste them in directly rather than routing through this skill.\n\nFile v1.0.0:references/subagent-brief.md\n\n# Subagent Brief Template\n\nThe orchestrator builds one brief per slice, mechanically, from `plan.md`. Every subagent gets the same shape so a caller reading `plan.md` can predict what each subagent was told.\n\nFill the template verbatim — no paraphrasing, no interpretation drift. Subagents return one terse status line to the orchestrator; all findings land in the output file.\n\n## Template\n\n```\nYou are one of up to 3 parallel artifact-analysis subagents. Scan a single slice of paths and write findings to disk.\n\nSlice: <slice name, copied from plan.md>\nIntent: <intent string, verbatim from plan.md — or \"generic salient extraction\" if absent>\nPaths to scan:\n  - <path 1 from plan.md for this slice>\n  - <path 2 from plan.md for this slice>\n  - <...>\n\nWhat to extract:\n  - Key insights — structurally important observations, decisions, and themes\n  - User / market context — users, customers, competition, market data\n  - Technical context — platforms, constraints, integrations, dependencies\n  - Ideas & decisions — tagged accepted / rejected / open (preserve rejected ideas with rationale)\n  - Raw detail worth preserving — specific quotes, metrics, and data points\n  - Gaps — what the corpus could not establish; empty/unreadable paths\n\n  When intent is present, weight extraction toward what is relevant to that intent. When intent is absent, extract anything structurally important without an interpretive filter.\n\nSkim strategy:\n  - Sharded documents (folder with index.md plus multiple files): read index.md first, then only the sub-files the index points to as relevant.\n  - Large documents (single file > ~2000 lines or > ~50 pages): read the TOC, executive summary, and section headings first; pull full content only from relevant sections. Record skimmed-vs-read status per file.\n  - Short documents: read end-to-end.\n\nSkip patterns: apply the default denylist from references/skip-patterns.md (sensitive, binary/media, vendor/build). Record every skipped path under the paths_skipped frontmatter field.\n\nOutput path: <output_dir>/findings/<slice-slug>.md\n\nCitation rules: every claim carries a [^n] footnote. Citations use source path (relative to the scanned root when possible) + verbatim excerpt. Include lines and heading only when the subagent naturally has them; never synthesized or guessed. See references/citation-schema.md for the full shape.\n\nRequired frontmatter on the output file:\n---\nstatus: ok | empty | failed\nslice: <slice name>\nbrief_hash: <hash of this brief, supplied by the orchestrator>\nstarted_at: <ISO timestamp>\nfinished_at: <ISO timestamp>\npaths_read: [<paths read end-to-end>]\npaths_skimmed: [<paths where only TOC/index/headings were consumed>]\npaths_skipped: [<paths skipped via the default denylist>]\nreason: <one line — required when status is empty or failed, omit otherwise>\n---\n\nPartial-failure protocol: always write the output file, even if the subagent fails or finds nothing. Use status: failed with a one-line reason on tool errors or exhaustion. Use status: empty with a reason when the slice is legitimately empty (\"all paths under this slice were under the skip denylist\" or \"all files were unreadable\"). Never exit without writing the file — absence of the file is treated as a silent failure.\n\nReturn: a single status line in this exact shape, and nothing else:\n<path-to-findings-file> <status>\n\nExample: /abs/path/findings/planning-folder.md ok\n```\n\n## Orchestrator responsibilities\n\n- **Build `<slice-slug>`** by the same rule as the run slug in SKILL.md (lowercase, punctuation stripped, whitespace → hyphens, truncated to 60 chars on a word boundary). Keep it stable across runs so `refresh: true` can match archived prior files.\n- **Compute `brief_hash`** over the filled-in brief text before dispatch so the findings file's provenance is verifiable.\n- **Guarantee non-overlapping slices.** The orchestrator partitions resolved paths before building briefs; no path appears in more than one slice.\n- **Verify every expected file exists** after all subagents return. Any missing file = silent failure per `failure-modes.md`.\n- **Never merge findings into one file.** Synthesis happens later, in `report.md`.\n\n## Subagent responsibilities\n\n- **Write the output file even on failure.** Absence is treated as silent context exhaustion.\n- **Do not reshape the intent or the slice.** If the brief is wrong, flag it in `reason` and return `status: failed` — do not silently pivot to a different scope.\n- **Apply skim strategies.** Do not read a 2000-line file end-to-end when the TOC tells you only three sections are relevant. Record the skim/read decision in the frontmatter path lists.\n- **Apply skip patterns silently.** Every skipped path goes in `paths_skipped` — no need to note it in the findings body.\n- **No inline returns.** The only thing that crosses back to the orchestrator is the status line. All evidence lives in the findings file.\n\nFile v1.0.0:skill-card.md\n\n## Description: <br>\nArtifact Analysis turns local paths or conventional project knowledge folders into an auditable, citation-backed document analysis with a scan plan, per-slice findings, and a synthesized report written to disk. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[anderskev](https://clawhub.ai/user/anderskev) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and project teams use this skill to scan local markdown and plain-text project documents, extract structurally important context, and produce path-cited analysis artifacts for later review or companion-skill grounding. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill reads local document paths supplied by the caller, or default project documentation locations when no paths are supplied. <br>\nMitigation: Use narrow path scopes for private projects and review the resolved paths in plan.md. <br>\nRisk: Using refresh:true archives and replaces a prior analysis run in the selected output directory. <br>\nMitigation: Choose an output_dir inside the project and use refresh:true only when intentionally replacing a prior run. <br>\n\n\n## Reference(s): <br>\n- [Artifact Analysis Skill](https://clawhub.ai/anderskev/artifact-analysis) <br>\n- [Citation Schema](references/citation-schema.md) <br>\n- [Companion Invocation Contract](references/companion-contract.md) <br>\n- [Failure Modes](references/failure-modes.md) <br>\n- [Synthesis Skeleton](references/report-template.md) <br>\n- [Default Skip Patterns](references/skip-patterns.md) <br>\n- [Subagent Brief Template](references/subagent-brief.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, guidance] <br>\n**Output Format:** [Markdown files on disk: plan.md, findings markdown, and report.md with citations.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Reads local text and markdown paths, applies skip patterns, and records gaps and limitations in the report.] <br>\n\n## Skill Version(s): <br>\n1.0.0 (source: server-resolved release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>","readmeExcerpt":"Skill: Artifact Analysis Owner: anderskev Summary: 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\",... Tags: latest:1.0.1 Version history: v1.0.1 | 2026-06-01T02:21:44.440Z | auto artifact-analysis 1.0.1 - Improved compatibility: Workflow now supports sequential slice processing if subagents are unavailable, en","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Receive paths + optional intent ──→ Auto-discover if paths empty\n                                   ↓\n                                 Write plan.md (no user-confirmation pause)\n                                   ↓\n                                 Dispatch subagents (up to 3 parallel)\n                                   ↓\n                                 Collect findings/<slice>.md files\n                                   ↓\n                                 Synthesize report.md\n                                   ↓\n                                 Return paths to caller"},{"language":"text","snippet":".beagle/analysis/<slug>/"},{"language":"markdown","snippet":"The skill must not pause for user confirmation before spawning subagents[^3]."},{"language":"markdown","snippet":"[^1]: **Path**: .beagle/concepts/artifact-analysis/spec.md\n      **Excerpt**: \"Partial-success behavior: if a subagent fails, the skill continues with the remaining findings and records the failure explicitly under Gaps & Limitations.\"\n      **Lines**: L29\n      **Heading**: Requirements\n      **Document type**: spec\n\n[^2]: **Path**: docs/architecture.md\n      **Excerpt**: \"All long-running jobs run on the worker queue, never the request thread.\"\n      **Heading**: Background Processing\n      **Document type**: readme"},{"language":"yaml","snippet":"# No parameters at all — auto-discover every beagle knowledge location, generic-salient-extraction mode."},{"language":"yaml","snippet":"intent: \"competitive and technical grounding for PRFAQ on AI coding-assistant pricing\"\npaths:\n  - .beagle/concepts/ai-coding-pricing/\n  - docs/\noutput_dir: \"/abs/path/.beagle/concepts/ai-coding-pricing/analysis/\"\nrefresh: false"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: artifact-analysis\ndescription: \"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.\"\n---\n\n# Artifact Analysis\n\nTurn 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.\n\nThe 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.\n\n## When to use\n\n- A user asks for a local-document read — \"analyze the docs folder\", \"scan the project for context\", \"extract what's in .beagle/concepts/\".\n- Another beagle skill invokes this one programmatically as a grounding companion (see `references/companion-contract.md`).\n- The caller wants auditable output: a plan written before extraction, findings files per slice, and a citation-backed synthesis report.\n\n## When NOT to use\n\n- Codebase lookups (\"where is this function defined\", \"grep for this symbol\"). Search the codebase instead.\n- Web research. Use [web-research](../web-research/SKILL.md).\n- Comparative evaluation of two implementations or source credibility adjudication. Use [llm-judge](../llm-judge/SKILL.md).\n- 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.\n- PDF / image OCR / format conversion. First version reads plain text and markdown only.\n- Paywalled or authentication-gated remote sources. This is a local-filesystem primitive.\n- Coaching, challenge, or reshaping of the caller's question. That belongs to the caller.\n\n## Workflow\n\nFour steps, in order. No step is skippable.\n\n### Hard gates\n\nAdvance to the next step only when the **pass condition** is true—confirm using files under `output_dir` (and tool output), not memory.\n\n| After | Pass condition |\n| --- | --- |\n| `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 "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn79190nfmdb20hk6xjhzt2zv583844x\",\n  \"slug\": \"artifact-analysis\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1780280504440\n}"},{"path":"references/citation-schema.md","content":"# Citation Schema\n\nEvery claim in a findings file and in `report.md` carries a citation. The shape is small on purpose — enough metadata to verify without re-reading the full document, not so much that subagents start fabricating fields.\n\n## Required fields\n\n- **`path`** — the document the claim was drawn from. Relative to the scanned root when possible (e.g. `docs/architecture.md`); absolute only when the path lives outside the scanned tree.\n- **`excerpt`** — a verbatim quoted string from the document that supports the claim. Keep it short enough to read at a glance (typically 1-3 sentences), long enough to stand on its own.\n\nIf either required field is missing or would have to be fabricated, do not include the citation. Drop the claim or mark it as unverified in `Gaps & Limitations`.\n\n## Optional fields\n\nInclude only when the subagent naturally has them. Never synthesize.\n\n- **`lines`** — line range (`L42-L58`) or single line (`L42`) where the excerpt appears. Include when reading a text/markdown file with stable line numbers. Omit for documents where line granularity is ambiguous (prose documents without visible line numbers, transcluded markdown, rendered output). Never guess.\n- **`heading`** — the nearest enclosing heading, copied verbatim. Useful for anchoring the reader in long documents.\n- **`document_type`** — one of:\n  - `spec` — specification, requirements doc, or formal brief.\n  - `adr` — architecture decision record.\n  - `readme` — README, overview, or project-root context doc.\n  - `planning` — roadmap, state, phase, or plan artifact.\n  - `concept` — beagle concept spec or analysis.\n  - `transcript` — meeting notes, interview transcript, or chat log.\n  - `other` — anything that does not fit.\n\nOmit fields you do not have. An incomplete citation with two real fields beats a five-field citation with three guessed values.\n\n## Footnote convention\n\nIn findings and in `report.md`, claims use `[^n]` inline footnote markers:\n\n```markdown\nThe skill must not pause for user confirmation before spawning subagents[^3].\n```\n\nThe numbered `Sources` section at the bottom of `report.md` lists each citation in order, matching the footnote number. Numbering is global across the report, not per-section.\n\n## Example — well-formed citation block\n\nIn `report.md`, the `Sources` section entries look like this:\n\n```markdown\n[^1]: **Path**: .beagle/concepts/artifact-analysis/spec.md\n      **Excerpt**: \"Partial-success behavior: if a subagent fails, the skill continues with the remaining findings and records the failure explicitly under Gaps & Limitations.\"\n      **Lines**: L29\n      **Heading**: Requirements\n      **Document type**: spec\n\n[^2]: **Path**: docs/architecture.md\n      **Excerpt**: \"All long-running jobs run on the worker queue, never the request thread.\"\n      **Heading**: Background Processing\n      **Document type**: readme\n```\n\nCitation `[^2]` omits `Lines` because the subagent did not have a stable line-number anchor. That is correct behavior —"},{"path":"references/companion-contract.md","content":"# Companion Invocation Contract\n\nOther beagle skills invoke `artifact-analysis` via this contract. It is small on purpose — no required inputs (!), three optional parameters for scoping and one for overwrite control, two return shapes.\n\nCallers are expected to honor the contract verbatim rather than invent parallel invocation styles. If a new caller needs behavior that the contract does not support, extend the contract here first, not in the calling skill.\n\n## Minimal call\n\n```yaml\n# No parameters at all — auto-discover every beagle knowledge location, generic-salient-extraction mode.\n```\n\nWith no inputs, the skill scans `.beagle/concepts/`, `.planning/`, `docs/`, and top-level README/brief/overview files, applies the default skip denylist, and extracts anything structurally important. Output lands at `.beagle/analysis/<YYYY-MM-DD>-<first-path-basename>/`.\n\n## Full call\n\n```yaml\nintent: \"competitive and technical grounding for PRFAQ on AI coding-assistant pricing\"\npaths:\n  - .beagle/concepts/ai-coding-pricing/\n  - docs/\noutput_dir: \"/abs/path/.beagle/concepts/ai-coding-pricing/analysis/\"\nrefresh: false\n```\n\n## Input semantics\n\n- **`intent`** — one string describing what the caller wants. When present, extraction is weighted toward relevance to the intent. When absent, the skill runs in generic-salient-extraction mode. Tone-neutral; the skill does not reshape the intent.\n- **`paths`** — directories and/or explicit files. When absent or empty, the skill auto-discovers beagle's conventional knowledge locations (see SKILL.md §Auto-discovery). When present, only the listed paths are scanned — auto-discovery does not run.\n- **`output_dir`** — absolute path. Callers embedding artifact-analysis in their own concept folder (e.g. `prfaq-beagle`) pass this explicitly so the analysis sits next to its consumer.\n- **`refresh`** — when `true`, a prior run in `output_dir` is archived to `<output_dir>/.archive-<timestamp>/` before the new run starts. See `failure-modes.md` for the archive rule.\n\n## Return shapes\n\nThis skill returns one of two shapes. Callers that invoke multiple beagle companions should handle the union of error codes across all companions they call — sibling companions (e.g. `web-research`) may return different error codes (notably `web-tools-unavailable`).\n\n- **success** — artifacts written. An empty-corpus run still returns this shape with a minimal `report.md`; the caller detects empty-corpus by reading the report, not by catching an error.\n- **error: `prior-run-present`** — `output_dir` already holds a prior run and `refresh` is false; nothing written.\n\n### Success\n\n```yaml\nplan: \"<output_dir>/plan.md\"\nreport: \"<output_dir>/report.md\"\nfindings_dir: \"<output_dir>/findings/\"\n```\n\nThe caller receives absolute paths. All evidence lives on disk — nothing returns inline.\n\n### Success with empty corpus\n\nEmpty-corpus is **not** an error. When path resolution yields zero readable documents, the skill still returns the Success shape above: `plan.md` e"},{"path":"references/failure-modes.md","content":"# Failure Modes\n\nFour failure cases the skill handles explicitly. Silent failures are the worst kind — every rule below exists to make a failure visible to the caller and preserve what succeeded.\n\nUnlike web-research, artifact-analysis does **not** fail-fast on missing tools. Filesystem search (read, glob, grep) is assumed present in the agent's environment. If it is somehow absent, that surfaces as a per-subagent failure under partial-success rather than aborting the whole run.\n\n## Partial success\n\nOne or more subagents fail; others return valid findings.\n\n**Behavior:** continue with the successful findings. Do not abort the run.\n\nIn `report.md`, under `Gaps & Limitations`, enumerate every failed slice:\n\n- Name the slice.\n- Include the subagent's last-known brief (or a one-line summary of what it was asked to scan).\n- Include the `reason` line from the stub findings file (see \"Silent-failure detection\" below).\n\nExample:\n\n```markdown\n## Gaps & Limitations\n\n- **Slice \"planning-folder\"** (status: failed) — subagent returned \"Read timeout on .planning/phase-3/PLAN.md after 3 retries\". Caller may retry this slice alone, or re-run with `refresh: true` after investigating the file.\n```\n\n## Empty corpus\n\nPath resolution (auto-discovery + explicit paths) yields zero readable documents after the skip denylist is applied.\n\n**Behavior:** do not spawn subagents. Return cleanly.\n\nThe skill writes:\n\n- `plan.md` with an empty `Resolved paths` list and a note that no readable documents were found.\n- `report.md` with every section present but containing a single bullet each, plus a `Gaps & Limitations` entry:\n\n```markdown\n## Gaps & Limitations\n\n- No readable documents found under the resolved paths. The caller passed <paths> and auto-discovery surfaced <auto-discovered paths>; every entry was either absent, empty, or matched the skip denylist. Pass a broader `paths` list, or point at a different folder.\n```\n\nReturning cleanly lets callers handle \"no documents found\" gracefully (e.g. fall back to asking the user to paste content) rather than crashing on an expected-but-uncommon state.\n\n## Silent-failure detection (stub-file rule)\n\nContext exhaustion and tool errors can cause a subagent to return without producing any output file. The orchestrator has no way to distinguish that from \"the subagent finished but the file is missing for some other reason\" — so the contract requires every subagent to write at least a stub file before returning.\n\n**Contract (enforced by `subagent-brief.md`):**\n\n- Every subagent writes `findings/<slice-slug>.md` with a `status:` frontmatter field: `ok`, `empty`, or `failed`.\n- On `empty` or `failed`, the file includes a one-line `reason:` field.\n- On `ok`, `reason` is omitted.\n\n**Orchestrator check, post-dispatch:**\n\nFor every expected slice, test that the findings file exists. For any missing file, record a silent-failure entry under `Gaps & Limitations`:\n\n```markdown\n- **Slice \"<name>\"** — subagent returned without producing a findings "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1999,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:52:27.079Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:52:27.079Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T18:16:24.511Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}