xdrs-core 0.7.1 → 0.9.0

package/.xdrs/_core/adrs/principles/researches/001-research-and-decision-lifecycle.md

@@ -0,0 +1,69 @@
+# _core-research-001: Research and decision lifecycle
+
+## Overview
+
+This research evaluates how Research should fit into the XDR model so maintainers can evolve it as a supporting artifact without weakening XDRs as the source of truth. It provides the context behind the decision captured in [_core-adr-006](../006-research-standards.md).
+
+Question: How should a Research artifact fit into the XDR model so it supports the decision lifecycle without diluting the role of XDRs as the source of truth?
+
+## Constraints
+
+- XDRs must stay concise and decision-focused.
+- Supporting analysis must be easy to discover from the same subject folder.
+- The new artifact must help during elaboration, discussion, approval, retirement, and updates.
+- The structure must remain simple enough for humans and AI agents to navigate.
+
+## Findings
+
+- Long-form option analysis does not fit well inside XDRs because it mixes evidence gathering with the adopted decision.
+- Articles are useful for synthesis, but they are optimized for understanding and navigation rather than preserving the full option tradeoff study.
+- Skills are procedures, not evidence. They explain how to do something, not why an option was evaluated or rejected.
+- Subject-level co-location is the strongest predictor of discoverability in the current XDR model.
+
+## Proposals
+
+### Option 1: Keep research inside XDRs
+
+Use larger XDRs and keep all exploratory analysis in the same file as the final decision.
+
+**Pros**
+- One file per decision thread.
+- No new folder type to teach.
+
+**Cons**
+- Bloats XDRs and makes the adopted rule set harder to scan.
+- Weakens the under-100-line guidance for decision records.
+
+### Option 2: Create a top-level shared research area
+
+Store all research under a global `researches/` tree detached from subjects.
+
+**Pros**
+- Centralized catalog of studies.
+- Easy to browse all research at once.
+
+**Cons**
+- Loses proximity to the decisions it informed.
+- Makes subject-scoped discovery and maintenance harder.
+
+### Option 3: Add `researches/` beside `skills/` and `articles/`
+
+Keep research documents under the same subject as the XDR they support.
+
+**Pros**
+- Preserves context and keeps evidence close to the decision.
+- Lets XDRs stay concise while retaining detailed tradeoff history.
+
+**Cons**
+- Adds one more artifact type to explain and maintain.
+- Requires linting and indexes to recognize another optional folder.
+
+## Recommendation
+
+Option 3 is the best fit because it preserves the existing navigation model while separating evidence gathering from the adopted decision text.
+
+## References
+
+- [_core-adr-006](../006-research-standards.md) - Decision that adopts research as a first-class artifact
+- [_core-adr-001](../001-xdr-standards.md) - Base XDR structure and references
+- [_core-adr-004](../004-article-standards.md) - Distinction between research and synthesis

package/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md

@@ -24,7 +24,7 @@ Performs a structured review of code changes or files against the XDRs in the re
 
 1. Gather all Decision Records from `.xdrs/index.md` starting from the working directory.
    - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
-   - Extract metadata first (status, impact, scope, applicability) to filter relevant XDRs before deep analysis.
+   - Extract metadata first (validity status and applicability) to filter relevant XDRs before deep analysis. Treat `Validity: Draft` and `Validity: Retired` as inactive policy.
 2. Filter relevance based on file types, domains, and architectural patterns in scope.
 
 ### Phase 3: XDR Review
@@ -84,6 +84,6 @@ Scope: [scope identifier]
 
 ## References
 
-- [_core-adr-001 - XDR standards](../../001-xdr-standards.md)
-- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-001 - XDR standards](../../../.xdrs/_core/adrs/principles/001-xdr-standards.md)
+- [_core-adr-003 - Skill standards](../../../.xdrs/_core/adrs/principles/003-skill-standards.md)
 

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

@@ -10,7 +10,7 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured XDR by following the standards in `_core-adr-001`, researching existing records for conflicts, and iterating until the document is concise and decision-focused.
+Guides the creation of a well-structured XDR by following the standards in `_core-adr-001`, researching existing records for conflicts, checking redundancy across related artifacts, and iterating until the document is concise and decision-focused.
 
 ## Instructions
 
@@ -50,15 +50,30 @@ Choose a title that clearly states the question this XDR answers, not the answer
 1. Read all existing XDRs relevant to the topic across all scopes listed in `.xdrs/index.md`.
 2. Identify decisions that already address the topic (full or partial overlap).
 3. Note decisions that might conflict with the intended outcome.
