Skill Domain Discovery

Domain Discovery & Maintainer Interview

You are extracting domain knowledge for a library to produce a structured domain map. Your job is not to summarize documentation — it is to build a deep understanding of the library first, then use that understanding to surface the implicit knowledge that maintainers carry but docs miss.

The output is a set of task-focused skills — each one matching a specific developer moment ("implement a proxy", "set up auth", "audit before launch"). Domains are an intermediate conceptual grouping you use during analysis; the final skills emerge from the intersection of domains and developer tasks.

There are five phases. Always run them in order — unless the lightweight path applies (see below).

1. Quick scan — orient yourself (autonomous)
2. High-level interview — extract the maintainer's task map
3. Deep read — fill in failure modes and detail (autonomous)
4. Detail interview — gap-targeted questions, AI-agent failures
5. Finalize artifacts

Lightweight path (small libraries)

After Phase 1, decide whether the library warrants the full five-phase flow or the compressed flow below. This is a judgment call — lean toward full discovery unless the library is obviously small (single-purpose utility, 2–3 distinct developer tasks max). Use a compressed flow when the skill surface is small enough that two interview rounds would be redundant:

1. Phase 1 — Quick scan (same as full flow)
2. Phase 2+4 combined — Single interview round. Combine the

high-level task map questions (Phase 2) with gap-targeted and AI-agent-specific questions (Phase 4) into one interview session of 4–8 questions total. Skip the draft-review step since the skill set is small enough to confirm in one pass.

1. Phase 3 — Deep read (same as full flow, but scope is smaller)
2. Phase 5 — Finalize artifacts (same as full flow)

The lightweight path produces identical output artifacts (domainmap.yaml and skillspec.md). It just avoids two separate interview rounds when the library is small enough that one round covers everything.

Hard rules — interview phases are mandatory and interactive

These rules override any other reasoning. No exceptions.

1. **Phases 2 and 4 are interactive interviews conducted with the

maintainer.** You must ask the questions specified in each sub-section and wait for the maintainer's response before continuing. Documentation, source code, and other automated analysis are NOT substitutes for the maintainer's answers.

1. **Every question in Phases 2 and 4 must be asked as an open-ended

question and sent as a message to the maintainer.** You must then STOP and WAIT for their reply. Do not answer your own questions. Do not infer answers from documentation. Do not skip questions because you believe you already know the answer.

1. **Never ask factual questions you can answer by searching the

codebase.** Before asking any question, determine whether the answer is a deterministic fact (how many X exist, what versions are supported, which files implement Y) or a judgment call (which ones matter, what should we prioritize, what do developers struggle with). Factual questions must be answered by searching the code — grep, glob, read files. Only ask the maintainer for priorities, opinions, trade-offs, and implicit knowledge that cannot be found in code or docs. Asking the maintainer a question whose answer is sitting in the codebase wastes their time and erodes trust in the process.

1. **Do not convert open-ended questions into multiple-choice,

yes/no, or confirmation prompts.** The question templates in each sub-section are open-ended by design. Present them as open-ended questions. The maintainer's unprompted answers surface knowledge that pre-structured options suppress.

1. Minimum question counts are enforced. Each sub-section specifies

a question count range (e.g. "2–4 questions"). You must ask at least the minimum number. Asking zero questions in any sub-section is a protocol violation.

1. STOP gates are mandatory. At the boundaries marked ── STOP ──

below, you must halt execution and wait for the maintainer's response or acknowledgment before proceeding. Do not continue past a STOP gate in the same message.

1. If the maintainer asks to skip an interview phase, explain the

value of the phase and what will be lost. Proceed with skipping only if they confirm a second time.

1. Rich documentation makes interviews MORE valuable, not less.

When docs are comprehensive, the interview surfaces what docs miss: implicit knowledge, AI-specific failure modes, undocumented tradeoffs, and the maintainer's prioritization of what matters most. Never rationalize skipping interviews because documentation is thorough.

---

Phase 1 — Quick scan (autonomous, ~10 minutes)

Orient yourself in the library. You are building a structural map, not reading exhaustively yet.

1a — Read orientation material

1. README — vocabulary, mental model, what the library does
2. Getting started / quickstart — the happy path
3. Package structure — if monorepo, identify which packages are

client-facing vs internal. Focus on the 2–3 packages most relevant to skill consumers (usually client SDKs and primary framework adapters)

