agentme 0.34.0 → 0.35.0

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

@@ -8,7 +8,7 @@ description: >
   the XDRS repository even when not directly exposed in the .agents skills folder.
 metadata:
   author: flaviostutz
-  version: "2.7"
+  version: "2.8"
 ---
 
 ## Overview
@@ -17,7 +17,7 @@ Ensures that every plan is deeply validated through iterative consistency checks
 
 **Questioning rule**: Ask questions about all findings proactively — skip only trivially obvious ones with no decision weight. Use `vscode_askQuestions` when available; ask at most 4–5 tightly related questions per call. Before each new round, explicitly state what territory has not yet been explored and will be the focus of this round (in structured phases such as Phase 4 or Phase 6, state which predefined check or angle you are covering next) — do not re-ask questions already addressed in previous rounds. Never self-resolve a choice point, and never produce output, plan sections, or decisions while any open decision, unresolved assumption, or ambiguity remains — embed nothing as 'or X / TBD / to be decided' — resolve through questions first. 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.
 
-**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 4 (consistency checks), create a todo for each check (a–i) before beginning Phase 4 and mark each completed when that check individually converges. For Phase 6 (challenge angles), create a todo for each of the 18 angles before beginning Phase 6 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 any decision was self-resolved without asking the human (per the Questioning rule) — 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 decision is self-resolved.
+**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 4 (consistency checks), create a todo for each check (a–i) before beginning Phase 4 and mark each completed when that check individually converges. For Phase 6 (challenge angles), create a todo for each of the 9 angles before beginning Phase 6 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 any decision was self-resolved without asking the human (per the Questioning rule) — 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 decision is self-resolved.
 
 **Phase navigation rule**: Governs loop control, convergence, and phase transitions across all phases:
 - **Loop**: within each phase, loop asking questions until convergence or Skip. Convergence means the last 2 consecutive rounds produced only single-sentence answers with no new issues surfaced — do not stop on a round count alone; stop only when checks genuinely have nothing left to surface. Explicit human confirmation that the phase output is correct also counts as convergence.
@@ -85,21 +85,21 @@ If the feature qualifies as too large, propose a split into 2–4 coherent parts
 
 If the human accepts the split, restart the entire planning process from Phase 1 with the new narrower scope. The deferred parts are preserved in the Deferred Features list and will be surfaced again at the Phase 7 handoff gate.
 
-4. Present a brief feature summary — a short bullet list of what will be built or changed, written in plain language the requester can validate at a glance. Then use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
+Present a brief feature summary — a short bullet list of what will be built or changed, written in plain language the requester can validate at a glance. Then use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
    - **"Continue to Phase 3 — Research and Draft Plan"** (recommended when scope is clear and agreed) — proceed with research and drafting.
-   - **"Re-run Phase 2 — deeper pass"** — repeat all steps with fresh eyes, prioritising areas not yet fully explored, then re-present this gate.
+   - **"Re-run Phase 2: Requirements Qualification — deeper pass"** — repeat all steps with fresh eyes, prioritising areas not yet fully explored, then re-present this gate.
    - **"Add a comment or correction"** (open box) — re-run Phase 2 in full, treating the comment as additional context and constraints, then re-present this gate.
 
 ### Phase 3: 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), ask questions about all non-trivial items. For each dependency or context item, apply the Phase navigation rule: loop asking questions until that item converges before moving to the next. Only skip asking for trivially obvious or deterministic context items with no decision weight.
-3. Draft a plan with ordered steps, items to create or modify, and a verification step at the end. The plan MUST include two dedicated sections:
+3. Draft a plan with ordered steps, items to create or modify, and a verification step at the end. The plan MUST include a dedicated phase for test generation and execution whenever applicable — this phase must appear as an explicit step in the ordered plan, not only in the verification section. It must specify: (a) what tests to create or extend (unit, integration, end-to-end, or manual); (b) the exact commands or manual steps to run them; (c) the expected outcome for each. Examples: "Generate unit tests for X and run `npm test` — expect all pass", "Run integration tests with `make test-integration` — verify no regressions", "Manually open the generated document and verify sections Y and Z look correct". If no automated or manual tests apply, explicitly state why and mark the phase N/A. The plan MUST also include two dedicated sections:
    - **Quality Verification Strategy**: (a) existing checks that must continue to pass; (b) new checks required for the task — for code: unit tests, integration tests, linting, type checking, dead code detection, security/dependency audit, schema/contract validation; for documents, analyses, and policies: proofreading, fact-checking, citation and link validation, policy compliance review, peer review, readability check; (c) exact executable steps or commands for each check; (d) what each check verifies. A plan without this section is incomplete.
    - **Unverified References**: any resource referenced in the plan but not verified during planning must be listed here as *"unverified — must verify before use"* with a concrete first-step verification. For code: file paths, function names, CLIs, library APIs (e.g., `which cmd`, `npm list pkg`). For documents and analyses: statistics, quotes, cited studies, named organizations or people, URLs, legal or regulatory references. This section is the primary defense against fabricated claims surfacing only at execution time.
 4. Present the draft and use `vscode_askQuestions` (per Phase gate UI rule) to ask: "Does this draft match your intent? What verification checks exist today, and what new checks will confirm the key outcomes?" Present at least these options:
    - **"Continue to Phase 4 — Consistency Checks"** (recommended when no gaps remain) — advance.
-   - **"Re-run Phase 3 — explore deeper"** — repeat the research and drafting pass looking for context, dependencies, or constraints not yet surfaced, then re-present the gate.
+   - **"Re-run Phase 3: Research, Dependencies & Draft Plan — explore deeper"** — repeat the research and drafting pass looking for context, dependencies, or constraints not yet surfaced, then re-present the gate.
    - **"Add a comment or correction"** (open box) — re-run Phase 3 in full, treating the comment as additional context and constraints, then re-present this gate.
    Wait for the answer before continuing.
 
@@ -137,7 +137,7 @@ Checks to run in order:
 
 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.