-4. Collect XDR IDs and file paths for cross-references.
+4. Read related `researches/` documents when they exist, especially if they contain constraints, findings, or option tradeoffs that should influence the decision.
+5. Collect XDR IDs and file paths for cross-references.
 
-### Phase 5: Write the First Draft
+### Phase 5: Check Redundancy Across Related Artifacts
+
+1. Review the related XDRs, research documents, skills, articles, and guides connected to the same decision thread.
+2. Identify content that is repeated across those files, especially decision statements, applicability boundaries, mandatory rules, and rationale.
+3. Prioritize the final decision, core boundaries, and short key instructions in the XDR itself.
+4. When another document already explains details well, link to it instead of re-explaining the same content in full.
+5. Copy only short instructions or key excerpts when they materially help a reader apply the decision without leaving the XDR.
+6. Avoid repeating the same decision text across multiple related documents whenever a link or short reference is enough.
+
+### Phase 6: Write the First Draft
 
 Use the mandatory template from `001-xdr-standards`:
 
 ```
 # [scope]-[type]-[number]: [Short Title]
 
+## Metadata
+[Optional. Include only when at least one metadata field is present]
+Applied to: [Optional short applicability scope, under 40 words]
+Validity: [Optional. Use Draft, Retired, from YYYY-MM-DD, until YYYY-MM-DD, or from YYYY-MM-DD until YYYY-MM-DD]
+
 ## Context and Problem Statement
 [4 lines max: background, who is impacted, and the explicit question being answered]
 
@@ -68,7 +83,7 @@ Use the mandatory template from `001-xdr-standards`:
 [One sentence: what is the decision]
 
 ### Implementation Details
-[Rules, specifics, examples — under 100 lines]
+[Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 100 lines]
 
 ## Considered Options (if meaningful options exist)
 
@@ -78,32 +93,45 @@ Use the mandatory template from `001-xdr-standards`:
 ```
 
 Mandatory rules to apply while drafting:
+- Include `## Metadata` only when `Applied to:` and/or `Validity:` adds value; omit the whole section when neither field is defined.
+- When present, place `## Metadata` immediately before `## Context and Problem Statement`.
+- Keep `Applied to:` under 40 words and use `Validity:` only with ISO dates or the special values `Draft` / `Retired`.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced XDRs — link instead.
+- Keep the decision itself authoritative in the XDR. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
+- Make clear when the decision applies and any important exception boundaries.
+- Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
+- Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
+- If the XDR genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/assets/` and link with a relative path.
 - No emojis. Lowercase filenames.
 - Target under 100 lines total; 200 lines max for complex decisions.
 
-### Phase 6: Review the Draft
+### Phase 7: Review the Draft
 
 Check every item before finalizing:
 
 1. **Length**: Is it under 100 lines? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
-3. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
-4. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
-5. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
+2. **Metadata**: If metadata exists, is it directly before Context, limited to `Applied to:` / `Validity:`, and omitted entirely when both are absent?
+3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
+4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
+5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
+6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
+7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
 
 If any check fails, revise and re-run this phase before proceeding.
 
-### Phase 7: Write Files
+### Phase 8: Write Files
 
 1. Create the XDR file at `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`.
 2. Add an entry to `.xdrs/[scope]/[type]/index.md` (create the file if it does not exist).
 3. Add or verify the scope entry in `.xdrs/index.md`.
+4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
+5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Implementation Details` without turning the XDR into a long procedure.
 
 ### Constraints
 
 - MUST follow the XDR template from `001-xdr-standards` exactly.
 - MUST NOT add personal opinions or general best-practice content not tied to a decision.
 - MUST NOT create an XDR that duplicates a decision already captured in another XDR — extend or reference instead.
+- MUST prefer links and short references over repeating the same decision content across related documents.
 - MUST keep scope `_local` unless the user explicitly states otherwise.

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

