xdrs-core 0.7.0 → 0.8.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,17 @@ 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.
+- 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`
 - **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 +46,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 when the decision applies, relevant boundaries or exceptions, and what a reader should do or avoid in common cases.
+- 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.
@@ -80,7 +89,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 +101,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]
@@ -118,14 +130,6 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - `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 +142,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)
@@ -95,6 +98,8 @@ 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.
 - 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 +127,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,22 +2,22 @@
 
 ## 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`.
 - Always use lowercase file names.
 - Never use emojis in article content.
@@ -55,7 +55,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 +76,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,119 @@
+# _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 support the decision lifecycle without replacing XDRs as the source of truth?
+
+## Decision Outcome
+
+**subject-level research documents co-located with XDRs**
+
+Research documents are Markdown files placed inside a subject folder alongside decision records. They capture the explored option space, relevant constraints, findings, and proposal tradeoffs that back a decision during elaboration, discussion, approval, retirement, and updates.
+
+### 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 problem statement or decision thread.
+- Research documents MUST state clearly what problem or question is being investigated and who needs the result.
+- The `## Overview` section MUST end with a line in the form `Question: [central question]?` that states the central question the research answers.
+- Research constraints MAY include hard requirements, stack limitations, regulatory limits, or other conditions that narrow the option space.
+- Research documents MUST summarize the problem constraints, important findings, and a small set of proposals with pros and cons for each option.
+- Research proposals are the considered options for the decision thread. They are not the final policy.
+- Research documents SHOULD link to the XDRs, skills, articles, discussions, and external references they informed.
+- One research document MAY inform multiple XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation produced several downstream decisions.
+- Research documents SHOULD remain concise enough to read end-to-end. Target under 500 lines; hard limit 2000 lines.
+- 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
+```
+
+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]
+
+## Overview
+
+[Brief description of the problem or question being explored, who needs the result, and the decision thread(s) it supports. Under 5 lines.]
+
+Question: [Central question of the research]?
+
+## Constraints
+
+- [Constraint or requirement 1]
+- [Constraint or requirement 2]
+
+## Findings
+
+- [Important finding 1]
+- [Important finding 2]
+
+## Proposals
+
+### Option 1: [Name]
+
+[Short description of the option.]
+
+**Pros**
+- [Benefit 1]
+- [Benefit 2]
+
+**Cons**
+- [Drawback 1]
+- [Drawback 2]
+
+### Option 2: [Name]
+
+[Same structure as above for each meaningful option.]
+
+## Recommendation
+
+[Optional summary of the currently preferred direction, if any.]
+
+## References
+
+- [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.
+* (REJECTED) **Separate top-level research area outside the subject tree** - Centralize all research in one independent folder.
+  * Reason: Breaks proximity with the decisions it supports and makes subject-scoped discovery weaker.
+* (CHOSEN) **Subject-level research folder co-located with XDRs** - Keep exploratory material beside the decisions, skills, and articles it informs.
+  * Reason: Preserves lifecycle context, keeps the XDR concise, and makes the research easy to discover when revisiting or updating a decision.
+
+## 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

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/002-write-xdr/SKILL.md

@@ -50,7 +50,8 @@ 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
 
@@ -68,7 +69,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)
 
@@ -80,6 +81,8 @@ Use the mandatory template from `001-xdr-standards`:
 Mandatory rules to apply while drafting:
 - 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.
+- 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.
 - No emojis. Lowercase filenames.
 - Target under 100 lines total; 200 lines max for complex decisions.
 
@@ -100,6 +103,8 @@ If any check fails, revise and re-run this phase before proceeding.
 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
 

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,10 @@ 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.
 - No emojis. Lowercase filenames. Target under 500 lines.
 
 ### Phase 5: Review the Draft
@@ -98,7 +102,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,8 +1,9 @@
 ---
 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.
+   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:
@@ -12,8 +13,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 +46,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 +63,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
@@ -83,7 +84,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 +96,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 +109,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,132 @@
+---
+name: 005-write-research
+description: >
+  Creates a new research document following XDR research standards: selects scope, type, subject, and number;
+  then writes a focused study of constraints, findings, and option proposals with pros and cons.
+  Activate this skill when the user asks to create, add, or write a research document that backs a decision.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## 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 a concise study that supports a decision lifecycle without replacing the XDR.
+
+## 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. Identify the problem or question being explored, the main constraints or requirements, and which decision or decision threads this research supports.
+3. Do NOT proceed without a clear problem statement and at least one concrete constraint or requirement.
+
+### 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: Write the Research Document
+
+Use the mandatory template from `006-research-standards`:
+
+```markdown
+# [scope]-research-[number]: [Short Title]
+
+## Overview
+
+[Brief description of the problem or question, audience, and decision thread(s) it supports.]
+
+Question: [Central question of the research]?
+
+## Constraints
+
+- [Constraint 1]
+
+## Findings
+
+- [Finding 1]
+
+## Proposals
+
+### Option 1: [Name]
+
+[Short description]
+
+**Pros**
+- [Benefit]
+
+**Cons**
+- [Drawback]
+
+## Recommendation
+
+[Optional preferred direction]
+
+## References
+```
+
+Rules:
+- Focus on exploring options under stated constraints; do not turn the document into the final decision.
+- End the `## Overview` section with `Question: [central question]?` so the main research question is explicit.
+- Make it explicit when the same research may feed multiple downstream XDRs.
+- Include a few meaningful proposals and summarize pros and cons for each.
+- Keep findings concrete and useful for later discussion or revision.
+- Keep the document under 2000 lines. Prefer much shorter when possible.
+- Treat `Research` as the artifact name; `researches/` is only the folder name.
+- Use lowercase file names. Never use emojis.
+
+### Phase 5: Review the Draft
+
+Before writing files, verify:
+
+1. **Problem clarity**: Is the research question explicit?
+2. **Constraints**: Are the most important constraints stated clearly?
+3. **Option quality**: Do the proposals represent real alternatives with non-trivial pros and cons?
+4. **Decision boundary**: Does the text support a decision without pretending to be the XDR itself?
+5. **References**: Are all related XDRs, research docs, skills, or articles linked, including multiple decisions when applicable?
+
+If any check fails, revise before continuing.
+
+### Phase 6: 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 a research document with constraints, findings, and options such as npm package, git submodule, and copy-paste distribution.
+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 record why alternatives were excluded or unavailable.
+- If the document grows too large, split independent problem threads into separate research files.
+- If the supported decision does not exist yet, reference the decision topic or planned XDR title in the overview.
+
+## 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/.xdrs/index.md

