xdrs-core 0.49.1 → 0.51.0

package/.xdrs/_core/adrs/principles/skills/review/SKILL.md

@@ -6,13 +6,46 @@ description: >
    Also activate when you identify a need to check compliance with Policies during implementation.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Performs a structured review of code changes or files against the Policies in the repository, categorizing findings by severity and type, and reporting them without modifying any code.
 
+### Inputs
+
+#### Required
+
+- A git diff, file set, or documents to review.
+
+#### Optional
+
+- Specific Policies or scope to focus on.
+
+### Outputs
+
+#### Contents
+
+- Structured ERROR/WARNING findings report in chat.
+
+#### Changes
+
+- None.
+
+### Halt Conditions
+
+- A declared follows scope is missing or unreadable.
+- A declared extends scope is missing or unreadable.
+- A local meta-policy file exists but cannot be read.
+- The declared scope-type has no governance policy.
+
+### Runtime Requirements
+
+- `git` available for diff-scoped reviews.
+- `npx @mermaid-js/mermaid-cli` for Mermaid diagram checks.
+
 ## Instructions
 
 ### Phase 1: Code Gathering
@@ -112,10 +145,23 @@ Scope: [scope identifier]
 - If no Policies apply to the scope, output "No applicable Policies found" and skip reporting.
 - If a potential violation is in pre-existing code outside the diff, report it as WARNING only.
 
