agentme 0.36.0 → 0.37.1

package/.xdrs/agentme/edrs/operations/405-dora-change-failure-rate.md

@@ -0,0 +1,42 @@
+---
+name: agentme-edr-policy-405-dora-change-failure-rate
+description: Defines calculation, examples, and challenges for DORA's Change Failure Rate metric and its hotfix/revert-rate, incident-linked-deploy-rate, and escaped-defect-rate sub-metrics, including cross-team root-cause attribution. Use when instrumenting or reviewing change failure rate measurement.
+apply-to: Teams and organizations measuring, reporting, or improving software delivery performance using DORA's four key metrics
+valid-from: 2026-09-18
+---
+
+# agentme-edr-policy-405: DORA change failure rate
+
+## Context and Problem Statement
+
+Failure shows up in different ways — an immediate rollback, an incident without a rollback, a defect found later — and no single detection method catches all of them. How should each be calculated, and how should a failure whose root cause spans multiple teams be attributed?
+
+## Decision Outcome
+
+**Measure three complementary, non-summing detection signals per deployable service, and attribute cross-team-caused incidents to both the root-cause team and the impacted team.**
+
+The three sub-metrics MUST NOT be summed; a team MAY treat one as primary as it matures, but all three remain independent signals.
+
+### Details
+
+#### 01-hotfix-revert-rate
+
+Hotfix/revert rate MUST be calculated by dividing PRs titled or labeled `revert` merged shortly after a deploy by total deploys for the service, using CODEOWNERS for attribution. Example: 2 reverts following 40 deploys gives a 5% hotfix/revert rate. Challenges: a hotfix that itself gets reverted MUST NOT be double-counted as two separate failures. Teams SHOULD adopt this first, since it catches the most severe, most obvious failures using a single data source.
+
+#### 02-incident-linked-deploy-rate
+
+Incident-linked deploy rate MUST be calculated by dividing GH Issues labeled `incident` that reference a deploy by total deploys for the service, using the issue-label/component convention from [agentme-edr-402](402-dora-metrics-framework.md)'s `03-artifact-to-service-mapping` (CODEOWNERS does not apply to Issues). Example: 3 incident-linked issues following 40 deploys gives 7.5%. Challenges: deploy-to-incident attribution lag, and label-discipline under-reporting when incidents go untagged. Teams SHOULD adopt this second: it reuses `01`'s deploy count with one additional label convention, and catches real failures that did not need a rollback but still affected users.
+
+#### 03-escaped-defect-rate
+
+Escaped defect rate MUST be calculated by dividing GH Issues labeled `bug` and `production`, opened after a release and attributed to the service, by total deploys. Example: 4 escaped defects following 40 deploys gives 10%. Challenges: attribution lag across period boundaries when a defect surfaces well after the causing deploy. Teams SHOULD adopt this third: it reuses the same issue-label convention as `02`, and catches slower-to-surface failures the first two signals miss.
+
+#### 04-cross-team-and-shared-root-cause-attribution
+
+When an incident's root cause is a different team's change, it MUST be counted against the root-cause team's numerator here, per [agentme-edr-402](402-dora-metrics-framework.md)'s `04-cross-team-incident-attribution`; the impacted team MUST instead receive a separate, non-tiered visibility tag rather than a numerator hit. An incident traced to one shared root cause but manifesting across several teams' trackers MUST be linked to a single root-cause record and MUST NOT be counted independently as multiple failures.
+
+## References
+
+- [agentme-edr-402](402-dora-metrics-framework.md) — DORA metrics framework
+- [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md) — Digital product roles: RACI (root-cause tracing methodology)
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)

package/.xdrs/agentme/edrs/operations/406-dora-time-to-restore-service.md