@@ -21,4 +21,4 @@ Decisions about how XDRs work
 
 Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Add specific `_local` ADR/BDR/EDR index links here when present.
 
-[View local ADRs Index](_local/adrs/index.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**

package/README.md

@@ -12,11 +12,12 @@ This project defines a standard for organizing XDRs that satisfies the following
 
 ## XDR elements
 
-Every XDR package contains three types of documents:
+Every XDR package contains four types of documents:
 
 - **Decision Records (XDRs)** — Architectural (ADR), Business (BDR), or Engineering (EDR) records that capture a single decision, its rationale, and the rules that follow from it. They are the source of truth.
-- **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time. Co-located with the XDRs they implement.
-- **Articles** — Synthetic explanatory texts that combine information from multiple XDRs and Skills around a specific topic or audience. They never replace XDRs as source of truth.
+- **Research** — Exploratory documents that capture the problem being investigated, constraints or requirements, findings, and option tradeoffs that back a decision during its lifecycle. One research document may inform multiple downstream decisions, but it is not a replacement for the Decision Record.
+- **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. Skills are task-based artifacts with a concrete outcome and should include enough detail to verify the task was completed correctly. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time. Co-located with the XDRs they implement.
+- **Articles** — Synthetic explanatory texts that combine information from multiple XDRs, Research documents, and Skills around a specific topic or audience. They never replace XDRs as source of truth.
 
 ## Getting started
 
@@ -51,6 +52,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - XDR numbering uniqueness per `scope/type`
 - skill numbering uniqueness per `scope/type/subject/skills`
 - article numbering uniqueness per `scope/type/subject/articles`
+- research numbering uniqueness per `scope/type/subject/researches`
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
 
@@ -106,10 +108,12 @@ This is especially important for BDRs: because business rules govern decisions t
       index.md                      # canonical index for this scope+type
       [subject]/
         [number]-[short-title].md   # individual decision record
+        researches/                 # optional decision-backing research documents
+          [number]-[short-title].md
         skills/                     # optional skill packages for humans and AI agents
           [number]-[skill-name]/
             SKILL.md
-        articles/                   # optional synthetic views over XDRs and Skills
+        articles/                   # optional synthetic views over XDRs, Research, and Skills
           [number]-[short-title].md
 ```
 
@@ -118,31 +122,32 @@ Document types:
 - **ADR** - Architectural Decision Record: architectural and technical decisions
 - **BDR** - Business Decision Record: business process and strategy decisions
 - **EDR** - Engineering Decision Record: engineering workflow and tooling decisions
-- **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Decision Records, but add the execution detail they lack. A skill may start as a fully manual human procedure and evolve incrementally toward partial or full AI automation without being restructured. Co-located with the XDRs they implement inside `skills/` sub-directories.
-- **Articles** - Synthetic views that explain concepts or combine information from multiple Decision Records and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Decision Records take precedence when there is a conflict. Useful as navigational indexes that link related DRs and Skills around a specific aspect.
+- **Research** - Exploratory support material used while evaluating or updating a decision. Research captures constraints, findings, options, and proposal tradeoffs, but it is not the source of truth.
+- **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Decision Records, but add the execution detail they lack. Skills are not mandatory by themselves unless referenced by an XDR or another policy artifact. A skill may start as a fully manual human procedure and evolve incrementally toward partial or full AI automation without being restructured. Co-located with the XDRs they implement inside `skills/` sub-directories.
+- **Articles** - Synthetic views that explain concepts or combine information from multiple Decision Records, Research documents, and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Decision Records take precedence when there is a conflict. Useful as navigational indexes that link related artifacts around a specific aspect.
 
 See [.xdrs/index.md](.xdrs/index.md) for the full list of active decision records.
 
 For a deeper overview of XDRs — objective, structure, guidelines, extension, and usage — see the [XDRs Overview article](.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md).
-For packaging guidance on publishing your own reusable scope with DRs, skills, and articles, see the [Create your own xdrs-core extension package article](.xdrs/_local/adrs/principles/articles/001-create-your-own-xdrs-extension-package.md), then compare [examples/basic-usage](examples/basic-usage) and [examples/mydevkit](examples/mydevkit).
+For packaging guidance on publishing your own reusable scope with DRs, Research documents, skills, and articles, see the [Create your own xdrs-core extension package article](docs/create-your-own-xdrs-extension-package.md), then compare [examples/basic-usage](examples/basic-usage) and [examples/mydevkit](examples/mydevkit).
 
 ## Flow: Decision -> Distribution -> Usage
 
-XDRs and skills follow a three-stage lifecycle that keeps decision-making decentralized while allowing controlled adoption across projects.
+XDRs, Research documents, and skills follow a three-stage lifecycle that keeps decision-making decentralized while allowing controlled adoption across projects.
 
 ### Decision
 
-Each scope manages its own set of XDRs independently. Scope owners discuss and evolve decisions through whatever process fits their team, such as RFCs, pull requests, or architecture review boards. XDRs and skills are authored, reviewed, and merged within the scope's folder in the repository.
+Each scope manages its own set of XDR artifacts independently. Scope owners discuss and evolve decisions through whatever process fits their team, such as RFCs, pull requests, or architecture review boards. Research documents, XDRs, and skills are authored, reviewed, and merged within the scope's folder in the repository.
 
 ### Distribution
 
 Once a set of decisions is ready to share, scope owners pack the relevant `.xdrs/[scope]/` folder into a versioned npm package using a tool such as [filedist](https://github.com/flaviostutz/filedist) and publish it to an npm registry, either public or a company-internal one. Versioning gives consumers explicit control over which revision of a scope's decisions they adopt, avoiding situations where a single breaking policy change is forced on all consumers at once.
 
-The same applies to skills: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
+The same applies to Research documents and skills: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
 
 ### Usage
 
-A project that wants to follow a scope's decisions adds the corresponding npm package as a regular dependency. Using a tool such as [filedist](https://github.com/flaviostutz/filedist), the package contents are unpacked into the project's `.xdrs/` folder at install or update time. Updating the dependency version pulls in the latest XDRs and skills for that scope, keeping the project aligned with the scope owners' current decisions.
+A project that wants to follow a scope's decisions adds the corresponding npm package as a regular dependency. Using a tool such as [filedist](https://github.com/flaviostutz/filedist), the package contents are unpacked into the project's `.xdrs/` folder at install or update time. Updating the dependency version pulls in the latest XDRs, Research documents, and skills for that scope, keeping the project aligned with the scope owners' current decisions.
 
 Multiple scope packages can be combined in the same workspace by listing them as separate dependencies. Scope precedence (defined in `.xdrs/index.md`) determines which decisions take effect when scopes overlap.
 
@@ -152,6 +157,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
     adrs/ bdrs/ edrs/                                                adrs/ bdrs/ edrs/
     [subject]/                                                        [subject]/
       *.md                                                              *.md
+      researches/                                                       researches/
       skills/                                                           skills/
       articles/                                                         articles/
 ```

package/lib/lint.js

@@ -21,6 +21,7 @@ const RESERVED_SCOPES = new Set(['_core', '_local']);
 const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
 const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRs in scopes listed last override the ones listed first';
+const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches']);
 
 function runLintCli(args) {
   if (args.includes('--help') || args.includes('-h')) {
@@ -198,6 +199,10 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
         artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
+      if (entry.name === 'researches') {
+        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        continue;
+      }
 
       errors.push(`Unexpected directory under ${scopeName}/${typeName}/${subjectName}: ${toDisplayPath(entryPath)}`);
       continue;
@@ -335,6 +340,49 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
   return artifacts;
 }
 
+function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors) {
+  const artifacts = [];
+  const researchNumbers = new Map();
+  const entries = safeReadDir(researchPath, errors, `read research directory ${scopeName}/${typeName}/${subjectName}/researches`);
+
+  for (const entry of entries) {
+    const entryPath = path.join(researchPath, entry.name);
+    if (!entry.isFile()) {
+      errors.push(`Unexpected directory in researches folder: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    const match = entry.name.match(NUMBERED_FILE_RE);
+    if (!match) {
+      errors.push(`Invalid research file name: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    artifacts.push(entryPath);
+
+    const number = match[1];
+    const previous = researchNumbers.get(number);
+    if (previous) {
+      errors.push(`Duplicate research number ${number} in ${scopeName}/${typeName}/${subjectName}/researches: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)}`);
+    } else {
+      researchNumbers.set(number, entryPath);
+    }
+
+    if (entry.name !== entry.name.toLowerCase()) {
+      errors.push(`Research file name must be lowercase: ${toDisplayPath(entryPath)}`);
+    }
+
+    const content = fs.readFileSync(entryPath, 'utf8');
+    const expectedHeader = `# ${scopeName}-research-${number}:`;
+    const firstLine = firstNonEmptyLine(content);
+    if (!firstLine.startsWith(expectedHeader)) {
+      errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
+    }
+  }
+
+  return artifacts;
+}
+
 function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   const content = fs.readFileSync(indexPath, 'utf8');
   const localLinks = parseLocalLinks(content, path.dirname(indexPath));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.",
   "repository": {
     "type": "git",
@@ -17,7 +17,6 @@
     ".xdrs/**",
     "package.json",
     "AGENTS.md",
-    "AGENTS.local.md",
     "bin/filedist.js",
     "lib/**/*.js"
   ],
@@ -30,10 +29,7 @@
         "selector": {
           "files": [
             "AGENTS.md",
-            ".xdrs/**"
-          ],
-          "exclude": [
-            ".xdrs/index.md"
+            ".xdrs/_core/**"
           ]
         },
         "output": {
@@ -50,8 +46,7 @@
       {
         "selector": {
           "files": [
-            ".xdrs/index.md",
-            "AGENTS.local.md"
+            ".xdrs/index.md"
           ]
         },
         "output": {

package/.xdrs/_local/adrs/index.md

@@ -1,11 +0,0 @@
-# local ADRs Index
-
-This index covers project-local architectural documentation for this repository. These documents
-are not meant to be distributed as reusable scope packages unless they are promoted into a named
-shared scope.
-
-## Articles
-
-Synthetic views combining XDRs, repository examples, and packaging guidance.
-
-- [_local-article-001](principles/articles/001-create-your-own-xdrs-extension-package.md) - **Create your own xdrs-core extension package** (package layout, filedist sets, publishing, versioning, and consumer overrides)

package/.xdrs/_local/adrs/principles/articles/001-create-your-own-xdrs-extension-package.md

@@ -1,123 +0,0 @@
-# _local-article-001: Create your own xdrs-core extension package
-
-## Overview
-
-This article explains how to turn your own XDR scope into a distributable npm package. It is for
-teams that want to publish their own DRs, skills, and articles while staying compatible with the
-xdrs-core structure and extraction flow.
-
-## Content
-
-### Start with a real shared scope, not `_local`
-
-Use `_local` only for project-only records that must stay inside one repository. Shared packages
-should publish a named scope such as `acme-platform` or `team-ml`, because scopes are the unit of
-ownership, distribution, and override ordering in XDRs. The root structure and precedence rules are
-defined in [_core-adr-001](../../../../_core/adrs/principles/001-xdr-standards.md).
-
-### Package the whole scope as a normal npm package
-
-The package shape used by this repository is the simplest reference implementation: the published
-artifact is a regular npm package with a `files` whitelist, a thin CLI entrypoint, and `filedist`
-configuration embedded in [package.json](../../../../../package.json). The important parts are:
-
-- include the shipped XDR tree, agent instruction files, and CLI files in `files`
-- expose `bin/filedist.js` as the package `bin` so consumers run the package through the same
-  `extract` and `check` interface
-- define one `filedist.sets` entry for managed files and another for editable local overrides
-
-For a minimal consumer flow, see [example/package.json](../../../../../example/package.json) and
-[example/Makefile](../../../../../example/Makefile).
-
-### Separate managed files from local overrides
-
-This repository's `filedist` config in [package.json](../../../../../package.json) shows the key
-pattern:
-
-- managed set: ships `AGENTS.md` and `.xdrs/**`, while excluding `.xdrs/index.md`
-- keep-existing set: ships `.xdrs/index.md` and `AGENTS.local.md` with `managed=false` and
-  `keepExisting=true`
-
-That split matters because consumers need some files to stay under package control and others to
-remain editable in their own repository. The current example verifies exactly that behavior by
-re-extracting into [example/output](../../../../../example/output) and asserting that local edits to
-`.xdrs/index.md` survive `extract --keep-existing` while managed files are still checked for drift in
-[example/Makefile](../../../../../example/Makefile).
-
-### Keep DRs, skills, and articles together
-
-Your reusable package should place DRs, skills, and articles under the same scope folder so they
-ship together:
-
-```text
-.xdrs/
-  my-scope/
-    adrs/
-      index.md
-      principles/
-        001-my-decision.md
-        skills/
-          001-my-skill/SKILL.md
-        articles/
-          001-my-overview.md
-```
-
-The co-location rule for skills comes from [_core-adr-003](../../../../_core/adrs/principles/003-skill-standards.md),
-and article placement rules come from [_core-adr-004](../../../../_core/adrs/principles/004-article-standards.md).
-When you publish the scope folder, those documents travel together and stay version-aligned.
-
-### Expose skills to Copilot-compatible tooling
-
-This repository's managed `filedist` set creates symlinks from `.xdrs/**/skills/*` into
-`.github/skills`, configured in [package.json](../../../../../package.json). That means your skills
-remain authored next to the XDRs they implement, but consumers also get the discovery path expected
-by GitHub Copilot and similar tooling.
-
-If your package targets non-Copilot agents too, keep the source of truth in `.xdrs/[scope]/.../skills/`
-and treat `.github/skills` as an exposure mechanism rather than the canonical location.
-
-### Verify with a consumer example before publishing
-
-The [example](../../../../../example) folder is the best reference in this repository for the
-consumer side of the workflow:
-
-1. depend on the locally packed tarball from `dist/`
-2. run `pnpm exec xdrs-core extract --output ./output`
-3. verify the expected files exist
-4. re-run extraction to confirm keep-existing behavior
-5. run `check` and `lint` against the extracted tree
-
-That same pattern should exist in your extension package repository. A runnable example catches bad
-selectors, missing files, broken indexes, and skill exposure problems before you publish.
-
-### Publish and version the package as an upgrade contract
-
-The release flow in [Makefile](../../../../../Makefile) packs the project and publishes it with npm,
-including prerelease tag handling. Your extension package can follow the same shape: `pnpm pack` for
-local verification, then `npm publish` to your public or internal registry.
-
-Version the package with semantic versioning according to the impact on consumers, not only on the
-changed file. [_core-adr-005](../../../../_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md)
-defines the practical rule: breaking guidance or changed mandatory behavior is `MAJOR`, additive
-guidance such as new DRs, skills, or articles is usually `MINOR`, and low-risk corrections are
-`PATCH`.
-
-### Use agentme as the fuller packaged example
-
-This repository shows the baseline xdrs-core packaging model. For a fuller distribution package that
-combines reusable XDR scopes with additional agent workflow files and presets, use
-[flaviostutz/agentme](https://github.com/flaviostutz/agentme) as the reference. Its README shows the
-same extraction model applied to a richer package: install the dependency, run `extract`, review the
-generated output, and re-run `check` when upgrading.
-
-## References
-
-- [_core-adr-001](../../../../_core/adrs/principles/001-xdr-standards.md) - Scope structure, precedence, and distribution model
-- [_core-adr-003](../../../../_core/adrs/principles/003-skill-standards.md) - Skill co-location and discovery rules
-- [_core-adr-004](../../../../_core/adrs/principles/004-article-standards.md) - Article placement and template rules
-- [_core-adr-005](../../../../_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md) - Versioning policy for published XDR packages
-- [package.json](../../../../../package.json) - Reference `files`, `bin`, symlink, and `filedist` set layout
-- [Makefile](../../../../../Makefile) - Reference pack and publish flow
-- [example/package.json](../../../../../example/package.json) - Minimal consumer dependency setup
-- [example/Makefile](../../../../../example/Makefile) - Extraction, keep-existing, check, and lint verification flow
-- [agentme](https://github.com/flaviostutz/agentme) - Full distribution package example built on top of xdrs-core

package/AGENTS.local.md

@@ -1,3 +0,0 @@
-# AGENTS.local.md
-
-No repository specific instructions available. Focus on XDRS instructions only.