xdrs-core 0.14.2 → 0.14.3

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

@@ -21,6 +21,9 @@ Guides the creation of a well-structured XDR by following the standards in `_cor
 3. Read `.xdrs/_core/adrs/principles/002-xdr-standards.md` in full to internalize the XDR template and document writing rules.
 4. Treat `001-xdrs-core` as the canonical source for all core XDR element definitions (type, scope, subject, numbering, placement). Treat `002-xdr-standards` as the canonical source for how to write and structure the document itself.
 5. Ask the user (or infer from context) the topic of the decision. Do NOT proceed to Phase 2 without a clear topic.
+   - Ask one focused clarifying question at a time. Wait for the answer before asking the next question.
+   - Each answer may reveal new ambiguities; ask follow-up questions as needed until the topic, intent, and scope are unambiguous.
+   - Stop asking and proceed only when the decision topic is fully understood.
 
 ### Phase 2: Select Type, Scope, and Subject
 
@@ -38,6 +41,8 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 - BDR: `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
 - EDR: `principles`, `application`, `infra`, `observability`, `devops`, `governance`
 
+When type, scope, or subject cannot be confidently inferred, ask the user a clarifying question before proceeding. Ask one question at a time and wait for the answer; follow up if the response introduces new ambiguity.
+
 **XDR ID** — format: `[scope]-[type]-[next available number]`
 - Scan `.xdrs/[scope]/[type]/` for the highest existing number in that scope+type and increment by 1.
 - Never reuse numbers from deleted XDRs.

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

@@ -13,12 +13,27 @@ Guides the creation of a well-structured article by following `_core-adr-004`, c
 
 ## Instructions
 
+### Phase 0: Clarify Intent
+
+Before reading any standards, ask the user clarifying questions to gather the information needed to proceed. Use the `vscode_askQuestions` tool with all questions in a single call.
+
+Mandatory questions (ask only if not already provided by the user):
+- **Topic**: What is the article about? (skip if the user already stated it)
+- **Audience**: Who is the intended reader? (e.g., new developers, product managers, external contributors) MUST always be asked explicitly; never infer from context.
+- **Scope**: Which XDR scope should contain the article? (default is `_local`; confirm or ask only if context is ambiguous)
+
+Optional questions (ask only when genuinely unclear):
+- **Type**: Should the article primarily synthesize ADRs, BDRs, or EDRs? Ask only when the topic spans multiple types.
+- **Existing XDRs**: Are there specific Decision Records or Skills you want the article to reference or synthesize?
+
+Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audience**.
+
 ### Phase 1: Understand the Article Goal
 
 1. Read `.xdrs/_core/adrs/principles/004-article-standards.md` in full to internalize the template,
    placement rules, numbering rules, and the constraint that articles are views, not decisions.
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full before defining the article's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering, naming, and folder placement.
-3. Identify the topic and intended audience from user input or context. Do NOT proceed without a clear
+3. Confirm the topic and intended audience gathered in Phase 0. Do NOT proceed without a clear
    topic.
 
 ### Phase 2: Select Scope, Type, and Subject

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

@@ -6,29 +6,33 @@ description: >
   Activate this skill when the user asks to create, add, or write a research document that backs a decision.
 metadata:
   author: flaviostutz
-  version: "1.3"
+  version: "1.4"
 ---
 
 ## Overview
 
 Guides the creation of a well-structured research document by following `_core-adr-006`, consulting `xdr-standards` for every core element definition, checking related XDRs and existing research to avoid duplication, and producing an IMRAD-based study that reads as a standalone technical paper. Treat each section goal in the research template as an acceptance criterion, not as optional wording. Do not assume missing direction, evidence, or intended follow-up; ask the user explicitly before proceeding when those points are not already concrete.
 
+This skill is interactive by design. Ask clarifying questions to the user at each phase where direction, evidence, or scope is unclear. Ask sequentially — one focused set of questions at a time — and wait for the user's answers before advancing to the next phase. Never front-load all questions at once if not all are yet relevant.
+
 ## 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. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full before defining the research document's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering expectations, naming constraints, and folder placement.
-3. Ask the user to confirm the intended direction of the research before planning the document: what decision, question, or option space the study should support, what boundaries or exclusions apply, and what kind of outcome they expect.
-4. Ask the user what evidence already exists and what evidence-gathering methods are acceptable if the current evidence is incomplete. Do not invent facts, sources, or confidence that the user did not provide.
-5. Ask the user what the proposed next step is after the research, such as writing a new XDR, updating an existing XDR, informing a discussion, or documenting trade-offs for later. Use that answer to shape the framing without turning the research into the final decision.
+3. Ask the user to confirm the intended direction of the research before planning the document: what decision, question, or option space the study should support, what boundaries or exclusions apply, and what kind of outcome they expect. Wait for the answers before proceeding.
+4. Ask the user what evidence already exists and what evidence-gathering methods are acceptable if the current evidence is incomplete. Do not invent facts, sources, or confidence that the user did not provide. Wait for the answers before proceeding.
+5. Ask the user what the proposed next step is after the research, such as writing a new XDR, updating an existing XDR, informing a discussion, or documenting trade-offs for later. Use that answer to shape the framing without turning the research into the final decision. Wait for the answers before proceeding.
 6. Identify the problem or question being explored, the relevant system or domain context, the likely technical audience, and why the subject matters in practice.
 7. Internalize the goal of each required section before drafting: `Abstract` gives a quick technical reader the question, method, main result, and takeaway, `Introduction` frames the investigated problem and context, `Methods` makes the important parts reproducible, `Results` records raw findings with minimal interpretation, `Discussion` interprets the findings, `Conclusion` summarizes the practical takeaway and boundaries, and `References` makes sources traceable.
 8. Collect the main constraints, known facts, important experiences, gaps, and assumptions that belong in the introduction.