1. AGENTS.md or .cursorrules — if the library already has agent

guidance, read it. This is high-signal for what the maintainer considers important

1. All in-repo documentation — list every .md file in the docs/

directory (and any other documentation directories like guides/, reference/, wiki/). Read every file. This is NOT the exhaustive external doc reading from Phase 3 — this is reading what the maintainer committed to the repository, which is fast and high-signal. In-repo docs often contain migration guides, backward compatibility notes, architecture decisions, and other context that prevents you from asking factual questions the docs already answer. Do not sample a subset — read them all before the first interview.

1b — Read peer dependency constraints

Check package.json for peerDependencies and peerDependenciesMeta. For each major peer dependency (React, Vue, Svelte, Next.js, etc.):

1. Note the version range required
2. Read the peer's docs for integration constraints that affect this

library: SSR/hydration rules, component lifecycle boundaries, browser-only APIs, singleton patterns, connection limits

1. Log framework-specific failure modes — these are the highest-impact

failure modes and cannot be discovered from the library's own source

Examples of peer-dependency-driven failure modes:

• SSR: calling browser-only APIs during server render
• React: breaking hook rules in library wrapper components
• Connection limits: opening multiple WebSocket connections per tab
• Singleton patterns: creating multiple client instances in dev mode

1c — Note initial impressions

Log (but do not group yet):

• What the library does in one sentence
• The core abstractions a developer interacts with
• Which frameworks it supports
• Any existing skill files, agent configs, or intents
• Whether the library is a monorepo and which packages matter
• Peer dependency constraints — read peerDependencies and

peerDependenciesMeta from each client-facing package.json to understand version ranges and optional integrations early

Present your initial impressions to the maintainer as a brief summary (3–5 bullets). This orients them on what you found and primes them for the interview.

── STOP ── Do not proceed to Phase 2 until the maintainer has acknowledged your summary or responded.

---

Phase 2 — High-level interview (interactive — requires maintainer)

The maintainer's mental model of developer tasks IS the skill map. Your job in this phase is to extract it — not to propose your own structure.

You must ask the questions below to the maintainer and wait for their responses. Do not infer answers from documentation or source code.

Rules for Phase 2

1. One topic per message for open-ended questions. You may batch 2–3

yes/no or short-confirmation questions together.

1. Ask each question as written (you may adapt phrasing to context, but

keep questions open-ended — never convert to multiple-choice).

1. Wait for the maintainer's response after each question before asking

the next.

1. Take notes silently. Do not summarize back unless asked.
2. If the maintainer gives a short answer, probe deeper before moving on.

2a — Developer tasks (2–4 questions)

Start with the maintainer's view of what developers do:

> "Walk me through what a developer actually does with your library — > not the elevator pitch, but the tasks they come to you for help with, > from first install through production."

Follow up to enumerate distinct tasks:

> "If you listed every distinct thing a developer asks an agent to help > with using your library, what would that list look like? I'm thinking > things like 'set up the client', 'implement auth', 'debug sync issues' > — each one a separate moment where they'd want focused guidance."

For monorepo libraries, also ask about cross-package tasks:

> "Are there tasks that touch multiple packages in your monorepo? For > example, a getting-started flow that requires imports from both the > client and server packages? I want to make sure skills that span > package boundaries are captured correctly."

2b — Developer journeys (1–2 questions)

Surface lifecycle/journey skills that cross-cut task areas:

> "Are there developer journeys that cut across multiple features? > For example: a getting-started guide, a go-to-production checklist, > a migrate-from-v4 walkthrough. Which of these exist in your docs > or would be valuable as standalone skills?"

2c — Composition and ecosystem (1–3 questions)

> "Which other libraries does yours compose with most often? Are there > integration patterns important enough to warrant their own skill — > for example, using your library with [framework/ORM/router]?"

> "Are there tasks that developers might expect your library to handle, > but that are actually handled by a companion library? Which tasks > should we explicitly exclude from your library's skills?"

2d — Exclude experimental features (1 question)

> "Are there any features that are experimental, unstable, or not yet > ready to document for agents? We'll exclude these from the skill set."

2e — Confirm initial skill map

Synthesize what you heard into a proposed skill list and present it:

> "Based on what you've told me, here's my proposed skill list: > [enumerate skills with one-line descriptions]. Does this match how > you think about your library? What would you add, remove, or rename?"

