agentme 0.33.0 → 0.34.0

package/.xdrs/agentme/edrs/principles/skills/151-refine-user-story/SKILL.test.md

@@ -0,0 +1,316 @@
+---
+skill: 151-refine-user-story
+skill-version: "2.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Vague request refined into a single story
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The workspace has no `.xdrs/` directory. The user says:
+
+"We need to add notifications to the app."
+
+**Expected Behaviour**
+1. Skill classifies the input as vague and restates the current understanding before asking questions.
+2. Skill asks targeted follow-up questions covering problem/value, scope, requirements, flow, edge cases, and dependencies — one group at a time using `vscode_askQuestions` when available.
+3. Skill does NOT produce any story or acceptance criteria while ambiguities remain open.
+4. After all questions are answered and no ambiguity remains, skill performs a consistency check across goal, scope, and acceptance criteria.
+5. Skill reviews each scope item for completeness, edge cases, technical constraint consequences, and missing attachments.
+6. Skill decides whether the work fits in one story; if so, produces one refined story using the output template.
+7. Output contains all required sections: Title, User Story, Scope, Acceptance Criteria.
+
+**Simulated Human Responses**
+1. "Registered users receive notifications. Events that trigger them: a new direct message, a mention in a comment, or a status change on an item they own."
+2. "In-app only (bell icon with a badge counter). No email or push for now."
+3. "Users can mark individual notifications as read or mark all as read. Unread count shown in the header."
+4. "No notifications for system or admin events. Notifications are scoped to the current user only."
+5. "If the user is offline the notification is stored and shown when they next open the app. No real-time delivery guarantee needed yet."
+6. "No limit on stored notifications per user for now. No deletion UI required."
+
+**Assertions**
+- [ ] Skill asks at least one question about who receives notifications and what triggers them before producing any output.
+- [ ] Skill does not output a story while any area in the identification table (problem, scope, requirements, flow, edge cases, dependencies) has an open question.
+- [ ] Final output follows the output template with Title (max 10 words), User Story (As a … I want … so that …), Scope, and Acceptance Criteria sections.
+- [ ] Acceptance criteria items are verifiable and start with a checkbox `- [ ]`.
+
+---
+
+### Scenario 2: User refuses to answer a clarifying question
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The workspace has no `.xdrs/` directory. The user says:
+
+"Add export to PDF for the reports page."
+
+The skill asks: "Should the export include all report data or only the currently filtered view?" The user replies: "I don't know, just decide."
+
+**Expected Behaviour**
+1. Skill classifies the input and identifies the filtering scope as an open decision.
+2. Skill asks the clarifying question about export scope.
+3. When the user refuses to answer, skill notes the item as an unresolved assumption.
+4. Skill does NOT produce a story or acceptance criteria while the assumption is unresolved.
+5. Skill explicitly communicates that it cannot proceed until the assumption is resolved, and re-asks or rephrases the question.
+
+**Assertions**
+- [ ] Skill does not produce a story, acceptance criteria, or output template while the filtering scope is unresolved.
+- [ ] Skill explicitly states that the unresolved assumption blocks output and asks the user to resolve it.
+
+---
+
+### Scenario 3: Request too large — split into vertical slices, one refined, rest deferred
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The workspace has no `.xdrs/` directory. The user says:
+
+"Build a complete user authentication system: registration with email/password, login, password reset via email, and social login with Google."
+
+**Expected Behaviour**
+1. Phase 0 finds no XDRS scope and skips to Phase 1.
+2. Skill classifies the input as too large (bundles multiple independent user outcomes).
+3. Skill asks targeted questions to understand each flow's requirements.
+4. After questions are resolved, skill determines the work cannot fit in one story and proposes splitting into 4 vertical slices: registration, login, password reset, social login.
+5. Skill presents `vscode_askQuestions` with "Accept split — start refining Registration" (recommended) plus options to adjust boundaries or keep the original scope.
+6. User accepts the split and picks "Registration" as the first slice to refine.
+7. Skill restarts from Phase 1 with the narrower registration scope. The remaining 3 slices are recorded as Deferred Stories.
+8. Phases 1–7 run on the registration slice only. At Phase 7, a Deferred Items summary lists the 3 remaining slices.
+9. Because no plan doc is active, skill presents `vscode_askQuestions` asking where to save the deferred slices; user picks BACKLOG.md.
+10. Skill outputs one fully refined story (registration) and appends the 3 deferred slices to BACKLOG.md.
+
+**Simulated Human Responses**
+1. "Registration: email + password only. Password min 8 chars, at least one digit. Email must be verified before the user can log in."
+2. "Login: email + password. No magic links. Session token valid for 7 days. Invalidated on logout."
+3. "Password reset: send a time-limited link to the registered email. Link expires after 1 hour. User sets a new password via the link."
+4. "Google social login: OAuth 2.0. If the Google email matches an existing account, link them. Otherwise create a new account."
+5. "Error handling: show a user-friendly message for invalid credentials, expired links, and OAuth failures. No silent failures."
+6. "No rate limiting, CAPTCHA, or 2FA in scope for now. Each flow ships independently."
+
+**Assertions**
+- [ ] Phase 0 is skipped (no XDRS scope found).
+- [ ] Skill proposes a split at Phase 2 with rationale for each slice boundary.
+- [ ] Skill uses `vscode_askQuestions` to present the split options, not plain text.
+- [ ] After the user accepts, skill restarts Phase 1 for the chosen slice (registration) only.
+- [ ] Final output contains exactly one fully refined story (the chosen slice), using the full output template.
+- [ ] The three deferred slices appear in a Deferred Items summary at Phase 7, each with a one-line description.
+- [ ] Skill does NOT produce a single merged story covering all four flows.
+- [ ] The chosen slice's story is independently shippable and delivers a complete end-to-end user-visible outcome.
+- [ ] No slice is a technical-layer-only story (e.g. "implement the auth database schema" alone is not acceptable).
+
+---
+
+### Scenario 4: Phase gate re-run — user requests deeper pass on Phase 4
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The skill has completed Phase 4 (Consistency & Scope Review) and presents the phase gate. The user selects:
+
+"Re-run Phase 4 — deeper pass"
+
+**Expected Behaviour**
+1. Skill does NOT advance to Phase 5 — it restarts Phase 4 Step 1 (consistency check) and Phase 4 Step 2 (scope item review) with fresh eyes.
+2. During the deeper pass, skill surfaces at least one finding not raised in the first run (e.g. a new edge case or a scope item with an unresolved constraint).
+3. Skill asks a question about the new finding using `vscode_askQuestions`.
+4. After the human responds, Phase 4 converges again and the gate is re-presented.
+5. Skill re-presents the Phase 4 gate with "Continue to Phase 5 — Visual Validation" as the recommended option.
+
+**Simulated Human Responses**
+1. (Re-run Phase 4 selected at gate)
+2. "The empty state message should appear only after a 300 ms delay to avoid a flash on fast networks."
+
+**Assertions**
+- [ ] Skill re-runs Phase 4 (does not skip to Phase 5) when the human selects re-run.
+- [ ] Skill surfaces at least one new finding during the deeper pass.
+- [ ] Skill asks a question about the new finding before re-presenting the gate.
+- [ ] The Phase 4 gate is re-presented after the human responds.
+- [ ] Skill does not advance to Phase 5 until the gate is explicitly confirmed with "Continue".
+
+---
+
+### Scenario 5: Phase 6 user-perspective challenge surfaces a missing journey step
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The story being refined is:
+
+"Add a CSV export button to the reports page so registered users can download the current view."
+
+Phases 1–5 are complete. The skill is running Phase 6, angle 1 (User journey completeness).
+
+**Expected Behaviour**
+1. During angle 1 analysis, skill identifies that the story does not specify what the user sees while the export is being prepared — there is no loading state or download confirmation described.
+2. Skill presents this as a finding and asks: "What should the user see while the export is being prepared — an immediate download, a loading indicator, or a background task with a notification? What feedback confirms the download completed?"
+3. Human answers the question.
+4. Skill incorporates the answer into the story scope and continues to angles 2–9.
+5. Skill does NOT produce the final story until Phase 7 is complete and the readiness checklist passes.
+
+**Simulated Human Responses**
+1. "Show a spinner while generating. When ready, auto-download the file and show a success toast: 'Your CSV is ready'."
+
+**Assertions**
+- [ ] Skill runs Phase 6 analysis before producing any output.
+- [ ] Skill surfaces the missing loading state and download confirmation as a finding during angle 1 (User journey completeness).
+- [ ] Skill asks at least one question about the finding using `vscode_askQuestions` before moving to angle 2.
+- [ ] After the human responds, the answer is reflected in the story scope (loading spinner + success toast added).
+- [ ] Skill does not skip to Phase 7 while any angle has open questions.
+
+---
+
+### Scenario 6: Plan document with pending placeholder stories — user picks one to refine
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The user references an epic plan document at `.xdrs/_local/bdrs/operations/plans/001-epic-improve-checkout.md`. The plan contains:
+
+```
+### Milestone 1: Payment Speed
+**Key tasks:**
+- [Reduce payment steps — pending](.assets/userstory-001-reduce-payment-steps.md)
+- [Save payment method — pending](.assets/userstory-002-save-payment-method.md)
+
+### Milestone 2: Error Recovery
+**Key tasks:**
+- [Retry failed payment — pending](.assets/userstory-001-retry-failed-payment.md)
+```
+
+Each `.assets/userstory-*.md` file contains `**Status:** to-be-refined` plus any preliminary notes captured when the story was created.
+
+**Expected Behaviour**
+1. Skill activates Phase 0, detects the plan document, and parses all Milestone key tasks.
+2. Skill reads each linked `.assets/userstory-*.md` file and checks for `**Status:** to-be-refined`. Identifies all three as pending.
+3. Skill presents a `vscode_askQuestions` list of the three pending stories plus a "New story" option.
+4. User picks the "Reduce payment steps" story from Milestone 1.
+5. Skill reads the placeholder file — extracts NNN (001) and slug (`reduce-payment-steps`) from its `**Story ID:**` line; carries any notes into Phase 1 as starting context.
+6. Skill proceeds to Phase 1 using the placeholder's title and notes as the subject.
+7. After Phase 7, skill overwrites `.assets/userstory-001-reduce-payment-steps.md` with the fully refined content (no `**Status:**` line).
+8. Skill updates the task entry link text in Milestone 1 to `- [Reduce payment steps at checkout](.assets/userstory-001-reduce-payment-steps.md)`.
+
+**Assertions**
+- [ ] Phase 0 detects pending stories by reading file content (`**Status:** to-be-refined`), not by task entry name format.
+- [ ] All three pending stories are listed before Phase 1 begins.
+- [ ] NNN and slug are extracted from the placeholder file's `**Story ID:**` line, not from the task entry text.
+- [ ] After Phase 7, the story detail file is overwritten with the refined content and no `**Status:**` field.
+- [ ] The Milestone 1 task entry link text is updated to the refined story title; the file path stays the same.
+- [ ] Skill does NOT offer "Save to BACKLOG.md" for deferred items while a plan doc is active.
+
+---
+
+### Scenario 7: Refined story output writes asset file and updates plan Milestone link
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. Phase 0 has detected an active plan doc at `.xdrs/_local/bdrs/operations/plans/002-epic-onboarding.md` with Milestone 1: "First Login Experience". The user is refining a new story to be placed there.
+
+After completing Phases 1–6, Phase 7 produces the final story: "Show personalised welcome screen on first login".
+
+**Expected Behaviour**
+1. Phase 7 determines the next NNN in the plan's `.assets/` folder (no existing userstory files → NNN = 001).
+2. Skill writes `.assets/userstory-001-welcome-screen-first-login.md` using the output template sections: Title, User Story, Scope, Edge Cases, Out of Scope, Constraints, Detailed Specs, Acceptance Criteria, Attachments, plus a back-link to the epic plan.
+3. Skill inserts `- [Show personalised welcome screen on first login](.assets/userstory-001-welcome-screen-first-login.md)` as a key task in Milestone 1 of the plan doc.
+
+**Assertions**
+- [ ] Story detail file is created at the correct path inside the plan's `.assets/` folder.
+- [ ] File uses all required template sections including `## Constraints` and `## Detailed Specs`.
+- [ ] File includes a back-link to the parent epic plan.
+- [ ] The plan doc's Milestone 1 key tasks section contains a markdown link entry pointing to the new file.
+- [ ] NNN is 001 (first story in this epic's `.assets/` folder).
+
+---
+
+### Scenario 8: No XDRS scope — skill asks where to save and defaults to workspace root
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The workspace has no `.xdrs/` directory. The user says:
+
+"I need to refine a story: users should be able to reset their PIN via SMS."
+
+**Expected Behaviour**
+1. Phase 0 finds no XDRS scope and skips to Phase 1 immediately.
+2. Skill runs all phases normally.
+3. At Phase 7, after producing the final story, skill asks via `vscode_askQuestions` where to save the story file, defaulting to `userstory-001-reset-pin-via-sms.md` at the workspace root.
+4. If the story is split, the deferred slices prompt offers: add to existing epic plan, create new epic plan, or save to `BACKLOG.md`.
+
+**Assertions**
+- [ ] Phase 0 does not block or present any plan-doc questions when no XDRS scope exists.
+- [ ] Phase 7 asks for a save location with a clear default path.
+- [ ] The story file is saved to the user-confirmed path.
+- [ ] Split deferred stories trigger a destination choice (not silently written to BACKLOG.md).
+
+---
+
+### Scenario 9: Story lacking detailed specs is flagged and sent back for more refinement
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The workspace has no `.xdrs/` directory. The user is refining:
+
+"Integrate with the payments provider so users can pay by card."
+
+After Phase 2 Step 1, no API endpoints, no payload structures, no documentation links, and no contact names have been surfaced.
+
+**Expected Behaviour**
+1. Phase 2 Step 1 interface-and-integration scan identifies that no external API details are recorded despite the story clearly involving a payment provider integration.
+2. Skill asks targeted questions: "What is the payment provider? Do you have an API reference or documentation link? What is the payment flow — which endpoints are called, in what order, with what payload?"
+3. Human provides partial answers: "We use Stripe. Charge endpoint. Don't know the exact payload."
+4. Skill asks follow-up: "Can you share the Stripe API documentation link or the name of someone who owns the Stripe integration?"
+5. Phase 7 readiness checklist item for Detailed Specs fails until sufficient detail is provided (endpoint, payload shape, or doc link).
+
+**Assertions**
+- [ ] Phase 2 Step 1 explicitly surfaces the missing integration details before Step 2 is reached.
+- [ ] Skill does not produce a final story while `## Detailed Specs` remains empty for a story involving an external API.
+- [ ] Phase 7 checklist item for Detailed Specs is checked only after sufficient detail (at minimum a doc link or endpoint) is provided.
+- [ ] Final output's `## Detailed Specs` section contains at least the Stripe API reference and the charge endpoint.
+
+---
+
+### Scenario 10: XDRS scope active, start fresh, story split — Phase 7 asks where to put deferred slices
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. Phase 0 detected an XDRS scope with two existing epic plans but the user chose "start fresh — no plan context". During Phase 2, the story is found to be too large and split into three slices. The user accepts the split and starts refining Slice 1.
+
+**Expected Behaviour**
+1. Phase 0 detects XDRS scope, presents epic plan list plus "Start fresh" option, user picks "Start fresh".
+2. Phases 1–7 run normally for Slice 1.
+3. At Phase 7, because the context is "start fresh" (no active plan doc), the two deferred slices trigger a `vscode_askQuestions` prompt: "Where should the deferred story slices go?" with options: add to an existing epic plan (lists found epics), create a new epic plan, or save to BACKLOG.md.
+4. Skill applies the chosen action (e.g., creates placeholder files for the two deferred slices and inserts `- [Slice description — pending](.assets/userstory-NNN-slug.md)` task entries in the chosen epic plan, or appends descriptions to BACKLOG.md).
+
+**Assertions**
+- [ ] Phase 0 presents the XDRS epic plan list even in "start fresh" mode.
+- [ ] Deferred slices do NOT go silently to BACKLOG.md when an XDRS scope is present.
+- [ ] Phase 7 presents a `vscode_askQuestions` destination choice for deferred slices.
+- [ ] If an epic plan is chosen, deferred slices are created as placeholder files and inserted as `- [description — pending](.assets/...)` link entries in the correct Milestone.
+
+---
+
+### Scenario 11: Very large story split into multiple slices — no XDRS scope — deferred slices saved to BACKLOG.md
+
+**Trigger / Input**
+You are an agent with the `151-refine-user-story` skill loaded. The workspace has no `.xdrs/` directory. The user says:
+
+"I need to build the entire checkout flow: cart review, address selection, payment method entry, coupon validation, order summary, fraud check, payment processing, order confirmation email, and post-purchase upsell screen."
+
+**Expected Behaviour**
+1. Phase 0 finds no XDRS scope and skips to Phase 1 immediately.
+2. Phase 1 classifies the input as a vague, massively oversized request covering 9+ distinct behaviours.
+3. Phase 2 determines the story is far too large for a single story (estimated > 2 weeks). Skill proposes splitting into vertical slices, for example:
+   - Slice 1: Review cart and confirm address
+   - Slice 2: Enter and validate payment method
+   - Slice 3: Apply coupon and show order summary
+   - Slice 4: Fraud check and payment processing
+   - Slice 5: Order confirmation email
+   - Slice 6: Post-purchase upsell screen
+4. Skill presents `vscode_askQuestions` asking which slice to refine first; user picks Slice 1.
+5. Phases 1–7 run on Slice 1 only. The remaining 5 slices are tracked as Deferred Stories.
+6. At Phase 7, because no plan doc is active, skill presents `vscode_askQuestions`:
+   - **"Save deferred slices to BACKLOG.md"** (recommended)
+   - **"Save to a different file"** (open box)
+   - **"Skip — do not save"**
+7. User picks "Save deferred slices to BACKLOG.md". Skill appends the 5 deferred slices under a `## Deferred Stories` heading in `BACKLOG.md` at the workspace root (creating the file if needed), each with a one-line description and split rationale.
+8. Skill outputs the refined story for Slice 1 only.
+
+**Assertions**
+- [ ] Phase 0 is skipped entirely (no XDRS scope found).
+- [ ] Skill explicitly states at Phase 2 that the request is too large and must be split.
+- [ ] All identified slices are presented for user selection before any refinement begins.
+- [ ] Only the user-selected slice (Slice 1) is refined through Phases 1–7.
+- [ ] The remaining slices appear in a Deferred Items summary at Phase 7.
+- [ ] `vscode_askQuestions` is used at Phase 7 to ask where to save deferred slices (not silently appended).
+- [ ] BACKLOG.md is created (or appended to) at the workspace root with a `## Deferred Stories` section.
+- [ ] Each deferred slice in BACKLOG.md has a one-line description and reason for deferral.
+- [ ] The final output contains exactly one refined story (Slice 1), not all slices.
+- [ ] Skill does NOT offer BACKLOG.md for deferred items from an active plan doc (this scenario has no plan doc — condition satisfied).

package/.xdrs/agentme/index.md

@@ -17,7 +17,7 @@ The `agentme` scope is a curated library of XDRs and skills encoding best practi
 
 ### What this scope covers
 
-The `agentme` scope provides opinionated, reusable guidance on how to scaffold, build, test, and ship software projects. It targets AI coding agents and human developers who want consistent, high-quality defaults across JavaScript, Go, and Python projects.
+The `agentme` scope provides opinionated, reusable guidance on how to scaffold, build, test, and ship software projects. It targets AI coding agents and human developers who want consistent, high-quality defaults across JavaScript, Go, and Python projects. It also provides business decisions for software development project management (epics, features, user stories).
 
 All content in this scope is published and consumed by external projects. Changes must be clear, backwards-compatible where possible, and thoroughly reviewed before merging.
 
@@ -25,6 +25,11 @@ All content in this scope is published and consumed by external projects. Change
 
 The `agentme` EDRs cover project tooling and structure for each supported language, CLI standards, monorepo layout, CI/CD pipelines, and observability. See the full list in the [EDRs Index](edrs/index.md).
 
+### Business decisions
+
+The `agentme` BDRs cover software development project management practices: how to organize and track epics, features, and user stories using XDRS plan documents. See the full list in the [BDRs Index](bdrs/index.md).
+
 ## Type Indexes
 
 - [EDRs Index](edrs/index.md) - Engineering decisions for coding best practices and project tooling
+- [BDRs Index](bdrs/index.md) - Business decisions for software development project management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"

package/.xdrs/agentme/edrs/principles/skills/150-plan-mode-consistency/SKILL.md

@@ -1,184 +0,0 @@
----
-name: 150-plan-mode-consistency
-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 —
-  software features, systems, research, documents, processes, or any other task — before execution
-  begins. This skill defines the required pre-execution structured workflow. It MUST be read from
-  the XDRS repository even when not directly exposed in the .agents skills folder. Activate in
-  full mode for non-trivial tasks and in abbreviated mode (Phases 3–5 collapsed, Phase 4 marked
-  not applicable) for trivial single-step tasks.
-metadata:
-  author: flaviostutz
-  version: "1.0"
----
-
-## Overview
-
-Ensures that every plan is deeply validated through iterative consistency checks, visual externalization, and multi-angle challenges before execution starts. The skill is not designed to make human work easier — its purpose is to identify precisely where human experience, feeling, and domain knowledge are irreplaceable, and to demand that input before moving forward.
-
-**No-assumption rule**: The agent performs all analysis autonomously. Surface findings as questions only when they are dubious, non-obvious, risky, or require subjective judgment — obvious and deterministic findings must be stated and the agent must continue without pausing. For findings with major impact on downstream users or consumers (breaking changes, behavior regressions, removals), do not ask — emit a prominently formatted **SEVERE WARNING** with a clear description of the impact and continue. Do not defer questions to the end of a check, round, or phase — raise them as soon as they arise. The human is the oracle for domain knowledge, intent, and subjective decisions; the agent is the oracle for everything deterministic.
-
-**Task tracking rule**: Use the todo list tool throughout this entire skill. Before starting each phase, create a todo for it and mark it in-progress. Mark it completed immediately when done. For Phase 3 (consistency checks), create a todo for each check (a–g) at the start of each round and mark them individually. For Phase 5 (challenge angles), create a todo for each of the 11 angles before beginning Phase 5 and mark each completed after the human responds to any question raised, or immediately if no question was raised for that angle. An angle todo MUST NOT be marked complete if a subjective decision was resolved without asking the human — if this is detected, flag it as a HITL violation, re-open the todo, surface the decision to the human as a clarifying question, and only mark it complete after the human responds. This ensures no check, round, or angle is silently skipped and no subjective decision is self-resolved.
-
-**Round budget rule**: The entire skill runs on a global budget of at most 30 rounds. A round is one human interaction in which the agent asks 1–5 related questions together. Rounds are drawn from this shared budget across all phases in order. Stop early when two consecutive rounds return no new questions worth asking — do not exhaust the budget for its own sake.
-
-## Instructions
-
-### Phase 1: Activate Plan Mode
-
-1. Switch to plan mode. Do not write, edit, or execute anything until the plan is fully validated through Phase 6.
-2. State the goal in one sentence: what problem is being solved and what the expected outcome is.
-3. State the scope boundaries explicitly: what is included and what is explicitly excluded.
-4. Ask the human: "Does this goal statement and scope match your intent? Is anything missing or wrong?" Wait for the answer and incorporate it before continuing.
-
-### Phase 2: Research, Dependencies, and Draft Plan
-
-1. Research the existing context: relevant files, prior decisions, established conventions, and analogous patterns already in place.
-2. For each contextual input, constraint, or dependency found (existing files, prior decisions, external systems, in-progress work by others), surface non-obvious, risky, or subjective items to the human and ask only when needed. Batch 1–5 related questions into a single round when multiple items need human input. Proceed without asking for obvious or deterministic context items.
-3. Draft a plan with ordered steps, items to create or modify, and a verification step at the end.
-4. Present the draft and ask: "Does this match your intent? What am I missing?" Wait for the answer before continuing.
-
-### Phase 3: Iterative Consistency Checks
-
-**Trivial tasks**: Run exactly one abbreviated round covering only checks (a), (e), and (f). Skip the remaining checks and mark them as not applicable. Proceed directly to Phase 4 after the single round.
-
-**Non-trivial tasks**: Run as many rounds as needed from the global budget. Each round asks 1–5 related questions spanning one or more checks (a–g). For each check, ask only for findings that are dubious, relevant, subjective, or risky — state obvious findings and continue. Stop when two consecutive rounds surface no new questions.
-
-Each round runs the following checks in order:
-
-- **(a) Internal consistency**: Are there contradictions between steps? Do the scope boundaries align with the implementation steps?
-- **(b) Dry run**: Walk through the plan with the most complex realistic scenario. Where does it break or leave gaps?
-- **(c) Component consistency**: Do all elements of the plan work together as a coherent whole? Are there missing connections between parts?
-- **(d) XDR alignment**: Does this plan align with the relevant XDRs governing this area? Have the right policies been consulted?
-- **(e) Feasibility**: Is each step actually achievable given the current context, constraints, and available resources?
-- **(f) Completeness**: Is anything missing that would leave the task half-done or the outcome broken for its consumer?
-- **(g) Scope creep check**: Has the plan grown beyond the original request? Flag any additions and ask the human to confirm or reject each one explicitly before continuing.
-
-**Convergence signals** (non-trivial tasks only): Stop running rounds when the last 2 consecutive rounds produce only single-sentence answers with no new issues surfaced. Do not stop on a round count alone — stop when the checks genuinely have nothing left to surface.
-
-### Phase 4: Visual Consistency Validation
-
-**Trivial tasks**: Mark this phase as **not applicable** and state this explicitly before moving to Phase 5. Do not skip silently.
-
-**Non-trivial tasks**:
-1. Choose the diagram type that best externalizes this plan's structure:
-   - **Flowchart** — step-by-step decision flows and process branches
-   - **Concept map** — ideas, relationships, and conceptual structure
-   - **Dependency graph** — components and their dependencies
-   - **Sequence diagram** — call flows, API interactions, and temporal order
-   - **State diagram** — lifecycle states and transitions
-   - **Activity diagram** — business workflows with parallel paths
-   - **Entity diagram** — data models and relationships
-   2. Generate the diagram.
-   3. Ask the human: "Does this diagram match your mental model of the solution?" Wait for the answer.
-   4. If the diagram reveals gaps or inconsistencies not yet surfaced, return to Phase 3 before continuing.
-
-### Phase 5: Challenge from 11 Distinct Angles
-
-Each angle is an analysis step. Run the angle and present findings. Batch questions from related angles into a single round of 1–5 questions when findings are related — batching questions is permitted, skipping analysis is not. For obvious or factual findings, state them and proceed immediately. For findings with major impact on users, emit a **SEVERE WARNING** and continue without asking. Ask clarifying questions whenever findings are ambiguous, subjective, risky, or very relevant — do not resolve those points unilaterally.
-
-#### Plan quality angles
-
-**1. Prompt faithfulness**
-Go back to the original request word by word. Is every part of the request covered? Is anything included in the plan that was not asked for? Identify gaps and additions explicitly.
-
-**2. Local context consistency**
-Does the plan account for existing files, decisions, and constraints already in place? Does it contradict anything already established in the codebase, repository, or context?
-
-**3. Goal achievability**
-Walk the end state step by step: if every step in the plan is executed exactly as written, does the desired outcome actually result? State the end state explicitly. Ask the human to confirm only if there is genuine doubt about whether the outcome matches their expectation.
-
-**4. Ambiguity scan**
-Is any step or decision in the plan interpretable in more than one way? Every ambiguity is a future mistake. List all ambiguous points and ask the human to resolve each one.
-
-**5. Pre-mortem**
-Assume the plan is executed and fails to reach the goal. What was the most likely reason? Identify the plan's most fragile assumption or weakest step.
-
-**6. Security and privacy scan**
-Does the plan or its output expose sensitive information, create privacy risks, or introduce misuse vectors? This applies to any task type: documentation, code, processes, data handling, communications. If findings are present and require a subjective decision to resolve, ask the human. For clear and obvious mitigations, state them and continue.
-
-**7. Success criteria and falsifiability**
-How will we know this plan succeeded or failed? Are the success criteria concrete enough to be measurable and observable? If they are vague, the outcome cannot be evaluated. If the criteria are already clear and measurable, state the assessment and continue. Ask the human only when criteria are vague or require their input to sharpen.
-
-**8. Second-order effects**
-What changes as a side effect of executing this plan beyond the intended outcome? Does solving this problem create a new problem elsewhere — in adjacent systems, files, processes, or stakeholders? List the side effects. Ask the human whether they are acceptable only when the effects are non-obvious or the decision is subjective.
-
-**9. Steelman the opposition**
-What is the strongest case against this approach? What would a well-informed critic say about this plan? Present the strongest objection. Ask the human to respond if the objection raises a genuine risk or requires a subjective decision — otherwise state the counter-argument and continue.
-
-#### Output quality angles
-
-**10. Output scenario dry runs**
-Simulate 5 realistic usage scenarios of the expected output by its actual consumer. For each scenario, ask: "Does the output serve its consumer in this situation?" Use scenarios that cover typical use, edge cases, and at least one adversarial or failure case.
-
-Examples of scenario framing:
-- If the output is operator documentation: "A worker needs to reset the machine at 2 AM — will they find the procedure in under 2 minutes?"
-- If the output is an API: "A developer calling this endpoint with a malformed payload — what happens?"
-- If the output is a business process: "An employee following this process on their first day — will they complete it without asking for help?"
-
-Whenever a scenario reveals ambiguity or requires a subjective judgment, stop and ask the human a clarifying question. Do not resolve subjective decisions unilaterally.
-
-**11. Output internal consistency**
-Check that the planned output is internally consistent: no contradictions between parts, no gaps between sections, all elements serve the same goal. Run approximately 3 rounds until answers converge to single sentences with no new issues surfaced.
-
-### Phase 6: Pre-Execution Readiness
-
-Before approving execution, verify ALL items in the checklist below. If any item cannot be checked, return to the relevant phase and resolve it first. For trivial tasks, mark non-applicable items explicitly as **N/A** rather than leaving them unchecked or omitting them.
-
-- [ ] Consistency rounds converged (convergence signals met — last 2 rounds produced only single-sentence answers with no new issues) *(trivial tasks: single abbreviated round completed)*
-- [ ] All 11 challenge angles completed with human input received for every ambiguity and subjective decision *(trivial tasks: single abbreviated round — mark remaining angles N/A)*
-- [ ] Diagram generated and confirmed by the human *(trivial tasks: N/A — mark explicitly)*
-- [ ] No unresolved human questions outstanding
-- [ ] Scope confirmed by the human with no silent expansions
-- [ ] Any irreversible or high-impact steps have a mitigation or fallback noted *(trivial tasks: N/A if no irreversible steps)*
-
-Only proceed to execution when every item is checked or explicitly marked N/A. Do not start execution to escape planning discomfort — only start when confidence is genuine and all items are verified.
-
----
-
-## Anti-Patterns
-
-Avoid these common failure modes:
-
-- **Planning theater**: running rounds without real critical thinking. The quality of questioning matters more than the count of rounds. 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.
-
-## Re-Plan Triggers
-
-Stop execution and return to Phase 1 if any of the following occur:
-
-- A discovered assumption underlying the plan is wrong.
-- The scope has expanded by more than approximately 20% beyond the original request.
-- Two consecutive execution steps fail unexpectedly and the root cause points to a planning gap.
-
-## Examples
-
-**Input**: "Add a rate-limiting feature to the API."
-
-- Phase 1: Goal stated as "rate-limit all POST endpoints to 100 req/min per user; internal service calls excluded." Human confirms.
-- Phase 2: Discovers existing middleware and an in-progress PR touching the same path. Human asked about each before drafting.
-- Phase 3: Round 1 — check (a) finds the plan references a `RateLimiter` class not yet decided on; human asked to clarify. Round 5 — all checks return trivial answers; convergence reached.
-- Phase 4: Sequence diagram generated. Human confirms it matches their model.
-- Phase 5: Angle 8 (second-order effects) reveals that rate-limiting breaks an existing test suite that sends rapid sequential requests; human decides to add a test bypass header. Angle 9 (steelman) surfaces that Redis dependency adds operational complexity; human accepts the trade-off.
-- Phase 6: All items checked. Execution approved.
-
-**Input**: "Write operator documentation for the conveyor belt system."
-
-- Phase 5, angle 10 (output dry runs): Scenario 1 — "An operator needs to restart the belt after an emergency stop at midnight." The draft plan has no emergency stop section; human asked whether to add it. Scenario 3 — "Operator reading on a mobile phone." Human asked whether a condensed quick-reference card is needed alongside the full manual.
-
-## Edge Cases
-
-- **Trivial changes** (typo fixes, single-line formatting): Phases 3–5 may be shortened to a single abbreviated round. Phase 4 (diagram) may be skipped, but MUST be explicitly noted as not applicable in the task tracking todo with a brief reason (e.g., "Phase 4: N/A — trivial single-step change"). Phase 6 checklist still applies — mark non-applicable items explicitly.
-- **Agent that insists it knows the answer**: Do not skip any phase because the agent expresses confidence. Confidence is not a substitute for consistency checks.
-- **Diagram cannot be generated**: Describe the flow in a plain-language walkthrough step by step. The intent of Phase 4 is to externalize the plan's structure — the medium is secondary.
-- **Scope change discovered mid-planning**: If Phase 3 or Phase 5 reveals that the scope must change significantly, restart from Phase 2 with the revised scope. Do not patch the plan incrementally without a full re-check.
-- **Human is unavailable for a step**: Note the unanswered question explicitly in the plan. Do not proceed past that point until the human responds.
-
-## References
-
-- [`agentme-edr-012`](../../012-continuous-xdr-enrichment.md) — Continuous XDR enrichment policy
-- [`agentme-edr-501`](../../../governance/501-project-quality-standards.md) — Project quality standards
-- [`agentme-edr-017`](../../017-skill-testing.md) — Skill testing mandate

package/.xdrs/agentme/edrs/principles/skills/150-plan-mode-consistency/SKILL.test.md

@@ -1,88 +0,0 @@
----
-skill: 150-plan-mode-consistency
-skill-version: "1.0"
----
-
-## Test Scenarios
-
-### Scenario 1: New feature implementation
-
-**Trigger / Input**
-
-"Add pagination to the user listing endpoint."
-
-**Expected Behaviour**
-
-The skill activates plan mode immediately. Before writing any code or editing any file, it: (1) states the goal and scope and asks the human to confirm; (2) batches related dependency questions into rounds of 1–5 questions each; (3) runs iterative consistency checks drawing from the global 30-round budget, each round asking 1–5 questions across one or more checks (a–g), stopping when two consecutive rounds surface no new questions; (4) generates a diagram and asks the human to confirm it; (5) analyzes all 11 challenge angles, batching related questions from multiple angles into rounds of 1–5 questions; (6) verifies the Phase 6 checklist before approving execution.
-
-**Simulated Human Responses**
-1. "Yes, goal and scope match exactly."
-2. "Route handler conventions look correct. Database query pattern is right."
-3. "No contradictions. The approach covers the edge cases."
-4. "Confirmed — no new issues."
-5. "The diagram matches my mental model."
-6. "Everything in scope as requested. No security concerns."
-7. "Success means all list responses include a `next` cursor and respect `limit`. Side effects are acceptable."
-8. "The caching layer is the most fragile assumption. The approach is otherwise sound."
-9. "All five scenarios work. Output is internally consistent."
-
-**Assertions**
-
-- [ ] Skill does not write or edit any file before Phase 6 is complete.
-- [ ] Skill asks the human to confirm the goal and scope in Phase 1 before proceeding.
-- [ ] Each human interaction round across all phases contains 1–5 questions grouped together.
-- [ ] Total number of human interaction rounds across all phases does not exceed 30.
-- [ ] Skill stops asking rounds when two consecutive rounds surface no new questions.
-- [ ] Skill generates a diagram in Phase 4 and asks the human to confirm it.
-- [ ] All 11 challenge angles are analyzed; related angles may share a round.
-- [ ] Phase 6 checklist is verified before execution is approved.
-
-### Scenario 2: Trivial change
-
-**Trigger / Input**
-
-"Fix the typo 'authentification' → 'authentication' in the README."
-
-**Expected Behaviour**
-
-The skill acknowledges this as a trivial single-step change. Phases 3–5 are abbreviated to a single round. Phase 4 (diagram) is marked as not applicable. Phase 6 checklist is still performed with non-applicable items explicitly marked.
-
-**Assertions**
-
-- [ ] Skill does not run multiple iterative consistency rounds for a trivial change.
-- [ ] Skill explicitly marks Phase 4 as not applicable rather than skipping it silently.
-- [ ] Phase 6 checklist is still performed before execution.
-- [ ] Non-applicable checklist items are explicitly noted as such.
-
-### Scenario 3: Overconfident agent wants to skip planning
-
-**Trigger / Input**
-
-"I already know exactly how to implement this caching layer — let's skip planning and just implement it."
-
-**Expected Behaviour**
-
-The skill explicitly states that agent confidence is not a substitute for consistency checks and proceeds with all 6 phases regardless of the expressed certainty level.
-
-**Assertions**
-
-- [ ] Skill does not skip any phase because the agent expressed confidence.
-- [ ] Skill explicitly states the no-assumption rule: confidence does not replace consistency checks.
-- [ ] Phase 1 is still executed — goal and scope are stated and confirmed with the human.
-
-### Scenario 4: Agent resolves a subjective output design decision without asking the human
-
-**Trigger / Input**
-
-During angle 10 (output scenario dry runs), a scenario reveals that documentation can be structured in two ways — a single long document or a set of short quick-reference cards. The agent picks the single long document and proceeds to angle 11 without asking.
-
-**Expected Behaviour**
-
-The skill flags this as a violation of the no-assumption rule and the HITL requirement. Subjective output design decisions must be surfaced to the human as a clarifying question — the agent must not resolve them unilaterally. The skill pauses, presents the two options, and asks the human to decide before continuing.
-
-**Assertions**
-
-- [ ] Skill does not proceed past a subjective design decision without asking the human.
-- [ ] Skill explicitly frames the question as a clarifying question, not a confirmation request.
-- [ ] Skill waits for the human's answer before continuing to the next angle.
-- [ ] Violation is noted if the agent attempted to self-resolve a subjective decision.