@@ -0,0 +1,42 @@
+---
+name: agentme-edr-policy-406-dora-time-to-restore-service
+description: Defines calculation, examples, and challenges for DORA's Time to Restore Service metric and its total-restore-time, detection-time, acknowledgement-time, and resolution-time sub-metrics, using GitHub Issues as the worked example. Use when instrumenting or reviewing incident restore-time measurement.
+apply-to: Teams and organizations measuring, reporting, or improving software delivery performance using DORA's four key metrics
+valid-from: 2026-09-18
+---
+
+# agentme-edr-policy-406: DORA time to restore service
+
+## Context and Problem Statement
+
+Restoring service after a failed deployment is DORA's safety-net metric (DORA's current term is "Failed Deployment Recovery Time"), but a single total-time figure hides whether delay lives in detection, response, or the fix itself. How should the total and its phases be calculated in a tool-agnostic way?
+
+## Decision Outcome
+
+**Measure a total restore time plus three additive phase sub-metrics per impacted service, using any incident-management tool with equivalent timestamps; GitHub Issues is the worked example.**
+
+The total MUST be tracked standalone, and the three phases decompose it, always attributed to the impacted or owning service regardless of where the root cause is traced.
+
+### Details
+
+#### 01-total-restore-time
+
+Total restore time MUST be measured from an incident's opened timestamp to its closed timestamp, attributed via the issue-label/component convention from [agentme-edr-402](402-dora-metrics-framework.md)'s `03-artifact-to-service-mapping` to the service that was down or degraded. Example: opened at 10:00, closed at 11:30, gives 90 minutes. Challenges: partial-vs-full restores and reopened incidents. Teams SHOULD adopt this first: it needs only two timestamps on one incident record, no extra tracked event, and gives an immediate, if coarse, restore-time signal.
+
+#### 02-detection-time
+
+Detection time MUST be measured from the underlying failure's occurrence to the incident's detected timestamp, a tracked event distinct from "opened." Example: failure at 10:00, detected at 10:05, gives 5 minutes. Challenges: without paging or monitoring, detection relies on user reports and is easy to under-track. Teams SHOULD adopt this second: it requires one additional tracked "detected" event, and exposes how much time is lost before anyone notices, a leading indicator for monitoring coverage gaps.
+
+#### 03-acknowledgement-time
+
+Acknowledgement time MUST be measured from detected to acknowledged or assigned. Example: detected at 10:05, acknowledged at 10:10, gives 5 minutes. Challenges: on-call handoff and timezone gaps. Teams SHOULD adopt this third: it requires one additional tracked "acknowledged" event, and exposes on-call responsiveness separately from the fix itself.
+
+#### 04-resolution-time
+
+Resolution time MUST be measured from acknowledged to actually-fixed, not merely issue-closed. Example: acknowledged at 10:10, fixed at 11:30, gives 80 minutes. Challenges: extensive or mandatory manual rollout testing can gate the fix itself, extending this phase. Rules `02`, `03`, and `04` MUST sum to the total measured in `01`. Teams SHOULD adopt this last: it requires a reliable "fixed" event, the hardest to track consistently, but it isolates how long the actual fix takes once someone is engaged.
+
+## References
+
+- [agentme-edr-402](402-dora-metrics-framework.md) — DORA metrics framework
+- [agentme-bdr-405](../../bdrs/operations/405-digital-product-roles-raci.md) — Digital product roles: RACI (incident-response accountability)
+- [DORA's software delivery performance metrics](https://dora.dev/guides/dora-metrics-four-keys/)

package/.xdrs/agentme/edrs/platform/301-monorepo-structure.md

@@ -17,7 +17,7 @@ What monorepo structure, naming conventions, tooling, and build standards should
 
 **Adopt a standardized monorepo layout with top-level application folders that aggregate independent module roots, shared parent-level example and test areas, Mise-managed tooling, and Makefiles at every level.**
 
-For step-by-step scaffolding instructions see [skill 053-monorepo-setup](skills/053-monorepo-setup/SKILL.md).
+For step-by-step scaffolding instructions see [skill monorepo-setup](skills/monorepo-setup/SKILL.md).
 Module folder responsibilities, artifact locations, and test-folder conventions follow [agentme-edr-016](../principles/016-cross-language-module-structure.md).
 
 ### Details

package/.xdrs/agentme/edrs/platform/skills/{053-monorepo-setup → monorepo-setup}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 053-monorepo-setup
+name: monorepo-setup
 description: >
   Step-by-step instructions for setting up and scaffolding a new monorepo following the standard
   layout, naming conventions, Makefiles, Mise tooling, and README requirements defined in
@@ -8,7 +8,8 @@ description: >
   complies with the standard structure.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.1.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -20,6 +21,27 @@ test any part of the monorepo with a single, predictable command.
 
 Related EDRs: [agentme-edr-301](../../301-monorepo-structure.md), [agentme-edr-502](../../../governance/502-contributing-guide-requirements.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
+### Inputs
+
+#### Required
+- Applications and modules to scaffold or extend
+
+#### Optional
+- Primary language(s), tool versions, target directory
+
+### Outputs
+
+#### Contents
+- Root/app/module Makefiles, READMEs, `.mise.toml`, `.gitignore`
+
+#### Changes
+- None
+
+### Halt Conditions
+- Applications/modules not specified and not inferable from context
+- Cross-application dependency requested (ambiguous boundary)
+- Existing README/Makefile found without explicit confirmation
+
 ## Instructions
 
 ### Phase 1: Gather information
@@ -67,8 +89,8 @@ test:
 	$(foreach app,$(APPS),$(MAKE) -C $(app) test &&) true
 
 clean:
-   $(foreach app,$(APPS),$(MAKE) -C $(app) clean &&) true
-   rm -rf .cache
+	$(foreach app,$(APPS),$(MAKE) -C $(app) clean &&) true
+	rm -rf .cache
 
 setup:
 	@echo "Install Mise: https://mise.jdx.dev/getting-started.html"
@@ -220,16 +242,16 @@ For each module inside an application:
    all: build lint test
 
    build:
-   mise exec -- go build ./...
+   	mise exec -- go build ./...
 
    lint:
-   mise exec -- golangci-lint run ./...
+   	mise exec -- golangci-lint run ./...
 
    test:
-   mise exec -- go test ./... -cover
+   	mise exec -- go test ./... -cover
 
    clean:
-	rm -rf dist .cache
+   	rm -rf dist .cache
    ```
 
    **Node.js / TypeScript:**
@@ -239,16 +261,16 @@ For each module inside an application:
    all: build lint test
 
    build:
-   mise exec -- pnpm exec tsc --project tsconfig.json
+   	mise exec -- pnpm exec tsc --project tsconfig.json
 
    lint:
-   mise exec -- pnpm exec eslint ./src
+   	mise exec -- pnpm exec eslint ./src
 
    test:
-   mise exec -- pnpm exec jest --verbose
+   	mise exec -- pnpm exec jest --verbose
 
    clean:
-	rm -rf dist .cache
+   	rm -rf dist .cache
    ```
 
    **Python:**
@@ -258,16 +280,16 @@ For each module inside an application:
    all: build lint test
 
    build:
-   mise exec -- uv build --project . --out-dir dist
+   	mise exec -- uv build --project . --out-dir dist
 
    lint:
-   mise exec -- uv run --project . ruff check .
+   	mise exec -- uv run --project . ruff check .
 
    test:
-   mise exec -- uv run --project . pytest
+   	mise exec -- uv run --project . pytest
 
    clean:
-	rm -rf dist .cache
+   	rm -rf dist .cache
    ```
 
 4. **Add source files** appropriate to the language, placing them inside the module folder.
@@ -338,3 +360,15 @@ test:
 - **Module with no compilable output (e.g., pure scripts):** Still create the Makefile; `build` can be a no-op (`@true`) but the target must exist.
 - **Language not listed above:** Mirror the pattern — `build` produces an artifact, `lint` runs static analysis, `test` runs tests. Adapt commands to the actual toolchain.
 - **Existing files:** Never overwrite existing `README.md`, `CONTRIBUTING.md`, or `Makefile` files without user confirmation. Diff and propose additions instead.
+
+## Anti-Patterns
+
+- **Mistake:** Letting one application import another application's code directly.
+  **Why it happens:** Reaching across app folders feels faster than publishing a shared library.
+  **Instead:** Refuse the direct import and move the shared code into `shared/libs/`.
+- **Mistake:** Silently overwriting an existing `README.md`, `CONTRIBUTING.md`, or `Makefile`.
+  **Why it happens:** Scaffolding logic assumes a clean, empty target directory.
+  **Instead:** Diff against the existing file and propose additions instead of overwriting.
+- **Mistake:** Skipping the `Makefile` for a module with no compilable output.
+  **Why it happens:** A pure-script module seems to need no build step at all.
+  **Instead:** Still create the Makefile with a no-op `build` target (`@true`) for consistency.

package/.xdrs/agentme/edrs/platform/skills/monorepo-setup/SKILL.test.md

@@ -0,0 +1,80 @@
+---
+skill: monorepo-setup
+skill-version: "1.1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Scaffold a two-application monorepo, happy path
+
+**Trigger / Input**
+
+"Set up a new monorepo called `platform-tools` with two applications: `ingest` (Go, one module
+named `collector`) and `dashboard` (Node.js/TypeScript, one module named `web`)."
+
+**Expected Behaviour**
+
+1. Phase 1 gathers or infers applications, modules, primary languages, and tool versions.
+2. Phase 2 creates the root `.mise.toml`, root `Makefile` (delegating `build`/`lint`/`test`/`clean`
+   to every application via `$(MAKE) -C $(app) $@`), root `.gitignore` ignoring `dist/` and
+   `.cache/`, root `README.md` with Overview/Machine setup/Quickstart/Repository map, and root
+   `CONTRIBUTING.md`.
+3. Phase 3 creates the `shared/` area (`libs/`, `scripts/`).
+4. Phase 4 scaffolds `ingest/` and `dashboard/` each with a `README.md` and a `Makefile` that
+   delegates to their modules.
+5. Phase 5 scaffolds `ingest/collector/Makefile` using the Go recipe (`mise exec -- go build
+   ./...`, `golangci-lint run ./...`, `go test ./... -cover`) and `dashboard/web/Makefile` using
+   the Node.js/TypeScript recipe (`mise exec -- pnpm exec tsc`, `eslint`, `jest`).
+6. Phase 6 verifies root `make build`, `make lint`, and `make test` succeed and reports the
+   Phase 6 checklist before finishing.
+
+**Assertions**
+
+- [ ] Output creates a root `Makefile` whose `build`, `lint`, and `test` targets delegate to each
+      application with `$(MAKE) -C $(app) $@`.
+- [ ] Output generates `ingest/collector/Makefile` with Go recipe commands and
+      `dashboard/web/Makefile` with Node.js/TypeScript recipe commands, each matching the
+      language-specific block for that module.
+- [ ] Output reports that root `make build`, `make lint`, and `make test` succeed before declaring
+      the scaffold complete.
+- [ ] Output includes a root `CONTRIBUTING.md` covering bugs, feature discussion, pull requests,
+      Conventional Comments, and small focused changes.
+
+### Scenario 2: Cross-application dependency request is refused
+
+**Trigger / Input**
+
+"Make the `web` module in `dashboard` import a function directly from the `collector` module in
+`ingest`."
+
+**Expected Behaviour**
+
+Per the Edge Cases entry for cross-application dependencies, the skill refuses to wire a direct
+import between two different applications' modules and instead proposes extracting the shared
+code into `shared/libs/` as a published library that both applications can depend on.
+
+**Assertions**
+
+- [ ] Output refuses to create a direct import from `dashboard/web` into `ingest/collector`.
+- [ ] Output proposes moving the shared logic into `shared/libs/` instead of a cross-application
+      import.
+
+### Scenario 3: Existing root Makefile is never silently overwritten
+
+**Trigger / Input**
+
+"Add a new application called `reports` to this monorepo." The repository already has a root
+`Makefile` with custom targets not generated by this skill.
+
+**Expected Behaviour**
+
+Per the Edge Cases entry for existing files, the skill does not overwrite the existing root
+`Makefile` (or `README.md`/`CONTRIBUTING.md`) without explicit user confirmation. It diffs the
+existing file against the standard layout and proposes additions instead.
+
+**Assertions**
+
+- [ ] Output does not overwrite the existing root `Makefile` without first asking for explicit
+      user confirmation.
+- [ ] Output presents a diff or a proposed set of additions rather than replacing the file
+      silently.

package/.xdrs/agentme/edrs/principles/012-continuous-xdr-enrichment.md

@@ -61,4 +61,4 @@ In SDD, specifications describe the feature being built; XDRs describe reusable
 - [_core-adr-001](../../../_core/adrs/principles/001-xdrs-standards.md)
 - [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md)
 - [agentme-article-001](articles/001-continuous-xdr-improvement.md)
-- [002-write-policy skill](../../../_core/adrs/principles/skills/002-write-policy/SKILL.md)
+- [write-policy skill](../../../_core/adrs/principles/skills/write-policy/SKILL.md)

package/.xdrs/agentme/edrs/principles/017-skill-testing.md

@@ -2,7 +2,7 @@
 name: agentme-edr-policy-017-skill-testing
 description: >
   Mandates a SKILL.test.md test file co-located with every skill, defines the test file format (scenarios with trigger, expected behaviour, and assertions), and requires execution before merging any change to the skill. Use when creating, updating, or reviewing skills.
-apply-to: contributors working in any scope that directly or transitively follows or extends agentme
+apply-to: the agentme scope itself, and any scope that directly or transitively follows or extends agentme
 valid-from: 2026-08-06
 ---
 
@@ -16,7 +16,7 @@ How should skill correctness be verified after every change, in a way that is co
 
 ## Decision Outcome
 
-**Every skill MUST have a `SKILL.test.md` file in the same directory as its `SKILL.md`. The file defines test scenarios with explicit input triggers and falsifiable assertions. It MUST be executed — using the `200-run-skill-tests` skill or manually — before merging any PR that modifies the skill or its test file.**
+**Every skill MUST have a `SKILL.test.md` file in the same directory as its `SKILL.md`. The file defines test scenarios with explicit input triggers and falsifiable assertions. It MUST be executed — using the `run-skill-tests` skill or manually — before merging any PR that modifies the skill or its test file.**
 
 ### Details
 
@@ -71,7 +71,7 @@ Rules:
 
 `SKILL.test.md` MUST be executed before merging any PR that modifies the skill or its test file. Execution means running each scenario and verifying all assertions pass.
 
-Use the `200-run-skill-tests` skill to execute the file, or run each scenario manually when automation is not available.
+Use the `run-skill-tests` skill to execute the file, or run each scenario manually when automation is not available.
 
 
 ## Considered Options
@@ -83,4 +83,4 @@ Use the `200-run-skill-tests` skill to execute the file, or run each scenario ma
 ## References
 
 - [`_core-adr-policy-003`](../../../_core/adrs/principles/003-skill-standards.md) — Skill package standards and folder layout
-- [`200-run-skill-tests`](../application/skills/200-run-skill-tests/SKILL.md) — Runner skill that executes `SKILL.test.md` scenarios
+- [`run-skill-tests`](../application/skills/run-skill-tests/SKILL.md) — Runner skill that executes `SKILL.test.md` scenarios

package/.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md

@@ -90,4 +90,4 @@ If the same clarification would likely be needed in another feature, by another
 - [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-standards.md) - XDR structure, numbering, and mandatory template
 - [_core-article-001](../../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
 - [agentme-edr-012](../012-continuous-xdr-enrichment.md) - Shared-first XDR enrichment policy and 80% coverage target
-- [002-write-policy skill](../../../../_core/adrs/principles/skills/002-write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs
+- [write-policy skill](../../../../_core/adrs/principles/skills/write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs

package/.xdrs/agentme/edrs/principles/skills/{150-refine-plan-mode → refine-plan-mode}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 150-refine-plan-mode
+name: refine-plan-mode
 description: >
   MANDATORY for ANY planning activity. Read and follow this skill in full whenever the user asks
   to plan, design, propose, outline, draft, brainstorm, architect, or think through anything —
@@ -8,7 +8,8 @@ description: >
   the XDRS repository even when not directly exposed in the .agents skills folder.
 metadata:
   author: flaviostutz
-  version: "3.0"
+  version: "3.1.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
@@ -29,6 +30,27 @@ Ensures that every plan is deeply validated through iterative consistency checks
 
 **Artifact rule**: The plan is a single continuously-edited final artifact, not an append-only log. Process detail — Q&A rounds, phase-gate confirmations, todo-list tracking — never enters the deliverable; todos stay in the agent's todo-list tool. When a later phase reverses an earlier decision or section, edit it in place — never leave the superseded content beside the replacement. The final artifact's structure follows the **Final Plan Artifact Template** below.
 
+### Inputs
+
+#### Required
+- Task, feature, or decision to plan
+
+#### Optional
+- Constraints, prior art, related decisions
+
+### Outputs
+
+#### Contents
+- Final Plan Artifact (steps, verification, decisions)
+
+#### Changes
+- None until Phase 7 handoff
+
+### Halt Conditions
+- Unresolved ambiguity or open assumption remains
+- Human has not confirmed phase convergence
+- Low confidence in a subjective/domain decision
+
 ## Final Plan Artifact Template
 
 The **final artifact** (Phase 7 handoff) uses this exact section order, no competing top-level sections — matching GitHub Copilot's native Plan Mode output shape:
@@ -137,16 +159,10 @@ Checks to run in order:
 - `"Check for more features I would probably need but that are not part of the plan. Ask questions."`
 - `"What happens if the file doesn't exist? Ask questions."`
 - `"Dry run if I send a file with 10GB in size"`
-- `"What happens if we have 10 million files?"`
 - `"Explore if all types of input would work with this utility"`
-- `"Is the plan doing everything we asked in the beginning?"`
-- `"How are you making sure those things are implemented correctly?"`
 - `"Verify all references in the plan. Ask questions."`
 - `"Check for edge cases we didn't discuss yet. Ask questions."`
-- `"Check for consistency and ask questions"`
 - `"Show me a diagram explaining the overall feature structure"`
-- `"Explain to me what this utility does"`
-- `"How could I distribute this utility?"`
 
 After all checks (a–i) converge, use `vscode_askQuestions` (per Phase gate UI rule) to present the Phase 4 gate with at least these options:
 - **"Continue to Phase 5 — Visual Consistency Validation"** (recommended when all checks have converged) — advance.
@@ -276,7 +292,7 @@ If any features were placed in the **Deferred Features** list during Phase 2 Ste
 This step is skipped if no features were deferred.
 
 **Deferred Features entry template** — always append a new `### Group:` section per split (never merge with a same-titled prior group); a group can have as few as 1 part:
-- `### Group: [original request title] — deferred [YYYY-MM-DD]` — with **Origin:** `150-refine-plan-mode — Phase 2 Step 5`, **Original objective:** the one-sentence value of the whole request before splitting, and **Split rationale:** why it was split.
+- `### Group: [original request title] — deferred [YYYY-MM-DD]` — with **Origin:** `refine-plan-mode — Phase 2 Step 5`, **Original objective:** the one-sentence value of the whole request before splitting, and **Split rationale:** why it was split.
 - One `#### [part title]` subsection per deferred part, each with **Objective:** (this part's specific value), **Scope:** (bullet list of what's included), **Context captured so far:** (bullet list of key decisions/answers/constraints already gathered before deferral), and **Suggested prompt to resume:** (a ready-to-paste prompt naming plan mode and summarizing the objective and known constraints so a future session can resume without re-reading the whole conversation).
 
 Before the final gate, add a step to the implementation plan to produce a concise feature documentation file. Use `vscode_askQuestions` to ask:
@@ -307,14 +323,24 @@ Do not start execution to escape planning discomfort — only start when confide
 
 ## Anti-Patterns
 
-Avoid these common failure modes:
-
-- **Planning theater**: running rounds without real critical thinking. Asking many questions is correct behavior — the anti-pattern is asking hollow, self-validating questions, not asking frequently. Rounds that confirm the plan against itself add false confidence — checks must challenge assumptions, not validate them.
-- **Scope creep silence**: the plan grows beyond the original request without the human noticing. Every addition must be flagged explicitly.
-- **Agent self-validation**: the agent answers its own questions on subjective, domain, or intent-based decisions and proceeds without asking the human. The human is the oracle for domain knowledge, intent, and subjective decisions — the agent must not self-resolve those unilaterally.
-- **Confidence as a proxy for correctness**: an agent expressing certainty does not mean the plan is correct. Run all checks regardless of how confident the agent sounds.
-- **Treating unverified references as facts**: the agent references files, CLIs, statistics, library APIs, quoted sources, or named organizations without a tool call or direct inspection to confirm they exist. All high-risk references must be verified immediately or explicitly listed in the Unverified References section with a mandatory first-step check before use.
-- **Artifact bloat**: the final plan accretes process narrative (Q&A rounds, phase-gate confirmations, todo-list tracking, superseded drafts) instead of converging to the **Final Plan Artifact Template**. It's a continuously-edited deliverable, not an append-only log.
+- **Mistake:** Running Q&A rounds that only confirm the plan against itself.
+  **Why it happens:** Frequent questions look thorough even when they validate rather than challenge.
+  **Instead:** Ask questions that challenge assumptions, not ones that just self-validate.
+- **Mistake:** Letting the plan grow beyond the original request unnoticed.
+  **Why it happens:** Small additions feel harmless one at a time.
+  **Instead:** Flag every addition to the human explicitly.
+- **Mistake:** Answering subjective or domain questions on the agent's own and proceeding.
+  **Why it happens:** It feels faster than waiting for human input.
+  **Instead:** Treat the human as the oracle for domain and subjective decisions.
+- **Mistake:** Treating the agent's own certainty as proof the plan is correct.
+  **Why it happens:** A confident tone feels like validation on its own.
+  **Instead:** Run every check regardless of how confident the agent sounds.
+- **Mistake:** Citing files, APIs, statistics, or sources without verifying they exist.
+  **Why it happens:** Plausible-sounding references are mistaken for confirmed ones.
+  **Instead:** Verify immediately, or list in Unverified References with a first-step check.
+- **Mistake:** Letting the plan accumulate Q&A rounds, gate confirmations, and superseded drafts.
+  **Why it happens:** Process narrative is easy to leave behind when editing in a hurry.
+  **Instead:** Keep the plan a continuously-edited deliverable matching the Final Plan Artifact Template.
 
 ## Re-Plan Triggers
 

package/.xdrs/agentme/edrs/principles/skills/{150-refine-plan-mode → refine-plan-mode}/SKILL.test.md

@@ -1,6 +1,6 @@
 ---
-skill: 150-refine-plan-mode
-skill-version: "3.0"
+skill: refine-plan-mode
+skill-version: "3.1.0"
 ---
 
 ## Test Scenarios
@@ -118,7 +118,7 @@ Phase 2 Step 4 surfaces roughly 24 distinct in-scope items across the three subs
 
 **Trigger / Input**
 
-A user runs the full 150-refine-plan-mode workflow across multiple rounds — including at least one re-run of a phase gate (e.g., "Re-run Phase 4: Consistency Checks — deeper pass") and one Phase 2 Step 5 scope split with a deferred part — before reaching Phase 7 and confirming "Hand off to implementation".
+A user runs the full refine-plan-mode workflow across multiple rounds — including at least one re-run of a phase gate (e.g., "Re-run Phase 4: Consistency Checks — deeper pass") and one Phase 2 Step 5 scope split with a deferred part — before reaching Phase 7 and confirming "Hand off to implementation".
 
 **Expected Behaviour**
 

package/.xdrs/agentme/edrs/principles/skills/{151-refine-user-story → refine-user-story}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 151-refine-user-story
+name: refine-user-story
 description: >
   Refine, elaborate, study or develop the contents of a user story used to create a unit of work
   for an agile team. Use when you need to write, refine, clarify requirements, ask follow-up
@@ -7,12 +7,13 @@ description: >
   complete, and ready for implementation.
 metadata:
   author: flaviostutz
-  version: "4.1"
+  version: "4.2.0"
+  updated: 2026-09-21
 ---
 
 ## Overview
 
-Turns a vague request or rough draft into an implementation-ready user story by running a structured 9-phase refinement process: establishing initiative context and gathering external information to ground the analysis (Phase 1), analysing the request and qualifying requirements with a scope size check (Phase 2), researching existing context and drafting a story skeleton (Phase 3), checking consistency and scope completeness (Phase 4), validating visually with a user journey diagram (Phase 5), challenging from 9 user-perspective angles (Phase 6), challenging from 8 implementer-perspective angles (Phase 7), producing a final ready-to-implement story with a readiness checklist (Phase 8), and running a final readiness double-check (Phase 9).
+Turns a vague request or rough draft into an implementation-ready user story via a structured 9-phase process: initiative context and external information gathering (Phase 1); request analysis and requirements qualification (Phase 2); context research and story drafting (Phase 3); consistency and scope review (Phase 4); visual validation via a user journey diagram (Phase 5); a 9-angle user-perspective challenge (Phase 6); an 8-angle implementer-perspective challenge (Phase 7); final story output with a readiness checklist (Phase 8); and a final readiness re-validation (Phase 9).
 
 Activate when:
 - The request is vague, incomplete, or internally inconsistent.
@@ -20,6 +21,27 @@ Activate when:
 - The change may affect multiple parts of a system and needs a vertical-slice check.
 - A requirement needs to be refined into a clear, testable story.
 
+### Inputs
+
+#### Required
+- Story request or draft to refine
+
+#### Optional
+- Initiative/epic context, related docs
+
+### Outputs
+
+#### Contents
+- Implementation-ready story, or split stories
+
+#### Changes
+- Story/initiative files under `.assets/`
+
+### Halt Conditions
+- Unresolved ambiguity or open decision remains
+- Human declines to answer a required question
+- Story still too large after a split is proposed
+
 ## Instructions
 
 ### Core Rules
@@ -144,7 +166,7 @@ Before beginning analysis, gather factual context about the system, process, or
 
 #### Step 2 — Requirements loop
 
-Loop asking questions across the 6 areas below until convergence. Apply the Phase navigation rule. A detailed or well-structured input does NOT exempt you from the question loop — treat apparent completeness as a signal to look harder for hidden ambiguities.
+Loop asking questions across the 6 areas below until convergence. Apply the Phase navigation rule and the Core Rules hard gate — a detailed-looking input does not exempt this loop.
 
 **Apply Context Probe rule** throughout this step: whenever a gap in any area could be resolved by an external document, spec, URL, screenshot, or artifact not yet in the Context Summary, ask for it specifically.
 
@@ -157,9 +179,9 @@ Loop asking questions across the 6 areas below until convergence. Apply the Phas
 | Edge cases | What unusual but valid scenarios must work? What invalid inputs or error paths must be handled? What happens on retries, duplicates, partial failure, or missing data? |
 | Dependencies | What upstream or downstream systems affect the change? Are there required approvals, sequencing, or external decisions? Does any migration, rollout, or compatibility concern exist? Is there a real named person — a domain expert, business owner, or decision maker — who can be contacted during implementation if questions arise? (Capture name and role only when they are an actual known person; never fabricate a contact.) |
 
-**Interface and integration scan** (apply Context Probe rule here): before closing Step 2, explicitly check for: external APIs invoked (endpoints, HTTP methods, request/response payloads, authentication, behavior); input/output data (field names, types, formats, valid values, meanings, constraints); documentation links (specs, API references, runbooks); contact names and roles (owners of external systems or business rules); process rules or business logic tied to the story. For any missing detail, ask targeted questions or apply the Context Probe rule to request external sources.
+**Interface and integration scan** (apply Context Probe rule): before closing Step 2, check for external APIs (endpoints, methods, payloads, auth), I/O data (fields, types, formats, constraints), docs/runbooks, contact names/roles, and business rules tied to the story. Ask targeted questions, or apply the Context Probe rule, for anything missing.
 
-Do not proceed to Step 3 while any open decision, unresolved assumption, or ambiguous rule exists. If you find yourself wanting to write "or X" / "TBD" / "to be documented" anywhere, that is a sign you skipped a question.
+Do not proceed to Step 3 while any open decision or ambiguous rule remains (Core Rules hard gate).
 
 #### Step 3 — Scope size evaluation
 
@@ -298,14 +320,7 @@ After all 9 angles converge, use `vscode_askQuestions` (per Phase gate UI rule)
 
 ### Phase 7: Implementer-Perspective Challenge
 
-For each angle, apply the following protocol. The Phase navigation rule (convergence, Skip, Backtracking) governs loop control on top of this protocol.
-
-1. Generate 10–20 specific questions about that angle **in the context of this story** (grounded in what has been gathered, not generic).
-2. Attempt to answer each question from the current story contents.
-3. For every question that cannot be answered, is unanswered, or reveals a gap or inconsistency: elaborate the finding and ask the user via `vscode_askQuestions`.
-4. Apply the Context Probe rule: if any gap could be resolved by an external spec, API reference, interface contract, or other artifact, ask for it specifically.
-5. Only mark the angle complete when all questions are answered or explicitly deferred as named risks.
-6. Do not resolve choice points unilaterally.
+For each angle, apply the Phase 6 per-angle protocol: 10–20 grounded questions, answer what's known, ask the user about gaps via `vscode_askQuestions`, apply the Context Probe rule for implementer artifacts (specs, API references, contracts), and never resolve a choice point unilaterally. The Phase navigation rule governs loop control.
 
 **1. Verifiable acceptance criteria**
 Can every acceptance criterion be independently tested by a developer without ambiguity? Is "done" unambiguous for each item, with no subjective interpretation required? Are criteria specific enough to write automated tests against?
@@ -500,8 +515,20 @@ Apply the same 4 criteria from Phase 2 Step 3. If two or more are met, the story
 - **Request spans multiple independent user outcomes**: always split into separate vertical-slice stories rather than merging into one broad story.
 - **Diagram cannot be generated**: describe the user journey in a plain-language step-by-step walkthrough. The intent of Phase 5 is to externalize the journey — the medium is secondary.
 
+## Anti-Patterns
+
+- **Mistake:** Producing output while a decision is still open.
+  **Why it happens:** The input already looks detailed enough.
+  **Instead:** Apply the hard gate; resolve it via questions first.
+- **Mistake:** Merging independent user outcomes into one story.
+  **Why it happens:** One story feels simpler than several.
+  **Instead:** Split into independently releasable vertical slices.
+- **Mistake:** Treating a skipped Context Probe as unresolved.
+  **Why it happens:** Missing context feels like an open ambiguity.
+  **Instead:** Record it as "not provided," not a blocker.
+
 ## References
 
 - [`agentme-edr-012`](../../012-continuous-xdr-enrichment.md) — Continuous XDR enrichment policy
 - [`agentme-edr-017`](../../017-skill-testing.md) — Skill testing mandate
-- [`agentme-bdr-401`](../../../../bdrs/operations/401-epic-feature-story-planning.md) — Epic/feature/user story planning structure (policy source for the inline reference in Phase 1)
+- [`agentme-bdr-401`](../../../../bdrs/operations/401-plan-epic-feature-story.md) — Epic/feature/user story planning structure (policy source for the inline reference in Phase 1)