@@ -18,7 +18,7 @@ Guides the creation of a well-structured skill package by following `_core-adr-0
 ### Phase 1: Understand the Skill Goal
 
 1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format, folder layout, and numbering rules.
-2. Identify what the skill must do and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal and activation trigger.
+2. Identify what the skill must do, the concrete outcome it should produce, and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal, outcome, and activation trigger.
 
 ### Phase 2: Select Type, Scope, Subject, and Number
 
@@ -47,6 +47,7 @@ Quick test:
 
 1. List `.xdrs/[scope]/[type]/[subject]/skills/` for existing skills. If one already covers the goal, extend or reference it instead of creating a duplicate.
 2. Read all XDRs relevant to the skill's domain to collect rules and cross-references.
+3. Decide whether the skill is merely guidance or is being referenced by an XDR as a mandatory procedure. Do not encode policy in the skill unless it comes from a referenced XDR.
 
 ### Phase 4: Write the SKILL.md
 
@@ -64,12 +65,12 @@ metadata:
 
 ## Overview
 
-[1–3 sentence goal statement.]
+[1–3 sentence goal statement with the task objective, expected outcome, and relevant prerequisites or tools when they matter.]
 
 ## Instructions
 
 ### Phase 1: …
-[Step-by-step agent instructions organized into named phases. Use imperative language.]
+[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.]
 
 ## Examples
 
@@ -87,7 +88,12 @@ metadata:
 Rules:
 - Use imperative language ("Read …", "Ask …", "Create …").
 - 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.
 - Do not duplicate content from referenced XDRs — link instead.
+- Do not present the skill itself as policy; mandatory behavior must come from referenced XDRs or other policy artifacts.
+- Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
+- If `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/assets/` and link with a relative path.
 - No emojis. Lowercase filenames. Target under 500 lines.
 
 ### Phase 5: Review the Draft
@@ -98,7 +104,7 @@ Before writing files, verify:
 2. **Completeness**: Does every phase have actionable steps?
 3. **Length**: Under 500 lines? Trim verbose explanations.
 4. **Duplication**: Does this overlap an existing skill? If yes, revise.
-5. **References**: Are all related XDRs and skills linked?
+5. **References**: Are all related XDRs and skills linked, including the cases where the skill operationalizes multiple XDRs?
 
 If any check fails, revise before continuing.
 

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

@@ -1,10 +1,7 @@
 ---
 name: 004-write-article
 description: >
-  Creates a new article document following XDR article standards: selects scope, type, subject, and number;
-  then writes a focused synthetic text that combines and links multiple XDRs 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 XDR project.
+   Creates a new article document following XDR article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple XDRs, 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 XDR project.
 metadata:
   author: flaviostutz
   version: "1.0"
@@ -12,8 +9,8 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured article by following `_core-adr-004`, researching the XDRs and
-Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating
+Guides the creation of a well-structured article by following `_core-adr-004`, researching the XDRs,
+Research documents, and Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating
 decision content.
 
 ## Instructions
@@ -45,7 +42,7 @@ If the article spans more than one subject, place it in `principles`.
 
 ### Phase 4: Research XDRs and Skills to Synthesize
 
-1. Read all XDRs and Skills relevant to the article topic across all scopes listed in `.xdrs/index.md`.
+1. Read all XDRs, Research documents, and Skills relevant to the article topic across all scopes listed in `.xdrs/index.md`.
 2. Identify the key points a reader needs to understand the topic end-to-end.
 3. Collect XDR IDs and file paths for cross-references. Never copy decision text verbatim; link to it.
 
@@ -62,7 +59,7 @@ Use the mandatory template from `004-article-standards`:
 
 ## Content
 
-[Synthetic text combining and explaining the topic. Use links to Decision Records and Skills
+[Synthetic text combining and explaining the topic. Use links to Decision Records, Research documents, and Skills
 when referencing information from those documents. Keep under 150 lines total.]
 
 ## References
@@ -75,6 +72,8 @@ Rules to apply while drafting:
 - Write for the stated audience; avoid jargon unexplained elsewhere.
 - Every factual claim must link back to the authoritative XDR or Skill.
 - Never reproduce decision text verbatim; summarize and link.
+- Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
+- If the article genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/articles/assets/` and link with a relative path.
 - Keep the article under 150 lines; move detailed content to XDRs or Skills.
 - Use lowercase file names. Never use emojis.
 - If a conflict exists between the article and a Decision Record, note it and defer to the XDR.
@@ -83,7 +82,7 @@ Rules to apply while drafting:
 
 1. Save the file at `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`.
 2. Add a link to the article in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
-3. Add back-references in the XDRs and Skills that the article synthesizes, under their `## References`
+3. Add back-references in the XDRs, Research documents, and Skills that the article synthesizes, under their `## References`
    section.
 
 ## Examples
@@ -95,7 +94,7 @@ Rules to apply while drafting:
 2. Topic: how skills work. Audience: developers new to the project.
 3. Scope: `_local`, type: `adrs`, subject: `principles`.
 4. Scan `.xdrs/_local/adrs/principles/articles/` — no articles exist → number is `001`.