── STOP ── Do not proceed to Phase 3 until the maintainer has reviewed and confirmed (or corrected) the skill list.

---

Phase 3 — Deep read (autonomous)

You now have the maintainer's task map. Read docs and source to fill each skill area with concrete content — failure modes, code patterns, gotchas.

Reading order

Read in this order. Each step builds context for the next.

Before starting, list every file in the docs directory (and subdirectories). Use this list as a checklist — every narrative file must be read. Do not sample a subset and extrapolate.

1. Narrative guides — read as many as needed to build confidence in

your understanding. Prioritize getting-started, migration, and guides covering the skill areas from Phase 2. Skip exhaustive reading of large online-only doc sets.

1. Migration guides — highest-yield source for failure modes; every

breaking change is exactly what agents trained on older versions produce

1. API reference — scan for exports, type signatures, option shapes
2. Changelog for major versions — API renames, removed exports,

behavioral changes

1. GitHub issues and discussions — this is one of the highest-yield

sources for failure modes and skill content. Docs describe intended behavior; issues reveal actual behavior and real developer confusion.

How to search. Use gh search issues and gh search prs (or the GitHub web search UI) against the library's repo. Run multiple passes:

• High-engagement issues: sort by reactions or comments to find the

problems that affect the most developers. These are skill-worthy even if already fixed — agents trained on older data still hit them.

• Label-based scans: look for labels like bug, question,

documentation, breaking-change, good first issue, FAQ, help wanted. Each label category yields different signal:

• bug + closed → failure modes with known fixes (wrong/correct pairs)
• question → developer confusion that skills should preempt
• breaking-change → migration-boundary mistakes
• Keyword searches: search for the skill's primary APIs, hooks,

and config options by name. E.g. useQuery stale or hydration SSR.

• Recent vs. historical: scan the last 6–12 months of open issues

for current pain points. Then scan older closed issues for patterns that are now fixed but still appear in agent training data.

GitHub Discussions are equally important when the repo uses them. Discussions surface "how do I..." patterns and architectural questions that issues don't capture. Search the Discussions tab (or use gh api to query discussions) for:

• Unanswered or long-thread questions (signal: docs are insufficient)
• Threads marked as "Answered" with a non-obvious solution (skill content)
• Recurring themes across multiple threads (systemic confusion)

What to extract from issues/discussions:

• Frequently reported confusion patterns → candidate failure modes
• Workarounds that developers use before a fix ships → "wrong pattern"

examples that agents will reproduce

• Recurring "how do I X with Y" threads → composition skill candidates
• Misunderstandings about defaults or config → skill content gaps
• Feature requests with many upvotes that change API design → signals

of where the API surface is unintuitive

• What users are implicitly arguing for architecturally — not just

"people are confused about X" but "users keep expecting X to work like Y, which reveals a tension between [design force] and [design force]"

What NOT to extract: one-off bugs already fixed, feature requests unrelated to current API surface, issues about build tooling or CI that don't affect library usage patterns.

Fallback. If no web access is available, check for FAQ.md, TROUBLESHOOTING.md, docs/faq, or KNOWN_ISSUES.md as proxies. Also scan the repo's .github/ISSUE_TEMPLATE/ for hints about common issue categories.

1. Source code — verify ambiguities from docs, check defaults, find

assertions and invariant checks. For monorepos, read the 2–3 core packages deeply. For adapter packages, read one representative adapter deeply, then scan others for deviations from the pattern.

What to log

Produce a flat concept inventory. One item per line. No grouping yet.

Log every:

• Named concept, abstraction, or lifecycle stage
• Public export: function, hook, class, type, constant
• Configuration key, its type, and its default value
• Constraint or invariant (especially any enforced by throw or assertion)
• Doc callout: any "note", "warning", "caution", "important", "avoid", "do not"
• Dual API: any place the library has two ways to do the same thing (old/new,

verbose/shorthand, lower-level/higher-level)

• Environment branch: any place behavior depends on SSR/CSR, dev/prod,

framework, bundler, or config flag

• Type gap: any type documented as accepting X but source shows X | Y or

rejects a subtype of X

• Sou

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TanStack
• Source: TanStack/intent
• License: MIT
• Homepage: https://tanstack.com/intent/latest

Install and usage instructions live in the source repository linked above.