---
type: "auto"
tier: "2b"
description: "User names external repo/file/URL/artifact as reference — fetch the actual tree and inspect, never summarize from README or metadata"
alwaysApply: false
triggers:
  - intent: "look at how X does it"
  - intent: "compare with reference repo"
  - intent: "use as template / vorlage"
  - intent: "wie macht es X"
  - intent: "vergleiche mit Y"
  - intent: "schau dir Z an"
  - intent: "study this competitor"
  - keyword: "github.com/"
  - keyword: "source of truth"
  - phrase: "reference repo"
workspaces:
  - agent-config-maintainer
packs:
  - meta
---

# external-reference-deep-dive

## The Iron Law

```
EXTERNAL REFERENCE NAMED → DEEP-DIVE FIRST.
NO README-ONLY SUMMARIES. NO METADATA GUESSES.
INSPECT THE TREE, THE FRONTMATTER, THE CONFIGS, THE CODE.
ABSENCE-OF-EVIDENCE IS NOT EVIDENCE — FETCH BEFORE CLAIMING.
```

Triggered when the user points to an external artifact (repo URL, `owner/repo`, file path, website, archive) **and** asks to analyze, compare, mirror, use as template, or "see how they do it". The user invested in naming the source — answer from the source, not from the cover.

## Mandatory before drawing any conclusion

1. **Use `/analyze-reference-repo`** (the canonical flow) when the artifact is a repo. Its Steps 2–5 are not optional shortcuts — they are the deep-dive contract: fetch listings (not just README), inspect key directories (`skills/`, `rules/`, `commands/`, `scripts/`, `.github/workflows/`, install configs, frontmatter samples), classify each axis adopt/adapt/reject/already.
2. **For single files / websites** — fetch the actual content, not a summary. PDFs/DOCX/XLSX → `markitdown` first.
3. **Cite verbatim** — every finding lands with a file path, line range, or URL fragment. "The README says X" is **not** a finding about implementation; it's a finding about marketing copy.
4. **Surface what was inspected** — list the files / directories actually fetched, so the user can audit coverage.
5. **"Not found" beats "probably not there"** — if a fetch budget was hit, say which subtrees are still un-inspected and ask before concluding absence.

## Forbidden patterns

- Reading only the README / homepage / package description and reporting capabilities.
- Declaring "they don't support X" without listing the directories actually inspected.
- Repeating a surface-level claim across turns without re-fetching when the user pushes back.
- Treating `package.json` / `composer.json` keywords as evidence of behavior.
- Summarizing a competitor's installer story from prose instead of reading `scripts/install*`, `bin/*`, or the npm `bin` field.

## Failure mode catalog

| Pattern | Why it fails | Fix |
|---|---|---|
| **README-summary-as-analysis** | Marketing prose ≠ implementation. Capabilities listed there may be aspirational, deprecated, or differently scoped. | Fetch the directory listing + 1–2 representative files per axis. |
| **"Nothing matches" without enumeration** | Claims absence without proof. The user has to re-prompt to force the real lookup. | Before saying "no X", list the directories scanned. If the budget caps, ask which to expand. |
| **Repeat-the-guess after pushback** | User says "really look" → agent re-paraphrases the same surface read. Burns trust. | On any pushback that names the source again, restart from a tree listing, not from prior notes. |
| **Cross-tool path inference from a single example** | One config file ≠ a convention. | Inspect ≥2 unrelated tool integrations before claiming a pattern is the project's universal anchor strategy. |

**Case-zero anchor.** May 2026 — `nextlevelbuilder/ui-ux-pro-max-skill` was named as the source of truth for 23 AI-tool anchors. Three rounds of "we have no content for these tools" were reported from README inference. The actual `tool-configs/*.json` files in the reference repo gave the exact directory layout per tool in one fetch. Cost: ~2 hours of user frustration. Lesson: when an external source is named, the first action is `GET /repos/{o}/{r}/contents/{interesting-subtree}` — not paraphrase.

## Escape hatch

User explicitly fences the scope (*"quick scan only"*, *"just glance at the README"*, *"don't fetch the whole thing"*) → quick-scan path is allowed. Say so up front: *"Quick-scan mode per your scope — README + top-level layout only, not a full analysis."*

## See also

- Command [`/analyze-reference-repo`](../commands/analyze-reference-repo.md) — canonical deep-dive flow.
- Rule [`think-before-action`](think-before-action.md) — sibling Iron Law for code paths in **this** repo; this rule is its mirror for **external** artifacts.
- Rule [`ask-when-uncertain`](ask-when-uncertain.md) — when a fetch budget caps, ask which subtree to expand instead of guessing.
- Skill [`markitdown`](../skills/markitdown/SKILL.md) — convert binary office formats before analysis.