-5. Research `_core-adr-003` and all existing skill SKILL.md files.
+5. Research `_core-adr-003`, `_core-adr-006`, and the existing skill SKILL.md files.
 6. Write `.xdrs/_local/adrs/principles/articles/001-skills-overview.md` following the template, linking
    to `_core-adr-003` and the individual skill files.
 7. Update `.xdrs/_local/adrs/index.md` with a link to the new article.
@@ -108,4 +107,10 @@ Rules to apply while drafting:
 - **Cross-subject topic** — place the article in `principles`, not in any single subject folder.
 - **No existing articles folder** — create it; it is optional in the folder layout.
 - **Conflicting information found** — note the conflict in the article and always defer to the XDR.
-- **Article would exceed 150 lines** — move detailed content to a new Skills or XDR and link back.
+- **Article would exceed 150 lines** — move detailed content to a new Research, Skill, or XDR and link back.
+
+## References
+
+- [_core-adr-004 - Article standards](../../004-article-standards.md)
+- [_core-adr-006 - Research standards](../../006-research-standards.md)
+- [_core-adr-001 - XDR standards](../../001-xdr-standards.md)

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

@@ -0,0 +1,256 @@
+---
+name: 005-write-research
+description: >
+  Creates a new research document following XDR research standards: selects scope, type, subject, and number;
+  then writes an IMRAD-based study with enough evidence and method detail to stand on its own as a technical paper.
+  Activate this skill when the user asks to create, add, or write a research document that backs a decision.
+metadata:
+  author: flaviostutz
+  version: "1.3"
+---
+
+## Overview
+
+Guides the creation of a well-structured research document by following `_core-adr-006`, checking related XDRs and existing research to avoid duplication, and producing an IMRAD-based study that reads as a standalone technical paper. Treat each section goal in the research template as an acceptance criterion, not as optional wording. Do not assume missing direction, evidence, or intended follow-up; ask the user explicitly before proceeding when those points are not already concrete.
+
+## Instructions
+
+### Phase 1: Understand the Research Goal
+
+1. Read `.xdrs/_core/adrs/principles/006-research-standards.md` in full to internalize the folder layout, numbering rules, and mandatory template.
+2. Ask the user to confirm the intended direction of the research before planning the document: what decision, question, or option space the study should support, what boundaries or exclusions apply, and what kind of outcome they expect.
+3. Ask the user what evidence already exists and what evidence-gathering methods are acceptable if the current evidence is incomplete. Do not invent facts, sources, or confidence that the user did not provide.
+4. Ask the user what the proposed next step is after the research, such as writing a new XDR, updating an existing XDR, informing a discussion, or documenting trade-offs for later. Use that answer to shape the framing without turning the research into the final decision.
+5. Identify the problem or question being explored, the relevant system or domain context, the likely technical audience, and why the subject matters in practice.
+6. Internalize the goal of each required section before drafting: `Abstract` gives a quick technical reader the question, method, main result, and takeaway, `Introduction` frames the investigated problem and context, `Methods` makes the important parts reproducible, `Results` records raw findings with minimal interpretation, `Discussion` interprets the findings, `Conclusion` summarizes the practical takeaway and boundaries, and `References` makes sources traceable.
+7. Collect the main constraints, known facts, important experiences, gaps, and assumptions that belong in the introduction.
+8. Do NOT proceed without a clear problem statement, a central question, explicit user direction, an understood next step, and at least one credible source of evidence or a method for generating it. If any of these are ambiguous, stop and ask instead of assuming.
+
+### Phase 2: Select Scope, Type, Subject, and Number
+
+**Scope** — use `_local` unless the user explicitly names another scope.
+
+**Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`).
+
+**Subject** — pick the most specific subject that matches the problem domain.
+
+**Research number** — scan `.xdrs/[scope]/[type]/[subject]/researches/` for the highest existing number and increment by 1. Never reuse numbers from deleted research documents.
+
+### Phase 3: Research Existing Artifacts
+
+1. Read relevant XDRs across all scopes listed in `.xdrs/index.md`.
+2. Read existing research documents in the same or overlapping subjects to avoid duplicating the same study.
+3. Read related skills or articles if they contain context, implementation limits, or terminology that must be reflected.
+4. Collect links that should appear in the final `## References` section.
+
+### Phase 4: Create the Skeleton and Frame the Study
+
+1. Create the final section skeleton in the research file before running the study: `Abstract`, `Introduction`, `Methods`, `Results`, `Discussion`, `Conclusion`, `References`.
+2. Write a one-line note under each section heading capturing that section's goal before filling in the content so the draft stays disciplined.
+3. Draft `## Introduction` early so the problem, scope, constraints, assumptions, and central question are fixed before evidence collection expands.
+4. Draft `## Methods` before or while executing the study so tools, data sources, and conditions are captured while they are still precise.
+5. Treat `## Abstract` as a late-stage summary. Do not try to finalize it yet.
+6. Keep process framing out of the body. If related ADRs or repository context matter, push that traceability to `## References` unless it is essential to the technical question itself.
+
+### Phase 5: Capture Evidence as the Study Runs
+
+1. As experiments, comparisons, code spikes, interviews, benchmarks, or document reviews happen, append the concrete findings to `## Results` continuously.
+2. Prefer capturing tables, bullet points, numbers, code outputs, and option comparisons while the evidence is fresh.
+3. If multiple options solve the same problem, add a comparison table and explicit pros and cons for each option in `## Results` so the trade-offs are directly inspectable.
+4. Update `## Methods` whenever the actual study design changes so the final document remains reproducible.
+5. Keep interpretation out of `## Results`; record observations first and save meaning-making for `## Discussion`.
+
+### Phase 6: Synthesize After Results Stabilize
+
+1. Write `## Discussion` only after the important findings are visible in `## Results`.
+2. Use `## Discussion` to interpret significance, trade-offs, limitations, implications, and performance considerations for technical readers.
+3. Write `## Conclusion` after the discussion so it reflects the actual findings, practical takeaway, applicability boundaries, and open questions.
+4. Write `## Abstract` last so it accurately summarizes the final goal, methods, results, and conclusion for quick technical readers.
+
+### Phase 7: Write the Research Document
+
+Use the mandatory template from `006-research-standards`:
+
+```markdown
+# [scope]-research-[number]: [Short Title]
+
+## 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.]
+
+## 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.]
+
+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.]
+
+## 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.]
+
+## 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.]
+
+## 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.]
+
+## References
+
+[A list of all cited literature, websites, tutorials, documentation, discussions, and related artifacts. Goal: make all cited sources and supporting artifacts traceable.]
+
+- [Related XDR or artifact](relative/path.md) - Why it matters
+- [Another related XDR if this research informed multiple decisions](relative/path.md) - Why it matters
+```
+
+Rules:
+- Treat the goal sentence of each section as a hard check on what belongs in that section.
+- Focus on exploring and evidencing the problem space; do not turn the document into the final decision.
+- Write as a standalone technical paper for readers who do not know the XDR process.
+- Keep mentions of future ADRs, decision lifecycle, repository process, or artifact management out of the body unless they are materially necessary to understand the research question.
+- Keep traceability to related XDRs, skills, articles, discussions, and external sources primarily in `## References`.
+- Use good-enough evidence. Experienced professional judgment is allowed, but the conclusions still need support that other colleagues can inspect and learn from.
+- Ensure the methods and test conditions are reproducible enough for an experienced professional to rerun or evolve the critical parts later.
+- Prefer plain Markdown, bullet points, tables, or ASCII art for simple explanations and comparisons, especially in the introduction and results.
+- If the research genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/researches/assets/` and link with a relative path.
+- 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.
+
+### 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?
+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?
+5. **Discussion goal**: Does it interpret the findings rather than repeat the results?
+6. **Conclusion goal**: Does it summarize the main findings, practical takeaway, applicability boundaries, and open questions without introducing new evidence?
+7. **References goal**: Are cited sources and related artifacts traceable, including related XDRs, skills, articles, and research where relevant?
+
+If any section fails its goal, revise that section before continuing.
+
+### Phase 9: Check Word Counts and Ratios
+
+Before the final review, run a word-count pass over the draft and verify that the main body roughly follows the standard proportion `Introduction : Methods : Results : Discussion ≈ 3 : 5 : 6 : 4`.
+
+1. Count words by top-level `##` section after stripping Markdown syntax so lists, tables, and links count as prose rather than punctuation.
+2. Compare only `Introduction`, `Methods`, `Results`, and `Discussion` for the ratio check.
+3. Use these target shares of the main body: `Introduction = 16.7%`, `Methods = 27.8%`, `Results = 33.3%`, `Discussion = 22.2%`.
+4. Treat any section as out of ratio when its share differs by more than 25% from its target share, unless the `## Introduction` explicitly justifies a very detailed or intentionally unbalanced analysis.
+5. If the ratio check fails, rebalance the draft before final review instead of accepting the imbalance silently.
+6. Use this Python script when you need a fast deterministic check:
+
+```python
+from pathlib import Path
+import re
+
+path = Path(".xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md")
+text = path.read_text(encoding="utf-8")
+
+sections = {}
+current = None
+for line in text.splitlines():
+  if line.startswith("## "):
+    current = line[3:].strip()
+    sections[current] = []
+    continue
+  if line.startswith("# "):
+    continue
+  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)
+  cleaned = re.sub(r"```[\s\S]*?```", " ", cleaned)
+  cleaned = re.sub(r"`([^`]*)`", r"\1", cleaned)
+  cleaned = re.sub(r"!\[([^\]]*)\]\([^)]*\)", r"\1", cleaned)
+  cleaned = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", cleaned)
+  cleaned = re.sub(r"^#+\s+", "", cleaned, flags=re.M)
+  cleaned = re.sub(r"[|*_>#-]", " ", cleaned)
+  cleaned = re.sub(r"[^\w'’]+", " ", cleaned, flags=re.UNICODE)
+  words = cleaned.strip().split()
+  return len(words)
+
+
+targets = {
+  "Introduction": 3,
+  "Methods": 5,
+  "Results": 6,
+  "Discussion": 4,
+}
+
+counts = {name: count_words("\n".join(lines)) for name, lines in sections.items()}
+total_words = sum(counts.values())
+body_total = sum(counts.get(name, 0) for name in targets)
+target_weight_total = sum(targets.values())
+
+print(f"TOTAL\t{total_words}")
+for name, count in counts.items():
+  print(f"{name}\t{count}")
+
+print("\nRATIO CHECK")
+for name, weight in targets.items():
+  actual_share = counts.get(name, 0) / body_total if body_total else 0
+  target_share = weight / target_weight_total
+  delta = ((actual_share - target_share) / target_share) if target_share else 0
+  status = "OK" if abs(delta) <= 0.25 else "REVISE"
+  print(
+    f"{name}: actual={actual_share:.1%} target={target_share:.1%} delta={delta:+.1%} {status}"
+  )
+```
+
+### Phase 10: Review the Draft
+
+Before writing files, verify:
+
+1. **Problem clarity**: Is the research question explicit?
+2. **Section discipline**: Does each section contain the right kind of content with minimal duplication?
+3. **Method quality**: Could an experienced professional reproduce or extend the important parts of the study from the methods section?
+4. **Evidence quality**: Are the results concrete enough to support the discussion and conclusion?
+5. **Standalone focus**: Does the text read as a technical paper rather than commentary about future ADRs, repository process, or artifact management?
+6. **Ratio fit**: Does the document stay within section word limits and pass the Python ratio check, or does the introduction explicitly justify the deviation?
+7. **References**: Are all related XDRs, research docs, skills, articles, and external sources linked when relevant?
+
+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 XDR, article, or skill when the relationship is important for discovery.
+
+## Examples
+
+**Input**: "Create research comparing package distribution options for our XDR scopes"
+
+**Expected actions:**
+1. Read `006-research-standards.md`.
+2. Choose type `adrs` and subject `principles`.
+3. Scan `.xdrs/_local/adrs/principles/researches/` for the next number.
+4. Read related XDRs about packaging and versioning.
+5. Write an IMRAD-based research document comparing options such as npm package, git submodule, and copy-paste distribution, with the comparison grounded in methods and results.
+6. Add references to the resulting XDR if a decision is later created.
+
+## Edge Cases
+
+- If the user is really asking for a final decision, write an XDR instead of research.
+- If only one viable option exists, still explain what was evaluated, what was ruled out, or what constraints removed the alternatives.
+- If the document grows too large, split independent problem threads into separate research files unless the introduction explicitly justifies a longer study.
+- If the supported decision does not exist yet, reference the decision topic or planned XDR 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-006 - Research standards](../../006-research-standards.md)
+- [_core-adr-001 - XDR standards](../../001-xdr-standards.md)
+- [002-write-xdr skill](../002-write-xdr/SKILL.md)

package/AGENTS.md

@@ -19,6 +19,4 @@
 5. **Do not perform git operations unless explicitelly asked**
    - The developer should be in control of possible destructive operations on the workspace
 
-Check for additional instructions on [AGENTS.local.md](AGENTS.local.md).
-
 **This AGENTS.md file was created with xdrs-core and shouldn't be changed**