xdrs-core 0.7.1 → 0.9.0

package/.xdrs/_core/adrs/index.md

@@ -12,6 +12,13 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-003](principles/003-skill-standards.md) - **Skill standards**
 - [_core-adr-004](principles/004-article-standards.md) - **Article standards**
 - [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages**
+- [_core-adr-006](principles/006-research-standards.md) - **Research standards**
+
+## Research
+
+Exploratory documents that back decisions during their lifecycle.
+
+- [_core-research-001](principles/researches/001-research-and-decision-lifecycle.md) - **Research and decision lifecycle** (how research supports XDRs, skills, and articles)
 
 ## Skills
 
@@ -21,9 +28,10 @@ Step-by-step procedural guides for humans and AI agents.
 - [002-write-xdr](principles/skills/002-write-xdr/SKILL.md) - **Write XDR** — create a new Decision Record
 - [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
 - [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
+- [005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
 
 ## Articles
 
-Synthetic views combining XDRs and Skills around a specific topic.
+Synthetic views combining XDRs, Research, and Skills around a specific topic.
 
 - [_core-article-001](principles/articles/001-xdrs-overview.md) - **XDRs Overview** (objective, structure, getting started, guidelines, extension, usage)

package/.xdrs/_core/adrs/principles/001-xdr-standards.md

@@ -22,11 +22,27 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 ### Implementation Details
 
 - XDRs MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references.
+- XDRs are the central artifact of the framework and the authoritative policy for their scope, type, and subject. Supporting artifacts may explain, justify, or operationalize the decision, but they do not replace it.
+- XDRs MAY include a `## Metadata` section, but only when at least one supported metadata field is present. When used, `## Metadata` MUST appear immediately before `## Context and Problem Statement`.
+- Supported XDR metadata fields are:
+  - `Applied to:` Optional. A short description of the contexts in which the decision is applicable. Keep it under 40 words. If omitted, the decision should be interpreted as applying to all logically applicable elements according to the decision text itself. Examples: `Only frontend code`, `JavaScript projects`, `Performance-sensitive codebases`
+  - `Validity:` Optional. Defines when the decision is active. Use ISO dates only: `from YYYY-MM-DD`, `until YYYY-MM-DD`, or `from YYYY-MM-DD until YYYY-MM-DD`. If `from` is omitted, the decision takes effect immediately. If `until` is omitted, the decision remains valid indefinitely. `Draft` or `Retired` mean the XDR should be ignored as an active rule or policy.
+- Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, approval, retirement, and updates, but the XDR remains the source of truth.
 - Make it clear if an instruction is mandatory or advisory
     - Mandatory language: "must", "always", "never", "required", "mandatory"
     - Advisory language: "should", "recommended", "advised", "preferably", "possibly", "optionally"
 - Always the following folder structure:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
+- Optional supporting artifacts under the same subject:
+  - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
+  - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
+  - `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
+- For simple structure, flow, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
+- Images and other supporting files SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they SHOULD live in a sibling `assets/` folder next to the document.
+  - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/assets/`
+  - Articles use `.xdrs/[scope]/[type]/[subject]/articles/assets/`
+  - Research uses `.xdrs/[scope]/[type]/[subject]/researches/assets/`
+  - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/assets/`
 - **Scopes:** 
   - examples: `business-x`, `business-y`, `team-43`, `_core`
   - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` must not be shared with or propagated to other contexts. This scope must always be placed in the lowest position in `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes.
@@ -40,6 +56,9 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
   - Types in IDs: `adr`, `bdr`, `edr`
   - Define the next number of an XDR by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted XDRs and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
 - Decisions MUST be concise and reference other XDRs to avoid duplication
+- The `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use `## Metadata` for short applicability or lifecycle markers and keep nuanced boundaries in the decision text.
+- Use concise rules, examples, or `Do` / `Don't` lists only when they help a reader apply the decision correctly. Keep them short and decision-specific.
+- When research exists for a decision, the XDR SHOULD mention the related research documents after the `## Considered Options` list.
 - Never use emojis in contents
 - Always use file names with lowercase
 - Avoid using lengthy instructions on the XDR. If there are long and detailed instructions related to the XDR, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the XDR itself.
@@ -64,6 +83,12 @@ All XDRs MUST follow this template
 ```markdown
 # [scope]-[type]-[number]: [Short Title]
 
+## Metadata
+
+[Optional section. Omit the entire section when neither `Applied to:` nor `Validity:` is defined.]
+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
 
 [Describe the context, background, or need that led to this decision.
@@ -80,7 +105,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 ### Implementation Details
 
-[Optional section with implementation specifics, rules, examples or impact. This is the answer to the question in the "Context and Problem Statement". (<100 lines)]
+[Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<100 lines)]
 
 ## Considered Options
 
@@ -92,6 +117,9 @@ Question: In the end, state explicitly the question that needs to be answered. E
   * Reason: Brief description of why this option was accepted, containing the strengths, strategical motivations and it's differential over the other options.
 * (REJECTED) **Option 3** - [same as above, if we have more than 2 options to choose from]
 
+[Related research, if any]
+- [Research document title](researches/001-example.md) - Brief description of what it informed
+
 ## Conflicts
 
 [If this XDR has conflicts with other scopes, this section is MANDATORY and needs to have an explanation why the conflict is accepted]
@@ -112,20 +140,32 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
 - `.xdrs/business-x/adrs/governance/010-security-and-secrets-management.md`
 - `.xdrs/_core/adrs/devops/001-multi-repo.md`
+- Metadata examples:
+  - `Applied to: JavaScript projects`
+  - `Validity: Draft`
+  - `Validity: from 2026-03-01 until 2026-12-31`
+
+```text
+subject/
+|-- 001-xdr.md
+|-- assets/
+|-- articles/
+|   |-- 001-article.md
+|   `-- assets/
+|-- researches/
+|   |-- 001-study.md
+|   `-- assets/
+`-- skills/
+    `-- 001-task/
+        |-- SKILL.md
+        `-- assets/
+```
 
 **XDR ID Examples:**
 - `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)
 - `business-x-edr-042` (not `EDR-BUSINESS-X-042`)
 - `business-x-bdr-007`
 
-## Procedures
-
-1. Choose the correct type (ADR, BDR, EDR), scope, and subject for each new XDR.
-2. Create the XDR using the template in the Implementation Details section above, adapting it for the chosen type and required sections.
-3. Update or create the scope `README.md` with examples if needed.
-4. Add/update the new/updated XDRs to `.xdrs/[scope]/[type]/index.md` and to the main `.xdrs/index.md`
-5. Keep decision texts short and link to other XDRs for shared rules
-
 ## Considered Options
 
 * (REJECTED) **Flat list of decisions** - Simple but becomes unmanageable as the number grows.
@@ -138,5 +178,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
 ## References
 
 - [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR from this standard
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
+- [_core-adr-006 - Research standards](006-research-standards.md)

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -26,9 +26,12 @@ Skills exist on a spectrum from fully manual (human-only) to fully automated (ag
 
 Write instructions so that each step is unambiguous and self-contained. Avoid implicit knowledge that only a human or only an AI would have.
 
-**Relation with XDRs and Articles**
-Skills are procedures, XDRs are guardrails and decisions, and Articles are synthetic views that combine information from multiple XDRs and Skills.
-Always create links back and forth between skills <-> XDRs as a reference.
+**Relation with XDRs, Research, and Articles**
+Skills are procedures, XDRs are guardrails and decisions, Research documents capture the explored option space and findings behind a decision, and Articles are synthetic views that combine information from multiple artifacts.
+Always create links back and forth between skills <-> XDRs when the relationship is direct, and link to related Research or Articles when they provide important context.
+- Skills are task-based artifacts. They should have a clear starting trigger, an expected end result, and enough detail for a human or agent to verify that the task finished correctly.
+- A skill is not policy by itself. If following a skill is mandatory, that obligation must come from an XDR or another explicit policy that references the skill.
+- Skills and XDRs have a many-to-many relationship: one skill may operationalize multiple XDRs, and one XDR may be executed through multiple skills in different contexts.
 
 Place a skill under the XDR type that matches the nature of the activity the skill performs:
 - **EDR skills** - engineering workflows, tool usage, coding procedures, implementation how-tos (e.g. how to design a webpage, how to run a CI pipeline, how to debug a service)
@@ -47,7 +50,7 @@ Quick test:
     SKILL.md              # required
     scripts/              # optional: executable scripts the agent may run
     references/           # optional: detailed reference material
-    assets/               # optional: templates, images, data files
+    assets/               # optional: images, templates, data files, and other local resources
 ```
 
 Examples:
@@ -95,6 +98,10 @@ Known gotchas and how to handle them.
 
 Rules:
 - The `name` field must match the parent directory name exactly (e.g., directory `001-code-review` uses `name: 001-code-review`). This preserves agentskills spec compliance while encoding the ordering number.
+- `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
+- `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
+- For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
+- Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and SHOULD live in `assets/` inside the same skill package.
 - Keep `SKILL.md` under 500 lines. Move lengthy reference material to `references/`.
 - Reference other files with relative paths from the skill root.
 - Always use lowercase file names.
@@ -122,3 +129,4 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]
 - [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
 - [_core-adr-001 - XDR standards](001-xdr-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
+- [_core-adr-006 - Research standards](006-research-standards.md)

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -2,23 +2,25 @@
 
 ## Context and Problem Statement
 
-As the number of XDRs and Skills grows, navigating and understanding related decisions across subjects and types becomes difficult. Without a structured format for synthetic documentation, teams create ad-hoc documents that drift from the actual decisions over time.
+As the number of XDRs, Research documents, and Skills grows, navigating and understanding related decisions across subjects and types becomes difficult. Without a structured format for synthetic documentation, teams create ad-hoc documents that drift from the actual decisions and supporting evidence over time.
 
-How should articles be structured and organized to provide useful views over XDRs and Skills without replacing them as the source of truth?
+How should articles be structured and organized to provide useful views over XDRs, Research, and Skills without replacing them as the source of truth?
 
 ## Decision Outcome
 
 **Subject-level synthetic documents co-located with XDRs**
 
-Articles are Markdown documents placed inside a subject folder alongside decision records. Placing articles within a subject keeps them close to the decisions and skills they reference.
+Articles are Markdown documents placed inside a subject folder alongside decision records. Placing articles within a subject keeps them close to the decisions, research, and skills they reference.
 
 ### Implementation Details
 
-- Articles are views, not decisions. They summarize and synthesize content from XDRs and Skills but are NOT the source of truth. When there is a conflict between an article and a Decision Record, the Decision Record takes precedence.
-- Articles must reference the XDRs and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
-- Articles may serve as indexes, combining related DRs and Skills on a specific topic into a single navigable document.
-- Articles must remain consistent with the XDRs and Skills they reference. When a referenced XDR or Skill changes, the article must be reviewed and updated.
+- Articles are views, not decisions. They summarize and synthesize content from XDRs, Research, and Skills but are NOT the source of truth. When there is a conflict between an article and a Decision Record, the Decision Record takes precedence.
+- Articles must reference the XDRs, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
+- Articles may serve as indexes, combining related artifacts on a specific topic into a single navigable document.
+- Articles must remain consistent with the XDRs, Research documents, and Skills they reference. When a referenced artifact changes, the article must be reviewed and updated.
 - Place an article in the subject folder that best matches its topic. If an article spans more than one subject, place it in `principles`.
+- For simple structure, flow, layout, or relationship indications, articles SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
+- Images and other local resource files referenced by an article SHOULD be used only when they are materially necessary and SHOULD live in `articles/assets/` next to the article files.
 - Always use lowercase file names.
 - Never use emojis in article content.
 - Articles should be kept under 150 lines. Move detailed content to referenced XDRs or Skills.
@@ -29,6 +31,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 .xdrs/[scope]/[type]/[subject]/
   articles/
     [number]-[short-title].md
+    assets/
 ```
 
 Examples:
@@ -55,7 +58,7 @@ All articles MUST follow this template:
 
 ## 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, and Skills
 when referencing an information from those documents.]
 
 ## References
@@ -76,4 +79,5 @@ when referencing an information from those documents.]
 
 - [_core-adr-001 - XDR standards](001-xdr-standards.md)
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-006 - Research standards](006-research-standards.md)
 - [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article

package/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md

@@ -2,9 +2,9 @@
 
 ## Context and Problem Statement
 
-Teams consume XDR packages as reusable guidance, constraints, skills, and articles. If package versions do not reflect the real impact of a release, upgrades become risky and teams lose trust in reuse.
+Teams consume XDR packages as reusable guidance, constraints, Research documents, skills, and articles. If package versions do not reflect the real impact of a release, upgrades become risky and teams lose trust in reuse.
 
-Question: How should semantic versioning be used when publishing or versioning a package containing XDRs, skills, and articles?
+Question: How should semantic versioning be used when publishing or versioning a package containing XDRs, Research documents, skills, and articles?
 
 ## Decision Outcome
 
@@ -28,8 +28,8 @@ XDR packages must use semantic versioning so the package version communicates th
 **MINOR**
 - Use a minor bump for backward-compatible additions and new capabilities.
 - Use a minor bump for new XDRs that do not break existing guidance.
-- Use a minor bump for new or updated articles and skill changes that extend the package without requiring consumers to undo previous adoption work.
-- Typical cases: new features, new optional guidance, new articles, expanded skills, or additive non-breaking decision coverage.
+- Use a minor bump for new or updated Research documents, articles, and skill changes that extend the package without requiring consumers to undo previous adoption work.
+- Typical cases: new features, new optional guidance, new Research documents, new articles, expanded skills, or additive non-breaking decision coverage.
 
 **PATCH**
 - Use a patch bump for low-risk fixes and simple improvements.
@@ -43,3 +43,4 @@ XDR packages must use semantic versioning so the package version communicates th
 ## References
 
 - https://semver.org/
+- [_core-adr-006 - Research standards](006-research-standards.md)

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -0,0 +1,127 @@
+# _core-adr-006: Research standards
+
+## Context and Problem Statement
+
+Teams often need more space than an XDR allows to evaluate constraints, explore options, and record findings before or after a decision changes. When that material is scattered across PR comments, docs, and chat, the reasoning behind a decision becomes hard to recover or update.
+
+Question: How should research documents be structured and organized so they communicate an investigated problem, evidence, and conclusions clearly, while remaining traceable from related XDRs?
+
+## Decision Outcome
+
+**IMRAD-based subject-level research documents co-located with XDRs**
+
+Research documents are Markdown files placed inside a subject folder alongside decision records. They use an IMRAD-inspired paper structure adapted to company needs so teams can communicate investigated problems, methods, findings, and conclusions clearly, combine experienced professional judgment with good-enough evidence, preserve reproducibility where it matters, and revisit the work when technology, constraints, or facts change.
+
+### Implementation Details
+
+- Research is evidence and exploration, not the adopted decision. When a research document and an XDR disagree, the XDR takes precedence.
+- `Research` is the artifact name. `researches/` is only the folder name used alongside `skills/` and `articles/`.
+- Research documents MUST live under `researches/` inside the relevant subject folder:
+  `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
+- Research documents SHOULD stay focused on one investigated problem, comparison, or hypothesis.
+- Research documents MUST state clearly what problem or question is being investigated, the relevant system or domain context, and why the subject matters in practice.
+- Research documents MUST follow this section order: `Abstract`, `Introduction`, `Methods`, `Results`, `Discussion`, `Conclusion`, `References`.
+- Research uses a company-adapted IMRAD structure. It MAY include informed professional judgment and experience-based observations, but claims that affect the conclusion MUST have enough evidence to be teachable, reviewable, and useful to other colleagues.
+- Research does not require full academic statistical rigor. Use good-enough evidence that supports the conclusion without demanding exhaustive proof.
+- Research documents MUST read as standalone technical papers for readers who do not know the XDR process.
+- Mentions of future ADRs, decision lifecycle, repository process, or artifact management SHOULD be avoided in the body unless they are materially necessary to understand the research question.
+- Traceability to related XDRs, skills, articles, discussions, and external sources SHOULD live primarily in `## References` and surrounding indexes rather than in the body narrative.
+- Research documents MUST describe the methods, tools, sources, and conditions with enough detail that an experienced professional could at least minimally reproduce the important parts of the study, especially the aspects that materially affected the conclusion.
+- The short title portion after the research id MUST stay under 20 words.
+- `## Abstract` MUST be a single paragraph under 200 words summarizing the goal, methods, results, and conclusion. It SHOULD let a quick technical reader understand the question, method, main result, and takeaway.
+- `## Introduction` MUST define the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives. It SHOULD prefer plain Markdown, bullet points, tables, or ASCII art for simple explanations, and SHOULD use external visuals only when they are materially necessary to improve understanding. It MUST stay under 700 words and MUST end with `Question: [central question]?`.
+- `## Methods` MUST explain how the study was conducted, including design, tools, data sources, and test conditions, with a reproducibility goal. It MUST stay under 1200 words.
+- `## Results` MUST present findings, data, trends, quantitative results, produced code, and option comparisons when relevant. It SHOULD prefer tables, bullet lists, or ASCII art for simple comparisons, and SHOULD use external figures only when they are materially necessary. Keep interpretation to a minimum. It MUST stay under 1800 words.
+- When different options for the same problem are being analyzed, `## Results` SHOULD include comparison tables and explicit pros and cons for each option so the trade-offs are directly inspectable.
+- `## Discussion` MUST interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications for technical readers. It MUST stay under 1000 words.
+- `## Conclusion` MUST summarize the main findings, practical takeaway, applicability boundaries, and important open questions. It MUST stay under 400 words.
+- `## References` MUST list all cited literature, websites, tutorials, documentation, discussions, or related artifacts.
+- In general, research SHOULD roughly follow the proportion `Introduction : Methods : Results : Discussion ≈ 3 : 5 : 6 : 4`.
+- Be strict about the goal of each section. Avoid duplicating the same material across sections and prefer clarity over rhetorical flourishes.
+- Research documents SHOULD stay under 5000 words total. They MAY exceed that only when the `## Introduction` explicitly states that the study will be lengthy because a very detailed analysis is required.
+- Research documents SHOULD link in `## References` to the XDRs, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
+- A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not required.
+- One research document MAY also be referenced by multiple XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
+- Images and other local resource files referenced by a research document SHOULD be used only when they are materially necessary and SHOULD live in `researches/assets/` next to the research files.
+- Research file names MUST be lowercase. Never use emojis.
+- A research document MAY exist before the related XDR is written, or remain after the XDR changes, as long as its status and references stay clear.
+
+**Folder layout**
+
+```
+.xdrs/[scope]/[type]/[subject]/
+  researches/
+    [number]-[short-title].md
+    assets/
+```
+
+Examples:
+- `.xdrs/_core/adrs/principles/researches/001-research-and-decision-lifecycle.md`
+- `.xdrs/business-x/adrs/platform/researches/003-api-gateway-options.md`
+- `.xdrs/_local/edrs/ai/researches/002-model-serving-constraints.md`
+
+**Research numbering**
+
+- Each research document has a number unique within its `scope/type/subject/researches/` namespace.
+- Determine the next number by checking the highest number already present in that namespace.
+- Never reuse numbers of deleted research documents. Gaps are expected.
+
+**Research template**
+
+All research documents MUST follow this template:
+
+```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.
+Prefer bullets, tables, or ASCII art for simple explanations. Use external visuals only when they are materially necessary. 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.
+Prefer tables, bullets, or ASCII art for simple comparisons. Use external figures only when they are materially necessary. 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
+```
+
+## Considered Options
+
+- Related research: [001-research-and-decision-lifecycle](researches/001-research-and-decision-lifecycle.md)
+
+* (REJECTED) **Inline long-form analysis inside the XDR** - Put all research and decision text in one file.
+  * Reason: Makes XDRs too long, mixes evidence with the adopted rule set, and hurts fast retrieval by humans and AI agents.
+* (CHOSEN) **IMRAD-based subject-level research beside XDRs** - Keep exploratory material beside the decisions, skills, and articles it informs, using an IMRAD-inspired structure adapted to company work.
+  * Reason: Preserves lifecycle context, keeps the XDR concise, gives readers a predictable structure, and raises evidence quality without demanding full academic rigor.
+
+## References
+
+- [_core-adr-001 - XDR standards](001-xdr-standards.md)
+- [_core-adr-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-004 - Article standards](004-article-standards.md)
+- [005-write-research skill](skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -8,88 +8,111 @@ the framework and links out to the authoritative Decision Records for full detai
 
 ## Content
 
-### What are XDRs?
-
-XDRs are structured Markdown documents that capture decisions made by teams. Three types exist:
-
-- **ADR (Architectural Decision Record)** — architectural and technical decisions: system context,
-  integration patterns, overarching corporate practices.
-- **BDR (Business Decision Record)** — business process, product strategy, compliance, and
-  operational decisions.
-- **EDR (Engineering Decision Record)** — engineering implementation details: library choices,
-  tooling standards, coding practices.
-
-Collectively they are called XDRs. See [_core-adr-001](../001-xdr-standards.md) for the full
-definition and mandatory template.
-
-### Objective
-
-As organizations grow, decisions accumulate across teams and domains. Without a consistent
-structure, AI agents cannot reliably locate the right decision for a given context, and humans
-struggle to maintain hundreds of documents. XDRs solve both problems by defining:
-
-- A predictable folder hierarchy that any agent can navigate.
-- Small, focused files (target under 100 lines) that are fast for LLMs to read.
-- Scope and subject grouping that limits the search space.
-- A root index as a single discovery entry point.
-
-### How it works
-
-Every XDR lives at a fixed path:
+### What the central elements are
+
+The XDR framework is built around a small set of artifact types that play different roles in the
+same decision system.
+
+- **Decision Records (XDRs)** are the authoritative decisions. They answer a concrete question and
+  record the adopted direction. They are the central policy artifact of the framework for the
+  scope and topic they cover. Three decision record types exist: **ADR** for architectural and
+  technical decisions, **BDR** for business and operational decisions, and **EDR** for engineering
+  implementation decisions. See [_core-adr-001](../001-xdr-standards.md).
+- **Research** captures exploration before or around a decision: constraints, findings, options,
+  pros, and cons. Research supports elaboration, discussion, approval, retirement, and updates,
+  but it is not the final rule. A single Research document may inform multiple downstream ADRs,
+  BDRs, or EDRs. If Research and an XDR disagree, the XDR wins. See
+  [_core-adr-006](../006-research-standards.md).
+- **Skills** describe how to execute work under the constraints of the decisions. They add the
+  procedural detail that XDRs intentionally avoid. A Skill may be used by a human, an AI agent, or
+  both. Skills are task-based, should end in a verifiable outcome, and are only mandatory when a
+  policy such as an XDR makes them mandatory. See [_core-adr-003](../003-skill-standards.md).
+- **Articles** are synthetic views, like this one. They explain a topic across multiple XDRs,
+  Research documents, and Skills, helping readers understand the system without making new
+  decisions. See [_core-adr-004](../004-article-standards.md).
+- **Indexes and folder structure** are the discovery layer. They do not make decisions by
+  themselves, but they determine how people and agents find the right artifacts, how scopes
+  override one another, and how a large set of decisions remains navigable.
+
+### How they differ
+
+The easiest way to distinguish the central elements is by asking what job each one performs.
+
+- **XDR**: "What did we decide?"
+- **Research**: "What did we learn while evaluating options?"
+- **Skill**: "How do we carry out work under this decision?"
+- **Article**: "How do these artifacts fit together for a reader?"
+- **Index/Scope structure**: "Where do I look, and which decision set takes precedence?"
+
+This separation matters because mixing these jobs into one file makes the system harder to search,
+harder to update, and harder for agents to apply correctly.
+
+### How they relate over time
+
+The framework is easiest to understand as a lifecycle rather than a static folder tree.
+
+1. **Explore** — A team starts with a problem, constraints, and uncertainty. Research is the best
+  place to compare options, record findings, and keep tradeoffs visible. That same research may
+  later support more than one decision record.
+2. **Decide** — Once a direction is chosen, an XDR captures the final answer in concise,
+  authoritative form. The XDR should make clear when the decision applies, and may link back to
+  the Research that informed its considered options.
+3. **Execute** — If the decision affects daily work, a Skill explains how to apply it in practice.
+   The Skill operationalizes the decision without turning the XDR into a procedure manual.
+4. **Explain** — When the topic becomes broad or cross-cutting, an Article synthesizes the XDR,
+   Research, and Skills into a navigable explanation for humans and agents.
+5. **Distribute and override** — Canonical indexes and scope ordering make the artifacts
+   discoverable across teams. Broader scopes can be reused, and more specific scopes can extend or
+   override them.
+
+This gives XDRs a timeline feel:
+
+- Research usually appears before or around a decision.
+- The XDR marks the adopted outcome.
+- Skills appear when the decision must be executed repeatedly.
+- Articles appear when the ecosystem around the decision needs explanation or onboarding support.
+
+### How the structure supports the model
+
+Every decision record lives at a fixed path:
 
 ```
 .xdrs/[scope]/[type]/[subject]/[number]-[short-title].md
 ```
 
-**Scopes** represent ownership domains (e.g. `_core`, `business-x`, `team-43`). `_local` is
-reserved for project-specific decisions that must not be shared externally; it always sits last
-in `.xdrs/index.md` so its decisions override all others.
-
-**Types** are `adrs`, `bdrs`, or `edrs`.
-
-**Subjects** constrain the domain further (e.g. `principles`, `application`, `devops`, `finance`).
-See [_core-adr-001](../001-xdr-standards.md) for the full allowed subject list per type.
-
-**IDs** follow the pattern `[scope]-[type abbrev]-[number]`, e.g. `_core-adr-001`. Numbers are
-never reused. Gaps in the sequence indicate deleted records.
+Supporting artifacts live beside it in the same subject:
 
-Each scope+type has a canonical `index.md` that lists all XDRs with short descriptions. A root
-`.xdrs/index.md` points to all canonical indexes and defines scope precedence (later scopes
-override earlier ones).
-
-Skills — step-by-step procedural instructions for humans and AI agents — live in `[subject]/skills/` sub-directories and are
-distributed alongside the XDRs they implement. A skill may start as a human-only procedure and evolve toward partial or full
-AI automation over time, without needing to be restructured. See [_core-adr-003](../003-skill-standards.md).
+```
+researches/[number]-[short-title].md
+skills/[number]-[skill-name]/SKILL.md
+articles/[number]-[short-title].md
+```
 
-Articles — like this document — are synthetic views that combine XDRs and Skills for a specific
-topic. They never replace the Decision Records as source of truth. See
-[_core-adr-004](../004-article-standards.md).
+- **Scopes** represent ownership domains such as `_core`, `business-x`, or `team-43`.
+- **Types** are `adrs`, `bdrs`, or `edrs`.
+- **Subjects** narrow the domain further, such as `principles`, `application`, or `finance`.
+- **Canonical indexes** list the artifacts for each scope+type, while the root `.xdrs/index.md`
+  defines precedence across scopes.
 
-### Why it is implemented this way
+This organization keeps the authoritative decision, the supporting evidence, the implementation
+guidance, and the explanatory overview close together without collapsing them into one document.
 
-Key design choices and their rationale:
+### Why this separation works
 
-- **Scoped folders over a flat list** — flat lists become unmanageable at scale; scopes give
-  clear ownership and allow selective adoption.
-- **Small focused files** — LLMs have limited context windows; small files make token budgets
-  predictable and keep decisions unambiguous.
-- **Canonical indexes** — agents read the index first to narrow the set of relevant files, rather
-  than scanning every document.
-- **npm distribution** — versioned packages let teams adopt specific decision sets at a specific
-  version without being forced to take all changes at once.
-- **Skills co-located with XDRs** — keeping procedural guidance next to the decisions it
-  implements reduces drift and makes discovery straightforward for humans and agents alike.
-  Because skills span a spectrum from fully manual to fully automated, co-location also
-  makes it easy to see when a human procedure is ready to be promoted to an agent workflow.
+- **Small focused files** keep decisions readable and agent-friendly.
+- **Research beside the XDR** preserves why options were accepted or rejected.
+- **Skills beside the XDR** reduce drift between decisions and execution.
+- **Articles above the artifacts** help readers understand the whole topic without replacing the
+  source of truth.
+- **Indexes and scopes** let the framework scale across teams while preserving override behavior.
 
 ### Getting started
 
 1. Create or open a project workspace.
 2. Run `npx xdrs-core` in the workspace root. This installs:
    - `AGENTS.md` — instructs AI agents to always consult XDRs.
-   - `AGENTS.local.md` — project-specific agent instructions (editable).
    - `.xdrs/index.md` — root index (editable, `keepExisting` mode).
-   - `_core` XDRs and skills under `.xdrs/_core/`.
+   - `_core` XDRs, Research documents, and skills under `.xdrs/_core/`.
 3. Start a conversation with your AI agent:
    > Create an ADR about our decision to use Python for AI projects.
 
@@ -100,6 +123,7 @@ Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
 - Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
   **advisory language** (`should`, `recommended`) for guidance.
 - Keep XDRs under 100 lines. Move procedural detail to a co-located Skill.
+- Keep exploratory option analysis in a co-located Research document instead of bloating the XDR.
 - Always update the scope+type index and the root index after adding or changing an XDR.
 - Use `_local` scope when a decision is project-specific and must not be shared.
 - Never reuse a number once it has been assigned, even if the XDR is deleted.
@@ -109,6 +133,8 @@ Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
 - **New scope** — create `.xdrs/[scope]/[type]/index.md` and add it to `.xdrs/index.md`.
 - **New subject** — create the subject folder under the existing scope+type path. Add an
   allowed subject or use `principles` if none fits (propose a new subject via a `_core` ADR).
+- **New research** — add a `researches/[number]-[short-title].md` inside the relevant subject
+  folder, following [_core-adr-006](../006-research-standards.md).
 - **New skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
   folder, following [_core-adr-003](../003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
@@ -120,7 +146,7 @@ Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
    `pnpm exec xdrs-core extract`) to unpack XDR files into `.xdrs/` in your workspace.
 2. **Pins and upgrades** — update the npm dependency version to pull in the latest decisions
    for a scope. The `filedist` mechanism tracks managed files in `.filedist` and keeps
-   `AGENTS.local.md` and `.xdrs/index.md` in `keepExisting` mode so local edits are preserved.
+  `.xdrs/index.md` in `keepExisting` mode so local edits are preserved.
 3. **Multi-scope** — list multiple scope packages as dependencies. Edit `.xdrs/index.md` to
    add each scope's canonical index link; place more specific scopes below broader ones.
 4. **Verify** — run `npx xdrs-core check` to confirm all managed files are in sync with the
@@ -133,6 +159,8 @@ Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
 - [_core-adr-001](../001-xdr-standards.md) - XDR standards and mandatory template
 - [_core-adr-003](../003-skill-standards.md) - Skill standards and co-location rules
 - [_core-adr-004](../004-article-standards.md) - Article standards
+- [_core-adr-006](../006-research-standards.md) - Research standards
 - [001-lint skill](../skills/001-lint/SKILL.md) - Linting code against XDRs
 - [002-write-xdr skill](../skills/002-write-xdr/SKILL.md) - Writing a new XDR
 - [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill
+- [005-write-research skill](../skills/005-write-research/SKILL.md) - Writing a new research document