xdrs-core 0.52.2 → 0.53.0

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

@@ -5,8 +5,8 @@ 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.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -27,7 +27,7 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 #### Contents
 
-- A new Policy file.
+- A new Policy file (<1300 words; complex <2600).
 
 #### Changes
 
@@ -43,6 +43,8 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
 1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
@@ -137,22 +139,22 @@ Refer to `_core-adr-policy-008-policy-structured-standards` for full requirement
 ---
 name: [scope]-[type]-[number]-[short-title]
 description: [What this decision is about and when to use it]
-apply-to: [Required. Contexts this decision applies to, under 40 words. Use "All scopes" when broadly applicable.]
+apply-to: [Required. Contexts this decision applies to, <40 words. Use "All scopes" when broadly applicable.]
 valid-from: [Required. ISO date YYYY-MM-DD. Defaults to today's date when not specified by the user.]
 ---
 
 # [scope]-[type]-[number]: [Short Title]
 
 ## Context and Problem Statement
-[background, who is impacted, and the explicit question being answered - under 40 words]
+[background, who is impacted, and the explicit question being answered - <40 words]
 
 ## Decision Outcome
 
 **[Chosen Option Title]**
-[One sentence: what is the decision - under 30 words]
+[One sentence: what is the decision - <30 words]
 
 ### Details
-[Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 1300 words]
+[Rules, applicability boundaries, concise examples, and optional do/don't guidance — <1300 words]
 
 ## Considered Options (only if the user explicitly indicated multiple options)
 
@@ -164,7 +166,7 @@ valid-from: [Required. ISO date YYYY-MM-DD. Defaults to today's date when not sp
 Mandatory rules to apply while drafting:
 - Always include frontmatter `apply-to:`. Use `All scopes` when the decision applies broadly, or a more specific description when the decision is narrowly scoped.
 - Always include frontmatter `valid-from:`. Use today's date in `YYYY-MM-DD` format when the user does not specify a date.
-- Keep `apply-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
+- Use `valid-from:` only with `YYYY-MM-DD` ISO format.
 - When frontmatter metadata is present, write it so a reader can decide whether the Policy should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `apply-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced Policies — link instead.
@@ -175,13 +177,12 @@ Mandatory rules to apply while drafting:
 - If the Policy genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.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 1300 words total; under 2600 words for complex decisions.
 
 ### Phase 7: Review the Draft
 
 Check every item before finalizing:
 
-1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
+1. **Length**: Is it within the Policy file cap and every template section cap? Trim verbose explanations. Move detailed skills to a separate file and link.
 2. **Frontmatter**: Are `apply-to:` and `valid-from:` both present? `apply-to:` must describe the applicable context (use `All scopes` when broadly applicable). `valid-from:` must be set (use today's date if the user did not specify one).
 3. **Normative language**: Does every normative requirement in the Details and Decision Outcome sections use uppercase BCP 14 keywords per `_core-adr-policy-001`? Replace any lowercase `must`/`should`/`may` that express requirements, prohibitions, or permissions with MUST/MUST NOT, SHOULD/SHOULD NOT, or MAY/OPTIONAL respectively. Lowercase forms are only acceptable in Context sections, question statements, or when used with their ordinary English meaning.
 4. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
@@ -196,7 +197,7 @@ If any check fails, revise and re-run this phase before proceeding.
 ### Phase 8: Write Files
 
 1. Create the Policy file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
-2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist).
+2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist); keep its description <15 words.
 3. Add or verify the scope entry in the Policy root `index.md` (exactly one link per scope; when the scope index declares `extends-only: true`, append the tag `` `extends-only` `` right after the link and make sure the legend line is present, see `_core-adr-policy-022`).
 4. If significant research was produced or already exists, link it from the Policy `## Considered Options` section.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the Policy into a long procedure.

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

@@ -5,8 +5,8 @@ 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.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -47,6 +47,8 @@ Guides the creation of a Marp Markdown slide presentation that supports an exist
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Prerequisites Gate — MUST complete before writing
 
 Identify the target scope from the parent document's path or the user's request; use `_local` if none is specified. Then run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `presentation`.
@@ -135,7 +137,7 @@ Rules:
 - The first line of YAML frontmatter must be `marp: true`. Additional Marp keys (`theme`, `paginate`, `header`, `footer`) may be added after.
 - Use `---` as the slide separator (standard Marp syntax).
 - The last slide must contain links back to the parent document and any other related documents.
-- Minimize text per slide. Prefer visual elements and short statements.
+- Minimize text per slide: each slide <80 words. Prefer visual elements and short statements.
 - Stress central questions, answers, doubts, decisions, and risks from the parent document.
 - No emojis.
 - Use relative paths for all links.

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

@@ -6,8 +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.0"
-  updated: 2026-09-19
+  version: "1.5.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -30,7 +30,7 @@ This skill is interactive by design. Ask clarifying questions to the user at eac
 
 #### Contents
 
-- A standalone IMRAD research document.
+- A standalone IMRAD research document (<5000 words).
 
 #### Changes
 
@@ -50,6 +50,8 @@ This skill is interactive by design. Ask clarifying questions to the user at eac
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
 1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
@@ -129,39 +131,39 @@ Use the mandatory template from `006-research-standards`:
 
 ## Abstract
 
-[Single paragraph summarizing the goal, methods, results, and conclusion. Goal: let a quick technical reader understand the question, method, main result, and takeaway. Under 200 words.]
+[Single paragraph summarizing the goal, methods, results, and conclusion. Goal: let a quick technical reader understand the question, method, main result, and takeaway. <200 words.]
 
 ## Introduction
 
 [Describe the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives.
-Use visuals, bullets, graphs, or diagrams when helpful. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
+Use visuals, bullets, graphs, or diagrams when helpful. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. <700 words.]
 
 Question: [Central question of the research]?
 
 ## Methods
 
 [Explain how the study was conducted, including design, tools, data sources, and test conditions.
-Include enough detail for an experienced professional to reproduce the relevant parts. Goal: make the important parts of the study reproducible. Under 1200 words.]
+Include enough detail for an experienced professional to reproduce the relevant parts. Goal: make the important parts of the study reproducible. <1200 words.]
 
 ## Results
 
 [Report findings, data, trends, quantitative results, code artifacts, and option comparisons.
-Use figures, tables, or bullets when useful. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
+Use figures, tables, or bullets when useful. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. <1800 words.]
 
 ## Discussion
 
-[Interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications. Goal: interpret the findings for technical readers. Keep this section technically engaged and under 1000 words.]
+[Interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications. Goal: interpret the findings for technical readers. Keep this section technically engaged. <1000 words.]
 
 ## Conclusion
 
-[Summarize the main findings, practical takeaway, applicability boundaries, and important open questions. Goal: summarize the main findings and what they mean in practice. Under 400 words.]
+[Summarize the main findings, practical takeaway, applicability boundaries, and important open questions. Goal: summarize the main findings and what they mean in practice. <400 words.]
 
 ## References
 
 [A list of all cited literature, websites, tutorials, documentation, discussions, and related artifacts. Goal: make all cited sources and supporting artifacts traceable.]
 
-- [Related Policy or artifact](relative/path.md) - Why it matters
-- [Another related Policy if this research informed multiple decisions](relative/path.md) - Why it matters
+- [Related Policy or artifact](relative/path.md) - Why it matters (<15 words)
+- [Another related Policy if this research informed multiple decisions](relative/path.md) - Why it matters (<15 words)
 ```
 
 Rules:
@@ -175,13 +177,13 @@ Rules:
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists and bullet points 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 the research genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/researches/.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 `/`.
-- Keep section word limits within the standard and keep the document under 5000 words total unless the introduction explicitly states that a very detailed analysis is required.
+- Keep every section within its template cap; exceed the document cap only when the introduction explicitly states that a very detailed analysis is required.
 
 ### Phase 8: Check Section Goals
 
 Before the final review, verify each section against its specific goal:
 
-1. **Abstract goal**: Does it let a quick technical reader understand the question, method, main result, and takeaway, in one paragraph and under 200 words?
+1. **Abstract goal**: Does it let a quick technical reader understand the question, method, main result, and takeaway, in one paragraph and within its cap?
 2. **Introduction goal**: Does it explain the investigated problem and context, stay within scope, and end with `Question: ...?`?
 3. **Methods goal**: Could an experienced professional reproduce the important parts that materially affect the conclusion?
 4. **Results goal**: Are the findings concrete and minimally interpreted, with comparisons and pros/cons when multiple options exist?
@@ -279,8 +281,8 @@ If any check fails, revise before continuing.
 ### Phase 11: Write Files
 
 1. Create the research file at `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`.
-2. Add an entry to `.xdrs/[scope]/[type]/index.md`.
-3. Add back-references from the related Policy, article, or skill when the relationship is important for discovery.
+2. Add an entry to `.xdrs/[scope]/[type]/index.md`, with a description <15 words.
+3. Add back-references (<15 words each) from the related Policy, article, or skill when the relationship is important for discovery.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new research. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
 
 ### Phase 12: Verify with Lint

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

@@ -6,8 +6,8 @@ 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.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -28,7 +28,7 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 #### Contents
 
-- A complete SKILL.md file
+- A complete SKILL.md file (<7000 words)
 
 #### Changes
 
@@ -48,6 +48,8 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
 1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
@@ -109,29 +111,29 @@ metadata:
 
 #### Required
 
-[Bare-minimum bullets needed to invoke the skill, or a single "None" bullet. Each under 10 words.]
+[Bare-minimum bullets needed to invoke the skill, or a single "None" bullet. Each <10 words.]
 
 #### Optional
 
-[Extra helpful-context bullets, or a single "None" bullet. Each under 10 words.]
+[Extra helpful-context bullets, or a single "None" bullet. Each <10 words.]
 
 ### Outputs
 
 #### Contents
 
-[End-objective files/chat text produced, or a single "None" bullet. Each under 10 words.]
+[End-objective files/chat text produced, or a single "None" bullet. Each <10 words. Append "(<N words)" or "(uncapped: <reason>)" to natural-language items not capped in a template or step, e.g. "Release notes (<300 words)". Code and structured data get no marker.]
 
 #### Changes
 
-[End-objective external system mutations, or a single "None" bullet. Each under 10 words.]
+[End-objective external system mutations, or a single "None" bullet. Each <10 words.]
 
 ### Halt Conditions
 
-[This skill's specific stop-before-completing triggers, or a single "None" bullet. Each under 10 words.]
+[This skill's specific stop-before-completing triggers, or a single "None" bullet. Each <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.]
+[Optional. Human-in-the-loop exchanges during execution: clarifying questions or approval gates, or a single "None" bullet. Each <10 words. Omit the whole section if none apply.]
 
 ### Runtime Requirements
 
@@ -139,8 +141,10 @@ metadata:
 
 ## Instructions
 
+[Blanket cap line, e.g. "Keep every question and intermediate message <100 words and the final summary <150 words."]
+
 ### Phase 1: …
-[Step-by-step agent instructions organized into named phases. Use imperative language and include verification or acceptance criteria at the end of the task or major phases.]
+[Step-by-step agent instructions organized into named phases. Use imperative language and include verification or acceptance criteria at the end of the task or major phases. State "<N words" in each step that produces natural-language content not covered by the blanket line or a template.]
 
 ## Examples
 
@@ -166,13 +170,14 @@ Rules:
 - The `description` field must state both *what* the skill does and *when* to activate it.
 - Keep the skill task-oriented. It should have a clear starting trigger and a concrete ending result.
 - Mention tools or prerequisites when they are required to complete the task reliably.
+- Declare a "<N words" cap, or "(uncapped: <reason>)", exactly once for every natural-language content the skill generates, per **Generated content caps** in `_core-adr-policy-003`.
 - Do not duplicate content from referenced Policies — link instead.
 - Do not present the skill itself as policy; mandatory behavior must come from referenced Policies or other policy artifacts.
 - When the skill depends on Policies, make the activation logic and instructions consistent with the Policy metadata so the skill does not operationalize inactive or out-of-scope decisions.
 - 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 7000 words.
+- No emojis. Lowercase filenames.
 
 ### Phase 5: Review the Draft
 
@@ -180,12 +185,13 @@ 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 7000 words? Trim verbose explanations.
+3. **Length**: Within the SKILL.md word cap? 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. **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`.
+9. **Output caps**: Does every natural-language content the skill generates (files, messages, questions, summaries, external posts) have exactly one "<N words" cap or "(uncapped: <reason>)" marker, with code and structured data unmarked?
 
 If any check fails, revise before continuing.
 
@@ -213,6 +219,8 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - 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.
 
+## Examples
+
 **Input**: "Create a skill to help debug CI pipelines"
 - Type: EDR (engineering workflow)
 - Scope: `_local`

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

@@ -5,8 +5,8 @@ description: >
   Activate this skill when the user asks to create or write any XDRS element.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -47,6 +47,8 @@ Routes the request to the appropriate XDRS authoring skill based on the type of
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 1: Infer Document Type
 
 1. Infer the target document type from the user's request and context using the mapping below. Do not ask the user unless the type is genuinely ambiguous after reading the request.