+## Anti-Patterns
+
+- **Mistake:** Reporting a finding based on general good-practice opinion with no specific Policy citation.
+  **Why it happens:** The reviewer conflates "seems wrong" with "violates a documented rule".
+  **Instead:** Drop any finding that cannot be traced to a specific rule in an Accepted Policy.
+
+- **Mistake:** Skipping the prerequisites gate (follows/extends/local meta-policy checks) when the scope looks simple.
+  **Why it happens:** The gate feels like overhead for a quick review request.
+  **Instead:** Always run the full prerequisites gate first; a silent FAIL on a missing governance layer is safer than an unreliable PASS.
+
+- **Mistake:** Editing the reviewed code directly to "just fix it" instead of only reporting findings.
+  **Why it happens:** Fixing feels faster than describing the fix.
+  **Instead:** This skill MUST NOT edit code; only report findings and suggested actions.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
 - [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
 - [_core-adr-policy-020 - Media and asset standards](../../020-media-and-asset-standards.md)
-

package/.xdrs/_core/adrs/principles/skills/write-article/SKILL.md

@@ -4,13 +4,42 @@ description: >
    Creates a new article document following XDRS article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple Policies, Research documents, and Skills around a topic. Activate this skill when the user asks to create, add, or write a new article, guide, or overview document within an XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a well-structured article by following `_core-adr-policy-004`, consulting `policy-standards` for every core element definition, researching the Policies, Research documents, and Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating decision content.
 
+### Inputs
+
+#### Required
+
+- A topic for the article.
+
+#### Optional
+
+- Target audience, scope, or XDRS elements to synthesize.
+
+### Outputs
+
+#### Contents
+
+- A new article file.
+
+#### Changes
+
+- Index entry and back-references in synthesized documents.
+
+### Halt Conditions
+
+- No relevant Policies, Research, or Skills exist to synthesize.
+
+### User Interaction
+
+- Clarification of target audience when unspecified.
+
 ## Instructions
 
 ### Phase 0: Clarify Intent
@@ -151,6 +180,22 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST defer to active and applicable Policies when article synthesis conflicts with them.
 
+## Anti-Patterns
+
+- **Mistake:** Reproducing decision text verbatim from a Policy instead of summarizing and linking to it.
+  **Why it happens:** Copying feels safer/more accurate than paraphrasing.
+  **Instead:** Articles are views, not decisions; summarize and link back to the authoritative Policy.
+
+- **Mistake:** Writing an article that spans multiple unrelated subjects without splitting it into chapters.
+  **Why it happens:** A broad topic feels easier to cover in one long document.
+  **Instead:** Once content approaches ~2000 words or covers distinct sub-topics, split into separate chapter articles per Phase 5/Edge Cases guidance.
+
+- **Mistake:** Skipping Phase 0 clarifying questions (topic/audience/scope) because the request seems clear.
+  **Why it happens:** The request looks self-explanatory, so asking feels like unnecessary friction.
+  **Instead:** Always ask the mandatory Phase 0 questions in a single batch before reading standards; audience in particular is easy to assume wrongly.
+
+## References
+
 - [_core-adr-policy-004 - Article standards](../../004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)

package/.xdrs/_core/adrs/principles/skills/write-initiative/SKILL.md

@@ -6,13 +6,42 @@ description: >
   Activate this skill when the user asks to create, add, or write an initiative, plan, project plan, roadmap, or execution plan within an XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a well-structured initiative document by following `_core-adr-policy-007`, consulting `xdrs-core` for every core element definition, researching related Policies and existing initiatives, and producing a focused execution document that connects to the decisions, research, and skills it relates to.
 
+### Inputs
+
+#### Required
+
+- A problem statement and proposed solution.
+
+#### Optional
+
+- Expected timeline or milestones.
+
+### Outputs
+
+#### Contents
+
+- A new initiative file.
+
+#### Changes
+
+- Index entry and back-references in related documents.
+
+### Halt Conditions
+
+- Rejects an expected end date beyond 2 years.
+
+### User Interaction
+
+- Clarifying questions about stakeholders and constraints, one batch.
+
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
@@ -32,7 +61,6 @@ Guides the creation of a well-structured initiative document by following `_core
    - Typical questions cover: the problem being solved, the proposed solution, the expected timeline, the scope, the key stakeholders, and any known constraints or risks.
    - Do NOT ask questions whose answers are already clear from context.
 
-
 ### Phase 2: Select Scope, Type, and Subject
 
 Consult `001-xdrs-standards` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
@@ -154,6 +182,20 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - If an initiative is fully implemented, delete it and confirm that all lasting outputs (Decisions, Skills, Articles, etc.) are properly linked and indexed.
 - If the user asks for an initiative that is really just a decision, guide them to create a Policy instead.
 
+## Anti-Patterns
+
+- **Mistake:** Writing a heavy, generic project-management document instead of focusing on problem/solution/approach.
+  **Why it happens:** Initiative templates have many optional sections, tempting the author to fill all of them.
+  **Instead:** Only fill optional sections when they add real value; keep the document focused and ephemeral.
+
+- **Mistake:** Leaving a completed initiative in the repository indefinitely instead of deleting it after implementation.
+  **Why it happens:** Deleting a finished document feels like discarding useful history.
+  **Instead:** Initiatives are ephemeral; delete them after full implementation once outputs are linked/indexed elsewhere.
+
+- **Mistake:** Setting an Expected end date more than 2 years out instead of splitting the initiative.
+  **Why it happens:** A large effort feels like one continuous initiative.
+  **Instead:** Break initiatives whose scope exceeds 2 years into multiple smaller, independently actionable initiatives.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)

package/.xdrs/_core/adrs/principles/skills/write-policy/SKILL.md

@@ -5,13 +5,42 @@ description: >
   Activate this skill when the user asks to create, add, or write a new Policy (ADR, BDR, or EDR).
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a well-structured Policy by following the standards in `_core-adr-policy-001`, consulting `policy-standards` for every core element definition, researching existing policies for conflicts, checking redundancy across related artifacts, and iterating until the document is concise, decision-focused, and clear about when the decision should be used.
 
+### Inputs
+
+#### Required
+
+- A decision topic to document.
+
+#### Optional
+
+- Preferred Policy type, if already known.
+
+### Outputs
+
+#### Contents
+
+- A new Policy file.
+
+#### Changes
+
+- Index entries added in the relevant scope.
+
+### Halt Conditions
+
+- Decision conflicts with an existing Policy, unresolved.
+
+### User Interaction
+
+- Clarifying questions when the decision topic is ambiguous.
+
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
@@ -187,6 +216,20 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - MUST keep scope `_local` unless the user explicitly states otherwise.
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 
+## Anti-Patterns
+
+- **Mistake:** Creating a new Policy that duplicates a decision already captured elsewhere instead of extending or linking it.
+  **Why it happens:** Writing a fresh Policy feels faster than researching existing ones in Phase 4.
+  **Instead:** Always research related Policies first; extend or reference an existing decision rather than duplicating it.
+
+- **Mistake:** Using lowercase "must"/"should" for normative requirements instead of uppercase BCP 14 keywords.
+  **Why it happens:** Natural writing style favors lowercase, and the distinction feels pedantic.
+  **Instead:** Use uppercase MUST/SHOULD/MAY for every normative statement in Details and Decision Outcome; verify in Phase 7.
+
+- **Mistake:** Skipping the Phase 0 prerequisites gate for a scope that "obviously" has no follows/extends chain.
+  **Why it happens:** The gate feels unnecessary when the scope looks simple.
+  **Instead:** Always run the prerequisites gate before writing; a missing governance layer produces an unreliable Policy.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)

package/.xdrs/_core/adrs/principles/skills/write-presentation/SKILL.md

@@ -5,13 +5,46 @@ description: >
   Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDRS document.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a Marp Markdown slide presentation that supports an existing XDRS document. The skill ensures the slides follow presentation standards (`_core-adr-policy-009`), are correctly placed in the `.assets/` folder, and maintain bidirectional links with the parent document.
 
+### Inputs
+
+#### Required
+
+- A parent XDRS document to present.
+
+#### Optional
+
+- Target audience for the slides.
+
+### Outputs
+
+#### Contents
+
+- A new Marp slide deck file.
+
+#### Changes
+
+- A bidirectional link added to the parent document.
+
+### Halt Conditions
+
+- Parent document does not exist yet.
+
+### User Interaction
+
+- Confirmation of audience when unclear.
+
+### Runtime Requirements
+
+- Marp-compatible viewer for visual rendering (optional).
+
 ## Instructions
 
 ### Phase 0: Prerequisites Gate — MUST complete before writing
@@ -159,6 +192,20 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - If the content requires more than 30 slides, split into multiple slide sets with distinct audience or topic focus.
 - If the parent document changes after slides are created, the slides must be reviewed and updated.
 
+## Anti-Patterns
+
+- **Mistake:** Creating standalone slides for multiple documents without first creating a synthesizing article.
+  **Why it happens:** Building slides directly from several source documents feels quicker than authoring an article first.
+  **Instead:** When slides must cover multiple documents, create (or point to) an article first and build slides for that article.
+
+- **Mistake:** Packing dense paragraphs of text onto slides instead of short bullets and visuals.
+  **Why it happens:** Copying exact wording from the parent Policy feels safer than summarizing.
+  **Instead:** Minimize text per slide; use bullets, tables, and visuals, reserving longer text only for exact-wording cases like controls.
+
+- **Mistake:** Forgetting to add a back-link from the parent document to the new slide file.
+  **Why it happens:** The slide file itself already links to the parent, so the reverse link feels redundant.
+  **Instead:** Bidirectional links are required; always update the parent document's `## References` (Phase 6).
+
 ## References
 
 - [_core-adr-policy-009 - Presentation standards](../../009-presentation-standards.md)

package/.xdrs/_core/adrs/principles/skills/write-research/SKILL.md

@@ -6,7 +6,8 @@ description: >
   Activate this skill when the user asks to create, add, or write a research document that backs a decision.
 metadata:
   author: flaviostutz
-  version: "1.4"
+  version: "1.4.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
@@ -15,6 +16,38 @@ Guides the creation of a well-structured research document by following `_core-a
 
 This skill is interactive by design. Ask clarifying questions to the user at each phase where direction, evidence, or scope is unclear. Ask sequentially — one focused set of questions at a time — and wait for the user's answers before advancing to the next phase. Never front-load all questions at once if not all are yet relevant.
 
+### Inputs
+
+#### Required
+
+- A research direction or question.
+
+#### Optional
+
+- Available evidence and the intended next step.
+
+### Outputs
+
+#### Contents
+
+- A standalone IMRAD research document.
+
+#### Changes
+
+- Index entry and back-references where relevant.
+
+### Halt Conditions
+
+- Redirects to write-policy if a final decision is wanted.
+
+### User Interaction
+
+- Interactive evidence-gathering, section by section.
+
+### Runtime Requirements
+
+- Python 3 for the optional ratio-check script.
+
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
@@ -188,7 +221,6 @@ for line in text.splitlines():
   if current is not None:
     sections[current].append(line)
 
-
 def count_words(markdown: str) -> int:
   cleaned = markdown
   cleaned = re.sub(r"^\|(?:\s*[-:]+\s*\|)+\s*$", " ", cleaned, flags=re.M)
@@ -202,7 +234,6 @@ def count_words(markdown: str) -> int:
   words = cleaned.strip().split()
   return len(words)
 
-
 targets = {
   "Introduction": 3,
   "Methods": 5,
@@ -276,12 +307,6 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - If the supported decision does not exist yet, reference the decision topic or planned Policy title in the introduction and conclusion.
 - If the user's direction, evidence base, or intended next step is vague, ask follow-up questions and wait for clarification instead of choosing a path yourself.
 
-## References
-
-- [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
-- [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
-- [write-policy skill](../write-policy/SKILL.md)
-
 ## Constraints
 
 - MUST consult `001-xdrs-standards` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
@@ -289,3 +314,23 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - MUST keep scope `_local` unless the user explicitly states otherwise.
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST keep the document as research rather than turning it into a final decision.
+
+## Anti-Patterns
+
+- **Mistake:** Writing conclusions or a final decision inside the research document instead of keeping it exploratory.
+  **Why it happens:** The findings feel conclusive enough to just state the decision directly.
+  **Instead:** Keep the document as evidence and analysis; direct the user to `write-policy` for the actual decision.
+
+- **Mistake:** Front-loading all clarifying questions at once instead of asking sequentially as each phase reveals new gaps.
+  **Why it happens:** Batching questions feels more efficient for the user.
+  **Instead:** This skill is interactive by design — ask one focused set of questions per phase and wait for answers before advancing.
+
+- **Mistake:** Skipping the Phase 9 word-count/ratio check because the sections "look" balanced.
+  **Why it happens:** Running the Python script feels like unnecessary overhead once the draft reads well.
+  **Instead:** Always run the ratio check; imbalance is often invisible until measured (e.g., Results ballooning past Methods).
+
+## References
+
+- [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
+- [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
+- [write-policy skill](../write-policy/SKILL.md)

package/.xdrs/_core/adrs/principles/skills/write-skill/SKILL.md

@@ -6,13 +6,46 @@ description: >
   Activate this skill when the user asks to create, add, or write a new skill, agent skill, or SKILL.md file.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Guides the creation of a well-structured skill package by following `_core-adr-policy-003` skill standards, consulting `xdrs-core` for every core element definition, checking existing skills to avoid duplication, and producing a complete SKILL.md ready to activate in VS Code.
 
+### Inputs
+
+#### Required
+
+- A description of the task the skill should perform
+
+#### Optional
+
+- None
+
+### Outputs
+
+#### Contents
+
+- A complete SKILL.md file
+
+#### Changes
+
+- A symlink under `.agents/skills/`
+
+### Halt Conditions
+
+- No writable scope can be found or inferred
+
+### User Interaction
+
+- A clarifying question when scope or type is ambiguous
+
+### Runtime Requirements
+
+- Write access to the target scope.
+
 ## Instructions
 
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
@@ -64,13 +97,46 @@ description: >
   [What the skill does AND exactly when an agent should activate it. Max 1024 chars.]
 metadata:
   author: [author]
-  version: "1.0"
+  version: "1.0.0"
+  updated: [YYYY-MM-DD]
 ---
 
 ## Overview
 
 [1–3 sentence goal statement with the task objective, expected outcome, and relevant prerequisites or tools when they matter.]
 
+### Inputs
+
+#### Required
+
+[Bare-minimum bullets needed to invoke the skill, or a single "None" bullet. Each under 10 words.]
+
+#### Optional
+
+[Extra helpful-context bullets, or a single "None" bullet. Each under 10 words.]
+
+### Outputs
+
+#### Contents
+
+[End-objective files/chat text produced, or a single "None" bullet. Each under 10 words.]
+
+#### Changes
+
+[End-objective external system mutations, or a single "None" bullet. Each under 10 words.]
+
+### Halt Conditions
+
+[This skill's specific stop-before-completing triggers, or a single "None" bullet. Each under 10 words.]
+
+### User Interaction
+
+[Optional. Human-in-the-loop exchanges during execution: clarifying questions or approval gates, or a single "None" bullet. Each under 10 words. Omit the whole section if none apply.]
+
+### Runtime Requirements
+
+[Optional. Tooling/network prerequisites as free-form bullets. Omit the whole section if none apply.]
+
 ## Instructions
 
 ### Phase 1: …
@@ -78,17 +144,23 @@ metadata:
 
 ## Examples
 
-[At least one concrete input/context → expected agent action pair.]
+[At least one concrete input/context → expected agent action pair. Include 2-3 example prompts a user could type to trigger the skill.]
 
 ## Edge Cases
 
 [Situations where the skill must not activate or must behave differently.]
 
+## Anti-Patterns
+
+[At least 3 entries. Each with **Mistake:**/**Why it happens:**/**Instead:** structure, grounded in this specific skill's domain.]
+
 ## References
 
 [Links to related Policies and skills.]
 ```
 
+If the skill needs to be distributed as a standalone package outside the full `xdrs-core` package, it MAY also add a bundling `Makefile` following the optional mechanism in [`_core-adr-policy-021`](../../021-skill-bundling.md). This is not required for skills that are always consumed as part of the full package.
+
 Rules:
 - Use imperative language ("Read …", "Ask …", "Create …").
 - The `description` field must state both *what* the skill does and *when* to activate it.
@@ -100,7 +172,7 @@ Rules:
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists first, then ASCII art for very simple cases, then Mermaid.js (sequence, state, activity, entity diagrams) for complex ones, then draw.io when Mermaid is insufficient — save as Editable Vector (File → Save As → Editable Vector) and store as `.svg` in the sibling `.assets/` folder.
 - If `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[skill-name]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
-- No emojis. Lowercase filenames. Target under 6500 words.
+- No emojis. Lowercase filenames. Target under 7000 words.
 
 ### Phase 5: Review the Draft
 
@@ -108,10 +180,12 @@ Before writing files, verify:
 
 1. **Activation criteria**: Is it unambiguous when this skill loads vs. when it should not?
 2. **Completeness**: Does every phase have actionable steps?
-3. **Length**: Under 6500 words? Trim verbose explanations.
+3. **Length**: Under 7000 words? Trim verbose explanations.
 4. **Duplication**: Does this overlap an existing skill? If yes, revise.
 5. **References**: Are all related XDRs and skills linked, including the cases where the skill operationalizes multiple XDRs?
-6. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `skill`.
+6. **Anti-Patterns**: Does the skill include at least 3 genuine, domain-specific `## Anti-Patterns` entries (not generic filler)?
+7. **Required sections**: Does `## Overview` contain nested `### Inputs` (Required/Optional bullets), `### Outputs` (Contents/Changes bullets), and `### Halt Conditions` listing this skill's specific stop triggers — each bullet under 10 words or a single "None"?
+8. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `skill`.
 
 If any check fails, revise before continuing.
 
@@ -137,6 +211,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - MUST keep scope `_local` unless the user explicitly states otherwise.
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST include a References section linking to `003-skill-standards`.
+- MUST include nested `### Inputs`, `### Outputs`, and `### Halt Conditions` subsections inside `## Overview` with skill-specific content.
 
 **Input**: "Create a skill to help debug CI pipelines"
 - Type: EDR (engineering workflow)
@@ -150,14 +225,32 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - Subject: `application`
 - Output: `.xdrs/_local/adrs/application/skills/review-api-design/SKILL.md`
 
+**Input**: "Add a skill for our onboarding checklist"
+- Asks a clarifying question if scope or type is ambiguous, then drafts the skill package.
+
 ## Edge Cases
 
 - If the user's goal is already covered by an existing skill, inform the user and offer to extend it instead of creating a new one.
 - If scope is ambiguous, default to `_local` and note the assumption.
 - If the goal spans multiple types (e.g., both EDR and ADR), favor the type that best matches the primary activity.
 
+## Anti-Patterns
+
+- **Mistake:** Omitting the `metadata.author`/`metadata.version`/`metadata.updated` fields, or using a partial version like `1.0` instead of full semantic versioning.
+  **Why it happens:** These feel like optional bookkeeping details rather than required fields.
+  **Instead:** `author`, `version` (full `MAJOR.MINOR.PATCH`), and `updated` (ISO date) are all required per `_core-adr-policy-003`.
+
+- **Mistake:** Writing a boilerplate `## Anti-Patterns` section that restates the Edge Cases content instead of describing real authoring mistakes.
+  **Why it happens:** Anti-Patterns and Edge Cases both describe "things that can go wrong", which invites duplication.
+  **Instead:** Edge Cases describe when the skill should behave differently; Anti-Patterns describe mistakes an agent following the skill is likely to make and how to avoid them.
+
+- **Mistake:** Creating a new skill that duplicates an existing one instead of extending it, because the existing skill wasn't searched for first.
+  **Why it happens:** Writing fresh instructions feels faster than reading and understanding an existing skill.
+  **Instead:** Always list `.xdrs/[scope]/[type]/[subject]/skills/` first (Phase 3) and extend or reference an existing skill when one already covers the goal.
+
 ## References
 
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
+- [_core-adr-policy-021 - Skill bundling](../../021-skill-bundling.md)
 - [write-policy skill](../write-policy/SKILL.md)