diff --git a/skills/domain-discovery/SKILL.md b/skills/domain-discovery/SKILL.md index 65ff394..2528bf8 100644 --- a/skills/domain-discovery/SKILL.md +++ b/skills/domain-discovery/SKILL.md @@ -2,14 +2,14 @@ name: skill-domain-discovery description: > Analyze library documentation and source code, then interview maintainers - to discover capability domains and generate a structured domain map for - AI coding agent skills. Activate when creating skills for a new library, - organizing existing documentation into skill categories, or when a - maintainer wants help deciding how to structure their library's agent-facing - knowledge. Produces a domain_map.yaml and skill_spec.md that feed directly - into the skill-tree-generator skill. + to discover capability domains and task-focused skills for AI coding + agents. Activate when creating skills for a new library, organizing + existing documentation into skill categories, or when a maintainer wants + help deciding how to structure their library's agent-facing knowledge. + Produces a domain_map.yaml and skill_spec.md that feed directly into + the skill-tree-generator skill. metadata: - version: "2.1" + version: "3.0" category: meta-tooling output_artifacts: - domain_map.yaml @@ -25,36 +25,128 @@ 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. -There are four phases. Always run them in order. Phases 1–2 are autonomous. -Phase 3 is an interview that builds on what you learned. Phase 4 produces -the final artifacts. +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. + +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** + +--- + +## 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) +4. **AGENTS.md or .cursorrules** — if the library already has agent + guidance, read it. This is high-signal for what the maintainer + considers important + +### 1b — 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 playbooks +- Whether the library is a monorepo and which packages matter + +--- + +## Phase 2 — High-level interview + +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. + +### 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. +2. Take notes silently. Do not summarize back unless asked. +3. 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." + +### 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–2 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]?" + +### 2d — 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?" --- -## Phase 1 — Read everything (autonomous) +## Phase 3 — Deep read (autonomous) -Read the library's documentation and source code. You are collecting raw -material — not reasoning about structure yet. +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 exact order. Each step builds context for the next. +Read in this order. Each step builds context for the next. -1. **README and overview** — establishes vocabulary and core mental model -2. **Getting started / quickstart** — reveals the happy path and setup -3. **Every narrative guide** — the how-to content, not API reference tables -4. **Migration guides** — highest-yield source for failure modes; every +1. **Every narrative guide** — the how-to content, not API reference tables +2. **Migration guides** — highest-yield source for failure modes; every breaking change is exactly what agents trained on older versions produce -5. **API reference** — scan for exports, type signatures, option shapes -6. **Changelog for major versions** — API renames, removed exports, +3. **API reference** — scan for exports, type signatures, option shapes +4. **Changelog for major versions** — API renames, removed exports, behavioral changes -7. **GitHub issues and discussions** — scan for frequently reported +5. **GitHub issues and discussions** — scan for frequently reported confusion, common misunderstandings, recurring questions. Also look for 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]" -8. **Source code** — verify ambiguities from docs, check defaults, find - assertions and invariant checks + like Y, which reveals a tension between [design force] and [design force]." + If no web access, check for FAQ.md, TROUBLESHOOTING.md, or docs/faq + as proxies. +6. **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 @@ -86,24 +178,17 @@ What changed: [one sentence — the specific mechanism] Version boundary: [e.g. "v4 → v5"] ``` -These become high-priority failure modes in Phase 2. - ---- - -## Phase 2 — Draft domain map (autonomous) - -You now have the concept inventory. Derive domains and failure modes from -it before involving the maintainer. +These become high-priority failure modes. -### 2a — Group the concept inventory +### 3a — Group concepts into domains -Move items into groups. Two items belong together when: +Move concept inventory items into groups. Two items belong together when: - A developer reasons about them together when solving a problem - Solving one correctly requires understanding how the other works - They share a lifecycle, configuration scope, or architectural tradeoff - Getting one wrong tends to produce bugs in the other -**Merge aggressively.** Target 4–7 domains. 5 sharp domains beats 12 thin ones. +Target 4–7 domains. These are conceptual groupings, not the final skills. Do not create a group for: - A single hook, function, or class @@ -111,49 +196,53 @@ Do not create a group for: - "Miscellaneous", "Advanced", or "Other" - Configuration knobs that only affect another group's behavior -### 2b — Validate every group +Name each domain as work being performed, not what the library provides. -For each group: +### 3b — Map domains × tasks → skills -> "Can a developer perform three or more meaningfully different tasks using -> the same mental model this group represents?" +Merge your conceptual domains with the maintainer's task list from +Phase 2. Each skill should match a specific developer moment while +carrying the conceptual depth of its parent domain(s). -If no — merge it with the closest related group. +A skill is well-shaped when: +- A developer would ask for it by name ("help me set up sync") +- It covers enough for the agent to complete the task end-to-end +- It doesn't require loading 3 other skills to be useful -### 2c — Flag subsystems within domains +Some domains produce multiple skills (a broad domain like "data access" +might yield "live-queries", "mutations", "offline-sync"). Some tasks +span domains (a "go-live" checklist touches security, performance, and +configuration). Both are fine. -After grouping, check each domain for internal diversity. A domain may -be conceptually unified (one mental model) but contain multiple -independent subsystems with distinct config interfaces — for example, -5 sync adapters that all solve "connectivity" but each with unique -setup, options, and failure modes. +Also consider: +- **Lifecycle/journey skills** — if the library's docs include a + quickstart guide, go-to-production checklist, or migration path, + suggest these as standalone skills. Don't force them if the docs + don't have the material. +- **Composition skills** — when peer deps or examples show consistent + co-usage with another library, output a full skill for the + integration, not a footnote on a domain. -For each domain, ask: "Does this domain contain 3+ backends, adapters, -drivers, or providers that share a purpose but have distinct -configuration surfaces?" If yes, list them as `subsystems` on the -domain. These tell the skill-tree-generator to produce per-subsystem -reference files rather than compressing everything into one skill. +### 3c — Flag subsystems within skills -Also flag domains with dense API surfaces — if a single topic within -the domain has >10 distinct operators, option shapes, or patterns -(e.g. query operators, schema validation rules), note it as a -`reference_candidates` entry. These need dedicated reference files -for agents to have enough detail for implementation. +Check each skill area for internal diversity. A skill may be +conceptually unified but contain multiple independent subsystems with +distinct config interfaces — for example, 5 sync adapters that all +solve "connectivity" but each with unique setup, options, and failure +modes. -### 2d — Name each group as a capability domain +For each skill, ask: "Does this cover 3+ backends, adapters, drivers, +or providers with distinct configuration surfaces?" If yes, list them +as `subsystems`. These tell the skill-tree-generator to produce +per-subsystem reference files. -Names describe work being performed, not what the library provides: +Also flag dense API surfaces — if a topic has >10 distinct operators, +option shapes, or patterns (e.g. query operators, schema validation +rules), note it as a `reference_candidates` entry. -| If your name is... | It is wrong because... | Rewrite as... | -|---------------------|------------------------|---------------| -| A function/hook name | Feature-oriented | The work the function enables | -| A doc section title | Mirrors existing structure | The developer intent it serves | -| A noun phrase | Describes a thing, not work | Verb phrase or lifecycle name | -| "Configuration" | Too generic | The specific config scope | +### 3d — Extract failure modes -### 2e — Extract failure modes from docs and source - -For each domain, extract failure modes that pass all three tests: +For each skill, extract failure modes that pass all three tests: - **Plausible** — An agent would generate this because it looks correct based on the library's design, a similar API, or an older version @@ -171,42 +260,42 @@ For each domain, extract failure modes that pass all three tests: | Type precision | Source type more restrictive than docs imply | | Environment branches | `typeof window`, SSR flags, `NODE_ENV` — behavior differs silently | -Target 3 failure modes per domain minimum. Complex domains target 5–6. +Target 3 failure modes per skill minimum. Complex skills target 5–6. -**Cross-domain failure modes.** Some failure modes belong to multiple -domains. A developer doing SSR work and a developer doing state management +**Cross-skill failure modes.** Some failure modes belong to multiple +skills. A developer doing SSR work and a developer doing state management both need to know about "stale state during hydration" — they load different skills but need the same advice. When a failure mode spans -domains, list all relevant domain slugs in its `domains` field. The +skills, list all relevant skill slugs in its `skills` field. The skill-tree-generator will write it into every corresponding SKILL file. -List a cross-domain failure mode once, under its primary domain. Set -the `domains` field to all domain slugs it applies to. Do not duplicate +List a cross-skill failure mode once, under its primary skill. Set +the `skills` field to all skill slugs it applies to. Do not duplicate the entry in the YAML — the skill-tree-generator handles duplication into multiple SKILL files at generation time. -### 2f — Identify cross-domain tensions +### 3e — Identify cross-skill tensions -Look for places where design forces between domains conflict. A tension -is not a failure mode — it's a structural pull where getting one domain -right makes another domain harder. Examples: +Look for places where design forces between skills conflict. A tension +is not a failure mode — it's a structural pull where optimizing for one +task makes another harder. Examples: - "Getting-started simplicity conflicts with production operational safety" - "Type-safety strictness conflicts with rapid prototyping flexibility" - "SSR correctness requires patterns that hurt client-side performance" -Tensions are where agents fail most because they optimize for one domain -without seeing the tradeoff. Each tension should name the domains in +Tensions are where agents fail most because they optimize for one task +without seeing the tradeoff. Each tension should name the skills in conflict, describe the pull, and state what an agent gets wrong when it only considers one side. -Target 2–4 tensions. If you find none, the domains may be too isolated — +Target 2–4 tensions. If you find none, the skills may be too isolated — revisit whether you're missing cross-connections. -### 2g — Identify gaps +### 3f — Identify gaps -For each domain, explicitly list what you could NOT determine from docs -and source alone. These become interview questions in Phase 3. +For each skill, explicitly list what you could NOT determine from docs +and source alone. These become interview questions in Phase 4. Common gaps: - "Docs describe X but don't explain when you'd choose X over Y" @@ -216,7 +305,7 @@ Common gaps: - "GitHub issues show confusion about X but docs don't address it" - "I found two patterns for doing X — unclear which is current/preferred" -### 2h — Discover composition targets +### 3g — Discover composition targets Scan `package.json` for peer dependencies, optional dependencies, and `peerDependenciesMeta`. Scan example directories and integration tests @@ -226,44 +315,41 @@ for import patterns. For each frequently co-used library, log: - Whether it's a required or optional integration - Any example code showing the integration pattern -These become targeted composition questions in Phase 3e. +These become targeted composition questions in Phase 4e. -### 2i — Produce the draft domain map +### 3h — Produce the draft Write the full `domain_map.yaml` (format in Output Artifacts below) with a `status: draft` field. Flag every gap in the `gaps` section. -Present the draft to the maintainer before starting the interview: +Present the draft to the maintainer before starting Phase 4: -> "I've read the docs and source for [library] and produced a draft domain -> map with [N] domains and [M] failure modes. Before we start the interview, -> review this draft. I've flagged [K] specific gaps where I need your input." +> "I've read the docs and source for [library] and produced a draft with +> [N] skills and [M] failure modes. I've flagged [K] specific gaps where +> I need your input." --- -## Phase 3 — Maintainer interview (builds on Phase 1–2) +## Phase 4 — Detail interview (builds on Phase 1–3) -You have already read everything and formed a draft. The interview fills -gaps, validates your understanding, and surfaces implicit knowledge. +You have the maintainer's task map and a deep read. The interview now +fills gaps, validates your understanding, and surfaces implicit knowledge. -### Rules for the interview +### Rules for Phase 4 1. One topic per message for open-ended questions. You may batch 2–3 - yes/no or short-confirmation questions in a single message when they - are factual checks (e.g. "Is X still the recommended pattern? Does Y - default apply in production? Is Z deprecated?"). Reserve single-question - format for any question requiring explanation or nuance. + yes/no or short-confirmation questions together. 2. Each question must reference something specific from your reading. 3. If the maintainer gives a short answer, probe deeper before moving on. 4. Take notes silently. Do not summarize back unless asked. -### 3a — Draft review (2–3 questions) +### 4a — Draft review (2–3 questions) -Start by confirming or correcting your draft: +Start by confirming or correcting your skill list and failure modes: -> "I've organized [library] into [N] domains. Here's my proposed grouping: -> [list domains with brief descriptions]. Does this match how you think -> about your library? What would you move, merge, or split?" +> "Here's the skill list I've built from our earlier conversation plus +> the deep read: [list skills with brief descriptions]. Does this still +> match your thinking? Anything to add, remove, or rename?" Follow up on any corrections. Then: @@ -271,9 +357,9 @@ Follow up on any corrections. Then: > there important ones I missed — especially patterns that look correct > but fail silently?" -### 3b — Gap-targeted questions (3–8 questions) +### 4b — Gap-targeted questions (3–8 questions) -For each gap flagged in Phase 2, ask a specific question. These are not +For each gap flagged in Phase 3f, ask a specific question. These are not generic — they reference what you found: **Instead of:** "What do developers get wrong?" @@ -303,7 +389,7 @@ Adapt from this bank of gap-targeted question templates: - "The API reference shows [type signature], but the guide examples use a different shape. Which is accurate?" -### 3c — AI-agent-specific failure modes (2–4 questions) +### 4c — AI-agent-specific failure modes (2–4 questions) These target mistakes that AI coding agents make but human developers typically don't. Agent-specific failures are often the highest-value @@ -325,7 +411,7 @@ the most critical failure modes. that require understanding unstated context, or where the 'obvious' approach from reading the API surface is wrong." -### 3d — Implicit knowledge extraction (3–5 questions) +### 4d — Implicit knowledge extraction (3–5 questions) These surface knowledge that doesn't appear in any docs: @@ -338,9 +424,9 @@ These surface knowledge that doesn't appear in any docs: - "Is there anything you'd change about the API design if you could break backwards compatibility? What's the current workaround?" -### 3e — Composition questions (if library interacts with others) +### 4e — Composition questions (if library interacts with others) -Use what you discovered in Phase 2h. For each integration target +Use what you discovered in Phase 3g. For each integration target identified from peer dependencies and example code, ask targeted questions: @@ -353,14 +439,14 @@ questions: --- -## Phase 4 — Finalize artifacts +## Phase 5 — Finalize artifacts -Merge interview findings into the draft domain map. For each interview answer: +Merge interview findings into the draft. For each interview answer: -1. If it confirms a draft domain or failure mode — no action needed -2. If it corrects something — update the domain map +1. If it confirms a skill or failure mode — no action needed +2. If it corrects something — update the map 3. If it adds a new failure mode — add it with source "maintainer interview" -4. If it reveals a new domain — evaluate whether to add or merge +4. If it reveals a new skill — add it 5. If it fills a gap — remove from gaps section Update `status: draft` to `status: reviewed`. @@ -389,7 +475,14 @@ library: domains: - name: "[work-oriented domain name]" slug: "[kebab-case]" - description: "[what a developer is doing, not what the library provides]" + description: "[conceptual grouping — what a developer is reasoning about]" + +skills: + - name: "[task-focused skill name]" + slug: "[kebab-case]" + domain: "[parent domain slug]" + description: "[what a developer is doing — matches a specific task/moment]" + type: "[core | framework | lifecycle | composition]" covers: - "[API/hook/concept 1]" - "[API/hook/concept 2]" @@ -397,7 +490,7 @@ domains: - "[example task 1]" - "[example task 2]" - "[example task 3]" - subsystems: # omit if domain has no independent subsystems + subsystems: # omit if skill has no independent subsystems - name: "[adapter/backend name]" package: "[npm package if separate]" config_surface: "[brief description of unique config]" @@ -411,21 +504,19 @@ domains: priority: "[CRITICAL | HIGH | MEDIUM]" status: "[active | fixed-but-legacy-risk | removed]" version_context: "[e.g. 'Fixed in v5.2 but agents trained on older code still generate this']" - domains: ["[this-domain-slug]"] # list all domains this belongs to; omit if single-domain - related_domains: - - "[other domain slug this one references]" + skills: ["[this-skill-slug]"] # list all skills this belongs to; omit if single-skill compositions: - library: "[other library name]" skill: "[composition skill name if applicable]" tensions: - name: "[short phrase describing the pull]" - domains: ["[domain-slug-a]", "[domain-slug-b]"] + skills: ["[skill-slug-a]", "[skill-slug-b]"] description: "[what conflicts — one sentence]" implication: "[what an agent gets wrong when it only considers one side]" gaps: - - domain: "[domain slug]" + - skill: "[skill slug]" question: "[what still needs input]" context: "[why this matters]" status: "[open | resolved]" @@ -441,48 +532,55 @@ A human-readable companion document. Follow this structure: [2–3 sentences: what this library is, what problem it solves. Factual, not promotional.] -## Domain Coverage +## Domains + +| Domain | Description | Skills | +|--------|-------------|--------| +| [name] | [conceptual grouping] | [skill-1, skill-2, ...] | + +## Skill Inventory -| Domain | Skill name | What it covers | Failure modes | Tier | -|--------|------------|----------------|---------------|------| -| [name] | [lib]/[slug] | [exhaustive list] | [count] | [1|2] | +| Skill | Type | Domain | What it covers | Failure modes | +|-------|------|--------|----------------|---------------| +| [name] | [core/framework/lifecycle/composition] | [domain] | [list] | [count] | ## Failure Mode Inventory -### [Domain name] ([count] failure modes) +### [Skill name] ([count] failure modes) -| # | Mistake | Priority | Source | Cross-domain? | -|---|---------|----------|--------|---------------| -| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other domain slugs or —] | +| # | Mistake | Priority | Source | Cross-skill? | +|---|---------|----------|--------|--------------| +| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other skill slugs or —] | -[Repeat table for each domain.] +[Repeat table for each skill.] ## Tensions -| Tension | Domains | Agent implication | -|---------|---------|-------------------| +| Tension | Skills | Agent implication | +|---------|--------|-------------------| | [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] | ## Subsystems & Reference Candidates -| Domain | Subsystems | Reference candidates | -|--------|------------|---------------------| +| Skill | Subsystems | Reference candidates | +|-------|------------|---------------------| | [slug] | [adapter1, adapter2, ...] or — | [topic needing depth] or — | ## Remaining Gaps -| Domain | Question | Status | -|--------|----------|--------| +| Skill | Question | Status | +|-------|----------|--------| | [slug] | [what still needs input] | open | [Omit this section if all gaps were resolved in the interview.] ## Recommended Skill File Structure -- **Core skills:** [list which domains become core sub-skills] +- **Core skills:** [list which skills are framework-agnostic] - **Framework skills:** [list per-framework skills needed] +- **Lifecycle skills:** [list journey/lifecycle skills if applicable] - **Composition skills:** [list integration seams needing composition skills] -- **Reference files:** [list domains needing references/ based on subsystems +- **Reference files:** [list skills needing references/ based on subsystems or dense API surfaces] ## Composition Opportunities @@ -498,23 +596,24 @@ not promotional.] | Check | Rule | |-------|------| -| Docs read before interview | Never start interviewing without completing Phase 1–2 | +| Quick scan before interview | Never interview without at least reading README and package structure | +| High-level interview before deep read | The maintainer's task map informs what you read deeply | | Batch only confirmations | Yes/no questions may batch 2–3; open-ended questions get their own message | | Questions reference findings | No generic questions — cite what you found | -| 4–7 domains | Merge aggressively; 5 sharp domains > 12 thin ones | -| Work-oriented names | No function names, no doc section titles | -| 3+ failure modes per domain | Complex domains target 5–6 | +| Skills are task-focused | Each skill matches a developer moment, not a conceptual area | +| 3+ failure modes per skill | Complex skills target 5–6 | | Every failure mode sourced | Doc page, source file, issue link, or maintainer interview | | Gaps are explicit | Unknown areas flagged, not guessed | | No marketing prose | Library description is factual, not promotional | | domain_map.yaml is valid YAML | Parseable by any YAML parser | -| Draft before interview | Always present draft for review first | -| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 3c | +| Draft before detail interview | Present draft for review before Phase 4 | +| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 4c | | Compositions discovered from code | Scan peer deps and examples before asking composition questions | -| Cross-domain failure modes tagged | Failure modes spanning domains list all relevant slugs in `domains` | -| Tensions identified | 2–4 cross-domain tensions; if none found, revisit domain boundaries | -| Subsystems flagged | Domains with 3+ adapters/backends list them as subsystems | +| Cross-skill failure modes tagged | Failure modes spanning skills list all relevant slugs | +| Tensions identified | 2–4 cross-skill tensions; if none found, revisit skill boundaries | +| Subsystems flagged | Skills with 3+ adapters/backends list them as subsystems | | Dense surfaces flagged | Topics with >10 patterns noted as reference_candidates | +| Lifecycle skills considered | Suggest journey skills when docs have the material | --- diff --git a/skills/tree-generator/SKILL.md b/skills/tree-generator/SKILL.md index 2e492c8..568ffef 100644 --- a/skills/tree-generator/SKILL.md +++ b/skills/tree-generator/SKILL.md @@ -56,13 +56,16 @@ skill-domain-discovery skill — prefer running that when time permits. 1. Build a concept inventory (every export, config key, constraint, warning) 2. Group into 4–7 capability domains using work-oriented names -3. Extract 3+ failure modes per domain (plausible, silent, grounded) -4. Proceed to Step 1 below +3. Enumerate 10–20 task-focused skills from the intersection of domains + and developer tasks +4. Extract 3+ failure modes per skill (plausible, silent, grounded) +5. Proceed to Step 1 below ### Step 1 — Plan the file tree -From the domain map, determine which skills are core (framework-agnostic) -and which are framework-specific. +From the domain map, each entry in the `skills` list becomes a SKILL.md +file. The `type` field on each skill (`core`, `framework`, `lifecycle`, +`composition`) determines where it goes. Determine the file tree: **Core vs framework decision:** @@ -242,9 +245,9 @@ Minimum working example for this domain. Each `failure_mode` entry from the domain map becomes a Common Mistake entry in the SKILL file. Minimum 3 entries. Complex domains target 5–6. -**Cross-domain failure modes:** The domain map may contain failure modes -with a `domains` list naming multiple domain slugs. Write these into -every SKILL file whose domain is listed. A developer loading the SSR +**Cross-skill failure modes:** The domain map may contain failure modes +with a `skills` list naming multiple skill slugs. Write these into +every SKILL file whose skill is listed. A developer loading the SSR skill and a developer loading the state management skill both need to see "stale state during hydration" — the same advice must appear in both files. Do not deduplicate across skills at the cost of coverage. @@ -472,7 +475,7 @@ Run every check before outputting. Fix any failures before proceeding. | Check | Rule | |-------|------| -| Every domain from domain_map has a skill | No orphaned domains | +| Every skill from domain_map has a SKILL.md | No orphaned skills | | Core/framework split is clean | No framework hooks in core skills | | Every framework skill has `requires` | Links to its core skill | | Framework skill opens with dependency note | "builds on [core]" prose line | @@ -489,7 +492,7 @@ Run every check before outputting. Fix any failures before proceeding. | Composition skills don't repeat individual skills | Only the seam | | `name` matches directory path | `router-core/search-params` → `router-core/search-params/SKILL.md` | | `sources` filled in sub-skills | At least one repo:path per sub-skill | -| Cross-domain failures in all relevant skills | Failure modes with multiple `domains` appear in each listed skill | +| Cross-skill failures in all relevant files | Failure modes with multiple `skills` appear in each listed SKILL.md | | Tensions noted in affected skills | Each tension has notes in all involved domain skills | | Framework domains decomposed per-package | No single skill covering multiple framework adapters | | Adapter-heavy domains have references | 3+ adapters/backends → one reference file per adapter | @@ -600,7 +603,7 @@ current_skills: | Composition skills require all dependencies | Lists all core + framework skills | | `name` matches directory | `router-core/search-params` → file at that path | | `library_version` in every frontmatter | Which version the skill targets | -| Cross-domain failures duplicated | Each listed domain gets the failure mode | +| Cross-skill failures duplicated | Each listed skill gets the failure mode | | Tensions cross-referenced | Tension notes in each involved skill point to the other | | Skills ship with packages | `"skills"` in package.json `files` array |