-- **"Re-run Phase 4 — deeper pass"** — restart all checks (a–i) with fresh eyes, prioritising angles and scenarios not yet explored, then re-present this gate.
+- **"Re-run Phase 4: Consistency Checks — deeper pass"** — restart all checks (a–i) with fresh eyes, prioritising angles and scenarios not yet explored, then re-present this gate.
 - **"Add a comment or correction"** (open box) — re-run Phase 4 in full, treating the comment as additional context and constraints, then re-present this gate.
 
 ### Phase 5: Visual Consistency Validation
@@ -161,17 +161,17 @@ After all checks (a–i) converge, use `vscode_askQuestions` (per Phase gate UI
 2. **Generate all selected diagrams** in sequence, each with a one-line description of what it is meant to reveal.
 
 3. Use `vscode_askQuestions` (per Phase gate UI rule) to ask: "Do these diagrams match your mental model of the solution? Is any important perspective missing?" Present at least these options:
-   - **"Continue to Phase 6 — 18 Challenge Angles"** (recommended when the diagrams match) — advance.
-   - **"Re-run Phase 5 — add or replace a diagram"** — add a missing perspective or replace one with a different type, then re-present this gate.
+   - **"Continue to Phase 6 — 9 Challenge Angles"** (recommended when the diagrams match) — advance.
+   - **"Re-run Phase 5: Visual Consistency Validation — add or replace a diagram"** — add a missing perspective or replace one with a different type, then re-present this gate.
    - **"Add a comment or correction"** (open box) — re-run Phase 5 in full, treating the comment as additional context and constraints, then re-present this gate.
 
 4. If any diagram reveals gaps or inconsistencies not yet surfaced, return to Phase 4 before continuing.
 
-### Phase 6: Challenge from 17 Distinct Angles
+### Phase 6: Challenge from 9 Distinct Angles
 
 Each angle is an analysis step. **For each angle:** formulate 5–10 challenge questions grounded in the current plan and broader context (codebase, prior decisions); reason through each surfacing evidence — not self-resolving; bring unresolved or subjective questions to the human per the Questioning rule; then run the angle's analysis. Run the angle and present findings. Batch questions from related angles into a single round when findings are related — batching questions is permitted, skipping analysis is not. Ask questions about findings. Only skip asking when a finding is trivially obvious and carries no decision weight. For findings with major impact on users, emit a **SEVERE WARNING** and continue without asking. Apply Phase navigation rule to each angle: ask questions about findings proactively; loop on that angle's findings until no new questions surface before marking the angle complete. Do not resolve choice points unilaterally — apply the Questioning rule.
 
-**Scenario-to-test rule**: Across all angles — especially angles 3 (dry run), 10 (scenario runs), 12 (input coverage), and 13 (stress/failure) — continuously collect scenarios into the plan's Quality Verification Strategy as named test cases. Capture a scenario from each of the following categories whenever one is encountered during investigation:
+**Scenario-to-test rule**: Across all angles — especially angles 5 (scenario runs), 6 (input coverage), and 7 (stress/failure) — continuously collect scenarios into the plan's Quality Verification Strategy as named test cases. Capture a scenario from each of the following categories whenever one is encountered during investigation:
 
 | Category | When to add |
 |---|---|
@@ -186,11 +186,11 @@ Each angle is an analysis step. **For each angle:** formulate 5–10 challenge q
 | **Smoke** | Minimal "does it work at all" check for the primary function — derived from feasibility analysis (Phase 4e) |
 | **Integration** | Components connect and communicate correctly — derived from component consistency analysis (Phase 4c) |
 | **Policy / contract compliance** | Behaviour matches a declared policy, interface contract, or external API shape — derived from XDRS alignment (Phase 4d) and unverified claims (Phase 4i) |
-| **Assumption** | A planning assumption that must hold true at runtime — derived from pre-mortem analysis (angle 5) and unverified references |
-| **Security** | No sensitive data exposed, no attack surface created, no OWASP violation — derived from security scan (angle 6) |
-| **Side-effect / isolation** | Executing this feature leaves adjacent systems, files, and state unaffected — derived from second-order effects analysis (angle 8) |
-| **Observability** | Failures and error states are detectable, logged, and produce actionable messages — derived from observability analysis (angle 17) |
-| **Acceptance** | The originally requested feature or outcome is demonstrably delivered end-to-end — derived from faithfulness (angle 1), goal achievability (angle 3), and success criteria (angle 7) |
+| **Assumption** | A planning assumption that must hold true at runtime — derived from pre-mortem analysis (angle 3) and unverified references |
+| **Security** | No sensitive data exposed, no attack surface created, no OWASP violation — derived from security scan (angle 3) |
+| **Side-effect / isolation** | Executing this feature leaves adjacent systems, files, and state unaffected — derived from second-order effects analysis (angle 4) |
+| **Observability** | Failures and error states are detectable, logged, and produce actionable messages — derived from observability analysis (angle 9) |
+| **Acceptance** | The originally requested feature or outcome is demonstrably delivered end-to-end — derived from faithfulness (angle 1), goal achievability (angle 2), and success criteria (angle 4) |
 
 Name each test case as `<descriptive action or scenario> (<category>)` so the purpose is immediately readable after implementation without needing to look up the planning notes. The descriptive part should name the concrete scenario; the category in parentheses identifies why it was captured. Examples: `"Validate BOM-prefixed file (edge case)"`, `"glob pattern [invalid throws (adversarial/invalid)"`, `"10 000 files processed synchronously (stress)"`, `"CLI exits 0 when all files valid (acceptance)"`, `"readFileSync EACCES returns invalid result (integration)"`. Optionally append the source angle in brackets for full traceability: `"BOM-prefixed file (edge case) [12-22]"`. Show a sample of the most revealing scenarios as brief inline callouts during the analysis to make the depth of analysis visible without producing a wall of text.
 
@@ -199,16 +199,16 @@ Name each test case as `<descriptive action or scenario> (<category>)` so the pu
 **1. Prompt faithfulness**
 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**
+**2. Goal achievability**
 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**
+**3. Pre-mortem**
 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. Ask the human about any non-trivial findings. For trivially obvious mitigations with no decision weight, state them and continue.
 
-**7. Success criteria and falsifiability**
+**4. Success criteria and falsifiability**
 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 the side effects are acceptable.
 
-**9. Steelman the opposition**
+**5. Steelman the opposition**
 Simulate 10 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 two adversarial or failure cases.
 
 Examples of scenario framing:
@@ -218,21 +218,21 @@ Examples of scenario framing:
 
 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**
+**6. Output internal consistency**
 Simulate 50–200 different inputs against the produced element with the goal of discovering edge cases, security issues, and unresolved discussion points not yet surfaced in earlier phases. Scale toward 200 when the feature has high input diversity (many argument types, branches, modes, or configuration axes) — use the lower end only for narrow, single-path features. These inputs are a breadth-forcing tool — not a pass/fail test. What counts as an "input" depends on the task type: for code/systems — function arguments, API payloads, config values; for documents/policies/processes — reader queries, usage scenarios, edge-case interpretations. Inputs must span typical, edge, boundary, invalid, adversarial, and combined cases. Add more inputs for each distinct branch or configuration axis the plan introduces — the more divergent paths exist in the logic, the more inputs are needed to cover them. For each, ask: does this reveal a new edge case, security risk, or ambiguity not already addressed? Surface all findings as questions to the human per the Questioning rule.
 
-**13. Stress and failure conditions**
+**7. Stress and failure conditions**
 Enumerate 2–3 meaningfully different ways the goal could be achieved. For each alternative, describe the approach in 1–2 lines and compare it against the current plan on at least: implementation effort, reversibility, risk, and fit with existing context. The goal is to surface whether the current plan is the right approach or just the first one considered. Ask the human: which tradeoffs matter most, and does the current approach still win? If an alternative is clearly superior in the context, flag it prominently and ask the human to reconsider.
 
-**15. Stakeholder perspective tour**
+**8. Stakeholder perspective tour**
 Review the plan for anything that could be cut, simplified, or deferred without losing essential value. For each candidate: what is it, why might it be unnecessary, and what is the risk of removing it? This is not the same as scope-creep detection (angle 1, which checks for additions) — this angle actively proposes reductions. Ask the human to confirm or reject each simplification candidate explicitly.
 
-**17. Observability and failure recovery**
+**9. Observability and failure recovery**
 Ask: will someone who did not build this be able to understand, change, and extend it safely 6 months from now? For code: are responsibilities clearly separated, is there excessive coupling, are there undocumented assumptions baked into the implementation, are naming and structure consistent with the codebase conventions? For documents and policies: is the content organized so that a future editor can update one section without inadvertently invalidating another? Is the vocabulary stable and defined, or does it rely on context that may not survive contributor turnover? For processes: are the steps atomic and independently verifiable, or do they depend on unstated tribal knowledge? Identify the parts of the plan most likely to become a maintenance burden and ask the human whether the trade-off is acceptable.
 
-After all 18 angles are complete, use `vscode_askQuestions` (per Phase gate UI rule) to present the Phase 6 gate with at least these options:
+After all 9 angles are complete, use `vscode_askQuestions` (per Phase gate UI rule) to present the Phase 6 gate with at least these options:
 - **"Continue to Phase 7 — Pre-Execution Readiness"** (recommended when all angles are complete and no open questions remain) — advance.
-- **"Re-run Phase 6 — deeper pass"** — repeat all 18 angles with fresh challenge questions, prioritising scenarios and inputs not yet explored, then re-present this gate.
+- **"Re-run Phase 6: 9 Challenge Angles — deeper pass"** — repeat all 9 angles with fresh challenge questions, prioritising scenarios and inputs not yet explored, then re-present this gate.
 - **"Add a comment or correction"** (open box) — re-run Phase 6 in full, treating the comment as additional context and constraints, then re-present this gate.
 
 ### Phase 7: Pre-Execution Readiness
@@ -240,12 +240,13 @@ After all 18 angles are complete, use `vscode_askQuestions` (per Phase gate UI r
 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.
 
 - [ ] Consistency rounds converged (convergence signals met — last 2 rounds produced only single-sentence answers with no new issues) (per Phase navigation rule)
-- [ ] All 18 challenge angles completed with human input received for every ambiguity and subjective decision
+- [ ] All 9 challenge angles completed with human input received for every ambiguity and subjective decision
 - [ ] Diagram generated and confirmed by the human
 - [ ] 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
 - [ ] Quality Verification Strategy defined in the plan with exact executable steps for all applicable check types (code: unit tests, integration tests, linting, static analysis; documents/analyses: fact-checking, link and citation validation, peer review, etc.)
+- [ ] A dedicated test generation and execution phase is present in the ordered plan steps (or explicitly marked N/A with a reason)
 - [ ] Verification checks executed during dry run and results reviewed — failures and coverage gaps resolved
 - [ ] All high-risk unverified references (code or factual) listed in the Unverified References section with explicit first-step verification in the execution plan
 - [ ] All scenarios from any phase or angle that revealed gaps, raised model doubt, or qualified for any category in the Scenario-to-test table have been added as named test cases to the plan's Quality Verification Strategy
@@ -311,12 +312,12 @@ Stop execution and return to Phase 1 if any of the following occur:
 - Phase 3: Discovers existing middleware and an in-progress PR touching the same path. Human asked about each before drafting.
 - Phase 4: 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 5: Sequence diagram generated. Human confirms it matches their model.
-- Phase 6: 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: Angle 4 (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 5 (steelman) surfaces that Redis dependency adds operational complexity; human accepts the trade-off.
 - Phase 7: All items checked. Execution approved.
 
 **Input**: "Write operator documentation for the conveyor belt system."
 
-- Phase 6, 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.
+- Phase 6, angle 5 (steelman): 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.
 
 **Input**: "Add input validation to the user registration endpoint."
 

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

@@ -7,12 +7,12 @@ description: >
   complete, and ready for implementation.
 metadata:
   author: flaviostutz
-  version: "2.0"
+  version: "4.0"
 ---
 
 ## Overview
 
-Turns a vague request or rough draft into an implementation-ready user story by running a structured 7-phase refinement process: understanding the request, qualifying requirements with a scope size check, researching existing context and drafting a story skeleton, checking consistency and scope completeness, validating visually with a user journey diagram, challenging from 9 user-perspective angles, and producing a final ready-to-implement story with a readiness checklist.
+Turns a vague request or rough draft into an implementation-ready user story by running a structured 9-phase refinement process: establishing plan 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).
 
 Activate when:
 - The request is vague, incomplete, or internally inconsistent.
@@ -37,13 +37,15 @@ Activate when:
 - **Loop**: within each phase, loop asking questions until convergence or Skip. Convergence means the last 2 consecutive rounds produced only single-sentence answers with no new issues surfaced — do not stop on a round count alone; stop only when checks genuinely have nothing left to surface. Explicit human confirmation that the phase output is correct also counts as convergence.
 - **Checklist gate**: after convergence, verify any completion checklist — if items are unmet, ask those specifically (targeted questions, not a full loop restart) before advancing.
 - **Skip**: when the human invokes Skip, stop the loop, record all open items as named Deferred Risks (visible in the story, carried forward), suspend the hard gate for those items, and advance immediately.
-- **Backtracking**: when any finding touches goals, scope, requirements, or assumptions from an earlier phase, explain to the human which phase is affected and why, and re-run that phase's loop focused on the new information; backtracking overrides any prior skip; Phase 1 concerns re-route to Phase 2 Step 1.
+- **Backtracking**: when any finding touches goals, scope, requirements, or assumptions from an earlier phase, explain to the human which phase is affected and why, and re-run that phase's loop focused on the new information; backtracking overrides any prior skip; concerns about the initial request understanding re-route to Phase 2 Step 1 (Classify and restate).
 
 **Phase gate UI rule**: At every point where the skill requires human confirmation before advancing to the next phase — any instruction that says "Wait for the answer before continuing" or requires the human to confirm convergence — use `vscode_askQuestions` to present the gate. Always include a clearly labeled recommended option such as "Continue to Phase N — [phase name]" and allow free text so the human can provide corrections, ask follow-up questions, or redirect instead. Do not present a text prompt alone and wait for freeform input — the human must always have a visible, labeled UI option to advance.
 
+**Context Probe rule**: In every phase, whenever you encounter a gap, uncertainty, or ambiguity that external documentation, specifications, URLs, screenshots, or other artifacts could resolve — ask the user proactively. Tie the ask to the specific gap identified (e.g. *"I need to understand how the current deletion confirmation works — do you have a design spec or screenshot?"*). Never ask generically ("do you have any docs?"). The user can always skip; skipped probes are recorded as "Context: not provided for [topic]" and do **not** count as unresolved decisions under the Hard Gate. Do not re-probe gaps already covered by the Context Summary from Phase 1.
+
 ---
 
-### Phase 0: Plan Document Context
+### Phase 1: Plan Document Context & Context Enrichment
 
 Before beginning refinement, determine the working context and where output will be saved.
 
@@ -62,9 +64,9 @@ Scan the workspace for a `.xdrs/` directory. Proceed to Step 2a, 2b, or 2c based
 2. For each linked file, read it and check for `**Status:** to-be-refined`. Collect only those as pending stories.
 3. Use `vscode_askQuestions` to list all pending stories (by their link text and file name) plus a "New story — I will describe it" option.
 4. If the user picks a pending story:
-   - Read the placeholder file. Extract the NNN and slug from its `**Story ID:**` line. Carry any notes, context, or related-story links from the placeholder into Phase 1 as starting context.
-   - Use the placeholder's title and notes as the subject for Phase 1.
-5. If the user picks "New story", ask which Milestone to place it in; offer to add the Milestone if it does not exist. The slug and NNN for the new story are assigned in Phase 7.
+   - Read the placeholder file. Extract the NNN and slug from its `**Story ID:**` line. Carry any notes, context, or related-story links from the placeholder into Phase 1 Step 3 (Context Enrichment) as starting context.
+   - Use the placeholder's title and notes as the subject for Phase 2.
+5. If the user picks "New story", ask which Milestone to place it in; offer to add the Milestone if it does not exist. The slug and NNN for the new story are assigned in Phase 8.
 
 **Step 2b — XDRS scope found but no plan document provided:**
 1. Search for files matching `*/bdrs/operations/plans/*-epic-*.md`.
@@ -97,21 +99,54 @@ Scan the workspace for a `.xdrs/` directory. Proceed to Step 2a, 2b, or 2c based
      **Key tasks:**
      ```
    - Proceed as Step 2a (the new plan is now the active plan context, Milestone 1 is the target).
-5. If "start fresh" is chosen, continue to Phase 1 with no active plan context; Phase 7 will handle deferred stories.
+5. If "start fresh" is chosen, continue to Phase 1 Step 3 (Context Enrichment) with no active plan context; Phase 8 will handle deferred stories.
 
 **Step 2c — No XDRS scope found:**
-Skip Phase 0. Proceed directly to Phase 1. Phase 7 will ask where to save output.
+Skip Phase 1 Steps 1–2. Proceed directly to Phase 1 Step 3 (Context Enrichment). Phase 8 will ask where to save output.
+
+**Step 3 — Context Enrichment**
+
+Before beginning analysis, gather factual context about the system, process, or domain the story touches. This step runs for all Phase 1 paths (2a, 2b, 2c).
+
+1. **Quick request analysis** *(internal — not surfaced verbatim to the user)*: read the story request and perform a rapid 3–5 bullet read to identify: domain/system type (CRM, e-commerce, auth, internal tool, etc.); key entities mentioned (contacts, leads, orders, users…); type of operation (CRUD, integration, notification, UI change…); any named systems, teams, or technologies. Used solely to generate targeted questions; NOT the full Phase 2 analysis.
+
+2. **Auto-discovery**: scan the workspace for signals — source code folders, documentation files (`.md`, `.pdf`, `.txt`), XDRS decisions, prior user stories (`.assets/userstory-*.md`), README files, API specs, test files, diagrams. Summarize findings in 3–5 bullet points (do not dump raw content). Include any notes or context carried forward from Step 2a/2b placeholder files.
+
+3. **Generate targeted context questions** derived from the quick analysis and auto-discovery. Questions must be specific — derived from what the request implies, not generic boilerplate:
+   - **Domain-specific probes** (examples: *"This looks like a CRM — is it? Can you point me to the Leads screen documentation or any existing specs?"* / *"Do you have screenshots, mockups, or a recording of the current flow?"* / *"Is there an existing implementation to reference? If so, point me to the relevant folder or file."*)
+   - **Business intent / artifact probes** (examples: *"What business outcome is expected from this change? Are there OKR or KR documents that describe the goal?"* / *"Were there any user interviews or stakeholder discussions about this need? A transcript or notes would help."*)
+   - ≤5 questions per `vscode_askQuestions` call; freeform answers preferred; use `options` only for bounded choices.
+
+4. After answers, auto-read any provided files/URLs and summarize them (factual only, each item labeled with its source). If the answers surface new questions that external info could address, generate a new targeted round and loop. Apply the Phase navigation rule (convergence = last 2 consecutive rounds produced no new actionable information).
 
-**Plan context record:** note the active plan file path (or none) and the target Milestone name; carry these into Phase 7.
+5. Present the convergence gate via `vscode_askQuestions`:
+   - **"Context is sufficient — continue to Phase 2"** *(recommended when meaningful context has been gathered)*
+   - **"Add more context"** (free text) — record and loop back to step 4
+   - **"Skip — no additional context available"** — record `Context: none available` and proceed
+
+6. Compile the **Context Summary**: a labeled bullet list of all gathered information, each item attributed to its source (e.g. `**Source:** workspace/README.md — describes the existing Contact entity model`). Carry this summary into all subsequent phases.
+
+**Hard constraint**: never invent or synthesize context from the story description alone. If nothing was found and the user skips, record `Context: none available.`
+
+---
+
+**Plan context record:** note the active plan file path (or none), the target Milestone name, and the Context Summary from Step 3; carry these into Phase 8.
 
 ---
 
-### Phase 1: Understand the Request
+### Phase 2: Request Analysis & Requirements Qualification
+
+#### Step 1 — Classify and restate
 
 1. Announce that you are activating the refine-user-story skill. State the story goal in one sentence: what the user wants to accomplish and what value it should deliver.
 2. **Classify the input.** Decide whether the input is a vague request, partial draft, or near-complete story. State the classification explicitly.
-3. **Restate current understanding** in 2–3 lines before asking any questions.
-4. **Identify missing information.** Scan across 6 areas:
+3. **Restate current understanding** in 2–3 lines, drawing on the Context Summary from Phase 1 when present.
+
+#### 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.
+
+**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.
 
 | Area | Questions to resolve |
 |---|---|
@@ -120,30 +155,13 @@ Skip Phase 0. Proceed directly to Phase 1. Phase 7 will ask where to save output
 | Requirements | What must the system do? What inputs, outputs, or contracts matter? What constraints shape the solution? |
 | Flow and interactions | What is the main end-to-end flow? Which actors, systems, or interfaces are involved? Are there state transitions or lifecycle rules? |
 | 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? |
-
-Use `vscode_askQuestions` to ask at most 4–5 tightly related questions from the initial scan. Apply the Phase navigation rule.
-
-Then use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
-- **"Continue to Phase 2 — Requirements Qualification"** (recommended when initial understanding is sufficient)
-- **"Re-run Phase 1 — deeper pass"** — revisit classification and 6-area scan with fresh eyes, then re-present this gate.
-- **"Add a comment or correction"** (open box) — re-run Phase 1 treating the comment as additional context, then re-present this gate.
+| 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.) |
 
----
-
-### Phase 2: Requirements Qualification
-
-#### Step 1 — Ask follow-up questions
+**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.
 
-Loop asking questions across the 6 areas from Phase 1. After each answer, evaluate whether new ambiguities surfaced before continuing. Apply the Phase navigation rule.
+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.
 
-- **Always use `vscode_askQuestions`** when available. Never dump questions as plain text.
-- Ask at most 4–5 tightly related questions per call. Do not batch many unrelated questions together.
-- Use `options` whenever the answer space is bounded. Use free-form text only when truly open-ended.
-- **Do not proceed to Step 2 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.
-- **Interface and integration scan**: before closing Step 1, 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. Ask targeted questions for any missing details.
-
-#### Step 2 — Scope size evaluation
+#### Step 3 — Scope size evaluation
 
 Assess whether the request as currently scoped is suitable for a single focused story. A request is likely too large if two or more of the following are true (a single criterion alone is not sufficient):
 - More than approximately 10 distinct scope items resulted from questioning.
@@ -152,30 +170,30 @@ Assess whether the request as currently scoped is suitable for a single focused
 - Multiple distinct actor groups experiencing the feature in non-overlapping ways.
 
 If too large, propose a split into 2–4 vertical slices where each slice delivers independent end-to-end releasable value. Present the proposed split with a brief rationale for each slice's boundary. Use `vscode_askQuestions` with:
-- **"Accept split — start refining [Slice 1 name]"** (recommended) — restart from Phase 1 with the narrower scope; record all deferred slices in a **Deferred Stories** list so they can be tracked for future runs.
+- **"Accept split — start refining [Slice 1 name]"** (recommended) — restart from Phase 2 with the narrower scope; record all deferred slices in a **Deferred Stories** list so they can be tracked for future runs.
 - **"Keep original scope — continue"** — proceed without splitting; note the human explicitly accepted the larger scope.
 - Free text to adjust the proposed slice boundaries before deciding.
 
-If the human accepts the split, restart the entire process from Phase 1 with the new narrower scope.
+If the human accepts the split, restart the entire process from Phase 2 with the new narrower scope.
 
-#### Step 3 — Feature summary and phase gate
+#### Step 4 — Feature summary and phase gate
 
 Present a brief feature summary — a short bullet list of what will be built or changed, written in plain language the requester can validate at a glance.
 
 Then use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
 - **"Continue to Phase 3 — Context & Story Draft"** (recommended when requirements are clear and agreed)
-- **"Re-run Phase 2 — deeper pass"** — repeat all steps with fresh eyes, prioritising areas not yet fully explored, then re-present this gate.
+- **"Re-run Phase 2: Request Analysis & Requirements — deeper pass"** — repeat all steps with fresh eyes, prioritising areas not yet fully explored, then re-present this gate.
 - **"Add a comment or correction"** (open box) — re-run Phase 2 in full treating the comment as additional context, then re-present this gate.
 
 ---
 
 ### Phase 3: Context & Story Draft
 
-1. **Research existing context**: inspect relevant workspace files, existing user stories or tickets, prior decisions, established conventions, and analogous patterns already in place. Ask questions about any non-trivial context items found. Apply the Phase navigation rule.
+1. **Build on the Context Summary** from Phase 1 Step 3. Do not re-scan the workspace for what is already captured there; instead focus on story-specific patterns, prior decisions, analogous implementations, and established conventions not yet covered in the Context Summary. Apply the Context Probe rule: if this deeper pass surfaces a partial or missing artifact (a referenced doc that was not provided, a prior story that links to an external spec), ask for it specifically. Apply the Phase navigation rule.
 2. **Draft a story skeleton** — a rough but structured version of the output template — incorporating context found. The skeleton must include at minimum: Title, User Story, Scope, and Acceptance Criteria as first drafts (not final).
 3. Present the draft skeleton and use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
    - **"Continue to Phase 4 — Consistency & Scope Review"** (recommended when the draft matches intent)
-   - **"Re-run Phase 3 — explore deeper"** — repeat the research pass looking for context, decisions, or constraints not yet surfaced, then re-present this gate.
+   - **"Re-run Phase 3: Context & Story Draft — explore deeper"** — repeat the research pass looking for context, decisions, or constraints not yet surfaced, then re-present this gate.
    - **"Add a comment or correction"** (open box) — re-run Phase 3 treating the comment as additional context, then re-present this gate.
 4. If the draft reveals gaps or contradictions, return to Phase 2 before continuing.
 
@@ -194,21 +212,21 @@ Ask questions about all findings. Apply the Phase navigation rule.
 
 #### Step 2 — Scope item review
 
-For every item listed under **Scope**, loop through these four checks before moving on:
+For every item listed under **Scope**, loop through these five checks before moving on:
 
 | Check | What to look for |
 |---|---|
 | Completeness | Is the item fully described? Are inputs, outputs, triggers, and expected behavior clear enough for autonomous implementation without guessing? |
 | Edge cases | Does this item have unusual paths — errors, empty states, boundary values, retries, or concurrency — not yet captured? Add any found. |
 | Technical constraints | Does this item imply or conflict with an existing technical constraint (e.g. API contract, data model, performance budget, auth model)? Flag any that must be honored. |
-| Missing attachments | Would a screenshot, mockup, flow diagram, or reference document make this item unambiguous? If so, ask for it explicitly before proceeding. |
+| Missing attachments | Would a screenshot, mockup, flow diagram, or reference document make this item unambiguous? If so, apply the Context Probe rule and ask for it explicitly before proceeding. |
 | Detailed Specs | Did refinement surface any external APIs, data contracts, documentation links, or contact names relevant to this item? If yes, are they fully recorded? If anything is missing, ask targeted questions. If none apply, note it explicitly so the N/A can be recorded in the output. |
 
 Do **not** advance while any scope item fails a check. If a check reveals a new gap, return to Phase 2 and ask the follow-up question.
 
 After all checks converge, use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
 - **"Continue to Phase 5 — Visual Validation"** (recommended when all items pass all checks)
-- **"Re-run Phase 4 — deeper pass"** — repeat all consistency and scope checks with fresh eyes, then re-present this gate.
+- **"Re-run Phase 4: Consistency & Scope Review — deeper pass"** — repeat all consistency and scope checks with fresh eyes, then re-present this gate.
 - **"Add a comment or correction"** (open box) — re-run Phase 4 treating the comment as additional context, then re-present this gate.
 
 ---
@@ -225,16 +243,24 @@ After all checks converge, use `vscode_askQuestions` (per Phase gate UI rule) wi
 
 3. Use `vscode_askQuestions` (per Phase gate UI rule) to ask: "Does this diagram match your mental model of the user journey?" Present at least these options:
    - **"Continue to Phase 6 — User-Perspective Challenge"** (recommended when the diagram matches)
-   - **"Re-run Phase 5 — try a different diagram type"** — choose a different type or regenerate with a different framing, then re-present this gate.
+   - **"Re-run Phase 5: Visual Validation — try a different diagram type"** — choose a different type or regenerate with a different framing, then re-present this gate.
    - **"Add a comment or correction"** (open box) — re-run Phase 5 treating the comment as additional context, then re-present this gate.
 
 4. If the diagram reveals gaps or inconsistencies not yet surfaced, return to Phase 4 before continuing.
+5. **Save the confirmed diagram.** Write the Mermaid source to `.assets/userstory-NNN-slug-journey.md` inside the plan's `.assets/` folder (when a plan doc is active) or to `userstory-journey.md` at the workspace root otherwise. Record this path to include as a diagram attachment in `## Attachments` when Phase 8 writes the story file.
 
 ---
 
 ### Phase 6: User-Perspective Challenge
 
-Each angle is an analysis step. Run the angle and present findings. Ask questions about all findings per the Phase navigation rule. Only skip asking when a finding is trivially obvious and carries no decision weight. Loop on each angle until no new questions surface before marking it complete. Do not resolve choice points unilaterally.
+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, interview transcript, design doc, 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.
 
 **1. User journey completeness**
 Does the story cover the full user journey from trigger to completion, including what happens immediately after? Identify any step the user must take that is not covered by the story.
@@ -264,13 +290,55 @@ Are there data privacy, error recovery, or safety implications from the user's p
 Can a new user complete this story's scenario without reading documentation? What is the first-use experience? Are there onboarding moments, tooltips, or self-describing UI elements needed?
 
 After all 9 angles converge, use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
-- **"Continue to Phase 7 — Story Output & Readiness"** (recommended when all angles have converged and no open questions remain)
-- **"Re-run Phase 6 — deeper pass"** — repeat all angles with fresh challenge questions, prioritising angles not yet fully explored, then re-present this gate.
+- **"Continue to Phase 7 — Implementer-Perspective Challenge"** (recommended when all angles have converged and no open questions remain)
+- **"Re-run Phase 6: User-Perspective Challenge — deeper pass"** — repeat all angles with fresh challenge questions, prioritising angles not yet fully explored, then re-present this gate.
 - **"Add a comment or correction"** (open box) — re-run Phase 6 treating the comment as additional context, then re-present this gate.
 
 ---
 
-### Phase 7: Story Output & Readiness
+### 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.
+
+**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?
+
+**2. Error and edge paths**
+Are all failure modes, invalid inputs, retries, empty states, and boundary values explicitly handled? Does the story cover what happens when things go wrong — not only the happy path? Are error responses and recovery flows described?
+
+**3. Blocking dependencies & startability**
+Is any external team decision, environment access, infrastructure change, or third-party system onboarding required before work can start? Is it clear when this story can be picked up — are there ordering constraints relative to other stories, milestones, or external events? All blocking items must be either resolved or explicitly deferred as named risks with the expected resolution date or condition.
+
+**4. Functional dependencies**
+What external APIs, systems, services, or teams does this story depend on to function — not necessarily blocking start, but required for the feature to work? For each: is the integration contract (endpoints, auth, data format, SLAs, contact) documented? Are there known risks, rate limits, reliability concerns, or ownership questions that the implementer needs to know?
+
+**5. Non-functional requirements**
+Are performance, scalability, availability, and accessibility expectations stated? If none apply, is that explicitly noted? (Mark N/A if not applicable.) Any measurable NFR discovered here (e.g. "response time < 2s", "supports 50 concurrent users") MUST also appear as a verifiable item in `## Acceptance Criteria` — recording it only in `## Constraints` is not sufficient.
+
+**6. Security implications**
+Are authentication model, authorization rules, sensitive data handling, and input validation concerns identified and addressed? Are any known threat vectors or compliance constraints noted? (Mark N/A if not applicable.)
+
+**7. Independent releasability**
+Can this story be deployed to production without requiring another story to be completed first? If a hard coupling exists, is it explicitly stated and justified?
+
+**8. Implementer dry run**
+Simulate an engineer receiving this story cold — no prior context, no verbal briefing. Walk through their experience step by step: reading the title and user story, scanning the scope, reading the acceptance criteria, checking the detailed specs, looking at external system references, identifying where to start. At each step ask: would they get stuck? Would they need to ask a question? Would they make a wrong assumption? Flag every point where the story is insufficient to let them start and make progress without outside help. This is the final integration check: if any of angles 1–7 left gaps, they will surface here.
+
+After all 8 angles converge, use `vscode_askQuestions` (per Phase gate UI rule) with at least these options:
+- **"Continue to Phase 8 — Story Output & Readiness"** (recommended when all angles have converged and no open questions remain)
+- **"Re-run Phase 7: Implementer-Perspective Challenge — deeper pass"** — repeat all angles with fresh challenge questions, prioritising angles not yet fully explored, then re-present this gate.
+- **"Add a comment or correction"** (open box) — re-run Phase 7 treating the comment as additional context, then re-present this gate.
+
+---
+
+### Phase 8: Story Output & Readiness
 
 Before producing the final story, verify ALL items in the checklist below. If any item cannot be checked, return to the relevant phase and resolve it first.
 
@@ -280,7 +348,7 @@ Before producing the final story, verify ALL items in the checklist below. If an
 - [ ] Every in-scope item passes the 5-check review (completeness, edge cases, technical constraints, attachments, detailed specs) with no open findings.
 - [ ] No contradictions between goal, scope, and acceptance criteria.
 - [ ] Story is either one thin vertical slice or a clean set of split slices, each delivering complete releasable value.
-- [ ] All 9 user-perspective challenge angles completed with human input received for every ambiguity and subjective decision.
+- [ ] All 9 user-perspective challenge angles (Phase 6) and all 8 implementer-perspective angles (Phase 7) completed with human input received for every ambiguity and subjective decision.
 - [ ] Diagram generated and confirmed by the human.
 - [ ] No unresolved human questions outstanding.
 - [ ] For every in-scope item where integration or interface details exist: `## Detailed Specs` is populated or explicitly marked N/A; the story contains enough detail to begin architecture or implementation without further business clarification.
@@ -290,9 +358,9 @@ Once all items are checked or explicitly marked N/A, **produce the final result*
 - If the work is too large, output only the split stories using the same template.
 - Acceptance criteria must be a plain checklist.
 
-If any stories or features were placed in the **Deferred Stories** list during Phase 2 Step 2 (scope split), or any items were recorded as named **Deferred Risks** during a Skip, present a **Deferred Items summary** — a bulleted list of each deferred item with a one-line description of what it covers and why it was deferred.
+If any stories or features were placed in the **Deferred Stories** list during Phase 2 Step 3 (scope split), or any items were recorded as named **Deferred Risks** during a Skip, present a **Deferred Items summary** — a bulleted list of each deferred item with a one-line description of what it covers and why it was deferred.
 
-**When an XDRS plan doc is active** (Phase 0 selected or created a plan): skip this prompt entirely. Deferred slices are handled as placeholder files with task links in the plan doc by the Plan document integration section below.
+**When an XDRS plan doc is active** (Phase 1 selected or created a plan): skip this prompt entirely. Deferred slices are handled as placeholder files with task links in the plan doc by the Plan document integration section below.
 
 **When no XDRS plan doc is active**: use `vscode_askQuestions` with:
 - **"Save to BACKLOG.md"** (recommended) — append the list under a `## Deferred Stories` heading in `BACKLOG.md` at the workspace root (create the file if it does not exist), so the items can be planned for future refinement runs.
@@ -303,12 +371,12 @@ This step is skipped if no stories were deferred and no Deferred Risks were reco
 
 ### Plan document integration
 
-After producing the final story output, persist it according to the active plan context from Phase 0.
+After producing the final story output, persist it according to the active plan context from Phase 1.
 
-**When an XDRS plan doc is active (Phase 0 selected or created a plan):**
+**When an XDRS plan doc is active (Phase 1 selected or created a plan):**
 1. Determine the NNN and slug for the story detail file:
-   - **Placeholder story** (Phase 0 picked a pending story): extract the NNN and slug from the placeholder file's `**Story ID:**` line. Reuse them for the refined file.
-   - **New story** (Phase 0 chose "New story" or a new epic was created): use the next available NNN in the plan's `.assets/` folder (list existing `userstory-NNN-*.md` files, increment the highest; start at 001 if empty). Derive the slug by kebab-casing the refined `## Title`, keeping at most 7 words, e.g. `save-payment-method-future-checkouts`.
+   - **Placeholder story** (Phase 1 picked a pending story): extract the NNN and slug from the placeholder file's `**Story ID:**` line. Reuse them for the refined file.
+   - **New story** (Phase 1 chose "New story" or a new epic was created): use the next available NNN in the plan's `.assets/` folder (list existing `userstory-NNN-*.md` files, increment the highest; start at 001 if empty). Derive the slug by kebab-casing the refined `## Title`, keeping at most 7 words, e.g. `save-payment-method-future-checkouts`.
 2. Write the refined story as `.assets/userstory-NNN-slug.md` inside the plan's `.assets/` folder using the output template, including the `**Story ID:** userstory-NNN-slug` line at the top (no `**Status:**` line — absence of the status field indicates a refined story).
 3. In the plan doc, update the task entry link text in the active Milestone: change `[Brief description — pending]` to `[Refined Story Title]` (keep the same `.assets/userstory-NNN-slug.md` path). For new stories, insert a new task entry `- [Refined Story Title]{.assets/userstory-NNN-slug.md}`.
 4. When splitting: for each non-chosen slice, create a placeholder file at `.assets/userstory-NNN-slug.md` containing:
@@ -368,10 +436,51 @@ As a [role], I want to [action], so that [benefit].
 ## Attachments
 [highly desirable — screenshots, mockups, or diagrams illustrating the feature.]
 - [attachment]
+
+**Epic plan:** [NNN-epic-slug.md](../NNN-epic-slug.md)
+*(omit when no XDRS plan doc is active)*
 ```
 
 ---
 
+### Phase 9: Final Readiness & Size Re-Validation
+
+Run two sequential checks. For any item in Check A not met in the final output, ask targeted questions and update the story before moving to Check B.
+
+#### Check A — Readiness double-check
+
+Verify all 14 items against the final story output:
+
+**Story-level (6 items):**
+1. **Vertical completeness** — story covers everything needed for end-to-end implementation; no half-slices that silently assume separate parallel work.
+2. **Size** — one person can develop it in roughly 2–3 days.
+3. **Engineering-ready detail** — sufficient for architecture and engineering detailing without further business clarification.
+4. **External systems** — all external systems documented with APIs, endpoints, data fields, formats, constraints, and known concerns.
+5. **User context** — user perspective present: what the user will do with this feature in their context, including concrete usage examples.
+6. **Scope boundary** — explicit statement of what is included and what is not included in this implementation.
+
+**Implementer double-check (mirrors Phase 7 angles 1–8):**
+7. **Verifiable acceptance criteria** — every criterion independently testable; "done" is unambiguous.
+8. **Error and edge paths** — failure modes, invalid inputs, empty states, and boundary values explicitly handled beyond the happy path.
+9. **Blocking dependencies & startability** — all blocking items resolved or deferred; ordering constraints and startability conditions are explicit.
+10. **Functional dependencies** — all external APIs, systems, services, and teams documented with integration contracts; known risks and reliability concerns noted.
+11. **Non-functional requirements** — performance, availability, and accessibility expectations stated or explicitly N/A.
+12. **Security implications** — auth model, data handling, and input validation addressed or explicitly N/A.
+13. **Independent releasability** — can ship without waiting for another story; any hard coupling explicitly stated.
+14. **Implementer dry run passed** — a cold engineer can read the story, understand where to start, and make progress without getting stuck or making wrong assumptions.
+15. **Definition of Done** — ask whether the team has a DoD; if so, confirm that its implicit criteria (e.g. code reviewed, tests passing, deployed to staging) are either satisfied by the story's scope or explicitly noted as out of scope.
+
+#### Check B — Size re-evaluation
+
+Apply the same 4 criteria from Phase 2 Step 3. If two or more are met, the story is still too large.
+
+- **Passes** → use `vscode_askQuestions` to confirm the skill is complete and the story is ready.
+- **Too large** → propose 2–4 vertical slices with rationale. Use `vscode_askQuestions` with:
+  - **"Accept split — start refining [Slice 1 name]"** (recommended) — restart from Phase 2 with the narrower scope; Phase 1 context is preserved; deferred slices follow Phase 2 Step 3 rules.
+  - Free text to adjust the proposed slice boundaries before deciding.
+
+---
+
 ## Examples
 
 **Input:** "Add a search bar to the product page."
@@ -393,4 +502,4 @@ As a [role], I want to [action], so that [benefit].
 
 - [`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 0)
+- [`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)