-9. Do NOT proceed without a clear problem statement, a central question, explicit user direction, an understood next step, and at least one credible source of evidence or a method for generating it. If any of these are ambiguous, stop and ask instead of assuming.
+9. Do NOT proceed without a clear problem statement, a central question, explicit user direction, an understood next step, and at least one credible source of evidence or a method for generating it. If any of these are ambiguous, use `vscode_askQuestions` to ask the user instead of assuming. After receiving answers, evaluate whether any response introduces new ambiguity and, if so, ask a follow-up set of questions before proceeding.
 
 ### Phase 2: Select Scope, Type, Subject, and Number
 
+If the answers from Phase 1 leave scope, type, or subject ambiguous, use `vscode_askQuestions` to present the candidate options with a brief rationale for each and ask the user to confirm the selection before proceeding. If the user's answer raises a related uncertainty, ask a follow-up question to resolve it before locking the selection.
+
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
@@ -54,13 +58,15 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 
 1. Create the final section skeleton in the research file before running the study: `Abstract`, `Introduction`, `Methods`, `Results`, `Discussion`, `Conclusion`, `References`.
 2. Write a one-line note under each section heading capturing that section's goal before filling in the content so the draft stays disciplined.
-3. Draft `## Introduction` early so the problem, scope, constraints, assumptions, and central question are fixed before evidence collection expands.
-4. Draft `## Methods` before or while executing the study so tools, data sources, and conditions are captured while they are still precise.
+3. Draft `## Introduction` early so the problem, scope, constraints, assumptions, and central question are fixed before evidence collection expands. If the central research question is still unclear after Phase 1, use `vscode_askQuestions` to confirm it in a single focused question before drafting the introduction. If the answer reveals further ambiguity, ask one more targeted follow-up before proceeding.
+4. Draft `## Methods` before or while executing the study so tools, data sources, and conditions are captured while they are still precise. If the study design is uncertain, use `vscode_askQuestions` to clarify which methods or data sources are applicable before committing to a design. Follow up if the answer leaves the design still unclear.
 5. Treat `## Abstract` as a late-stage summary. Do not try to finalize it yet.
 6. Keep process framing out of the body. If related ADRs or repository context matter, push that traceability to `## References` unless it is essential to the technical question itself.
 
 ### Phase 5: Capture Evidence as the Study Runs
 
+If at any point during evidence collection a significant gap appears, an assumption cannot be verified, or a new branch of the question emerges, pause and use `vscode_askQuestions` to ask the user a focused question before continuing. If the answer resolves one gap but reveals another, ask a follow-up question immediately. Do not proceed past a critical gap by guessing.
+
 1. As experiments, comparisons, code spikes, interviews, benchmarks, or document reviews happen, append the concrete findings to `## Results` continuously.
 2. Prefer capturing tables, bullet points, numbers, code outputs, and option comparisons while the evidence is fresh.
 3. If multiple options solve the same problem, add a comparison table and explicit pros and cons for each option in `## Results` so the trade-offs are directly inspectable.
@@ -69,6 +75,8 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 
 ### Phase 6: Synthesize After Results Stabilize
 
+If the results contain competing interpretations or the intended audience for the conclusions is unclear, use `vscode_askQuestions` to ask the user a focused question before writing the discussion. Keep the question specific to a single open point. If the answer raises a further interpretive uncertainty, ask one targeted follow-up before writing.
+
 1. Write `## Discussion` only after the important findings are visible in `## Results`.
 2. Use `## Discussion` to interpret significance, trade-offs, limitations, implications, and performance considerations for technical readers.
 3. Write `## Conclusion` after the discussion so it reflects the actual findings, practical takeaway, applicability boundaries, and open questions.

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

@@ -19,7 +19,13 @@ Guides the creation of a well-structured plan document by following `_core-adr-0
 
 1. Read `.xdrs/_core/adrs/principles/007-plan-standards.md` in full to internalize the template, placement rules, numbering rules, and the constraint that plans are ephemeral and must be deleted after implementation.
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full before defining the plan's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering, naming, and folder placement.
-3. Identify the problem being solved, the proposed solution, and the expected timeline from user input or context. Do NOT proceed without a clear problem statement and proposed solution. Ask the user if these are not clear.
+3. Identify the problem being solved, the proposed solution, and the expected timeline from user input or context. Do NOT proceed without a clear problem statement and proposed solution.
+4. Ask the user clarifying questions to fill any gaps before writing the plan. Use the following rules:
+   - Ask all initial questions in a single batch so the user can answer them together.
+   - After receiving the answers, evaluate whether any answer introduces new ambiguity or opens a related topic that requires further clarification. If it does, ask a focused follow-up question (or a small batch of follow-up questions) before proceeding.
+   - Repeat this question-answer loop until you have enough information to write the plan with confidence.
+   - Typical questions cover: the problem being solved, the proposed solution, the expected timeline, the scope, the key stakeholders, and any known constraints or risks.
+   - Do NOT ask questions whose answers are already clear from context.
 
 
 ### Phase 2: Select Scope, Type, and Subject

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "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",