xdrs-core 0.49.1 → 0.50.0

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)

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

@@ -5,13 +5,46 @@ description: >
   Activate this skill when the user asks to create or write any XDRS element.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.0.0"
+  updated: 2026-09-19
 ---
 
 ## Overview
 
 Routes the request to the appropriate XDRS authoring skill based on the type of document the user wants to create. Reads the target skill at runtime and follows its instructions in full.
 
+### Inputs
+
+#### Required
+
+- A free-form request to write a document.
+
+#### Optional
+
+- None.
+
+### Outputs
+
+#### Contents
+
+- The delegated skill's fully written file.
+
+#### Changes
+
+- Whatever changes the delegated skill makes.
+
+### Halt Conditions
+
+- No document type identifiable even after clarification.
+
+### User Interaction
+
+- A single disambiguation question when type is unclear.
+
+### Runtime Requirements
+
+- Same as the delegated skill's, if any.
+
 ## Instructions
 
 ### Phase 1: Infer Document Type
@@ -60,3 +93,17 @@ Read the full content of the skill file for the inferred type, then follow all i
 - MUST NOT create documents of a type not listed in the routing table above.
 - When routing to the Policy skill, MUST also read `_core-adr-policy-016` (`.xdrs/_core/adrs/principles/016-policy-subjects.md`) before choosing a subject — it contains the allowed subject list, descriptions, and disambiguation tiebreaker rules.
 - When routing to the Policy skill, MUST also read `_core-adr-policy-017` (`.xdrs/_core/adrs/principles/017-policy-numbering-ranges.md`) before choosing a policy number — it defines the subject-based block ranges that determine valid numbers for each subject.
+
+## Anti-Patterns
+
+- **Mistake:** Authoring the document directly from general knowledge of the target type instead of reading the target skill file.
+  **Why it happens:** The router already knows roughly what a Policy or Skill looks like, so reading the full target skill feels redundant.
+  **Instead:** Always read the full target SKILL.md and follow it phase by phase; this skill is a router, not an author.
+
+- **Mistake:** Guessing the document type without asking when the request is genuinely ambiguous (e.g., could be Research or Article).
+  **Why it happens:** Asking feels like it slows the user down.
+  **Instead:** Ask the single focused disambiguation question in Phase 1 rather than guessing wrong and producing the wrong document type.
+
+- **Mistake:** Creating a document type not present in the routing table (e.g., a generic README) by improvising a new template.
+  **Why it happens:** The user's request doesn't map cleanly onto the six known types.
+  **Instead:** MUST NOT create documents of a type not listed in the routing table; clarify with the user instead.