agentme 0.34.0 → 0.35.1

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.1"
 ---
 
 ## 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 initiative context and gathering external information to ground the analysis (Phase 1), analysing the request and qualifying requirements with a scope size check (Phase 2), researching existing context and drafting a story skeleton (Phase 3), checking consistency and scope completeness (Phase 4), validating visually with a user journey diagram (Phase 5), challenging from 9 user-perspective angles (Phase 6), challenging from 8 implementer-perspective angles (Phase 7), producing a final ready-to-implement story with a readiness checklist (Phase 8), and running a final readiness double-check (Phase 9).
 
 Activate when:
 - The request is vague, incomplete, or internally inconsistent.
@@ -37,45 +37,47 @@ 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: Initiative Document Context & Context Enrichment
 
 Before beginning refinement, determine the working context and where output will be saved.
 
 **Inline reference — Epic / Feature / User Story structure** (self-contained; no external policy file required to run this skill):
-- **Epic** — A plan document at `[scope]/bdrs/operations/plans/NNN-epic-slug.md`. Represents a group of features toward a well-defined objective (1–12 months). Heading: `# [scope]-bdr-plan-NNN: [Epic Title]`.
-- **Feature** — A `### Milestone N: [Feature Name]` section inside the epic plan. One Milestone per Feature. Duration: 2 weeks – 6 months.
+- **Epic** — An initiative document at `[scope]/bdrs/operations/initiatives/NNN-epic-slug.md`. Represents a group of features toward a well-defined objective (1–12 months). Heading: `# [scope]-bdr-initiative-NNN: [Epic Title]`.
+- **Feature** — A `### Milestone N: [Feature Name]` section inside the epic initiative. One Milestone per Feature. Duration: 2 weeks – 6 months.
 - **User Story** — A key task inside a Milestone, always as a link: `- [Brief description]{.assets/userstory-NNN-slug.md}`. Pending stories append ` — pending` to the link text and have `**Status:** to-be-refined` in the file. Refined stories have the full title. Duration: < 2 weeks; stories exceeding this MUST be split.
-- **User story detail file** — `.assets/userstory-NNN-slug.md` inside the epic plan's `.assets/` folder. NNN restarts at 001 per epic. Filenames always lowercase.
+- **User story detail file** — `.assets/userstory-NNN-slug.md` inside the epic initiative's `.assets/` folder. NNN restarts at 001 per epic. Filenames always lowercase.
 
 **Step 1 — Detect XDRS scope**
 
 Scan the workspace for a `.xdrs/` directory. Proceed to Step 2a, 2b, or 2c based on what is found.
 
-**Step 2a — Plan document explicitly provided or referenced:**
+**Step 2a — Initiative document explicitly provided or referenced:**
 1. Parse all `### Milestone` sections (Features) and collect all task entries that link to `.assets/userstory-*.md` files.
 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.
-
-**Step 2b — XDRS scope found but no plan document provided:**
-1. Search for files matching `*/bdrs/operations/plans/*-epic-*.md`.
-2. Use `vscode_askQuestions` to ask the user to: pick an existing epic plan, create a new epic plan, or start fresh (no plan context).
-3. If an existing plan is picked, proceed as Step 2a.
-4. If **create a new epic plan** is chosen, run a guided Q&A using `vscode_askQuestions` to collect: Epic Title, one-sentence objective, Expected end date (YYYY-MM-DD), and name of the first Feature/Milestone. Then:
+   - 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 initiative document provided:**
+1. Search for files matching `*/bdrs/operations/initiatives/*-epic-*.md`.
+2. Use `vscode_askQuestions` to ask the user to: pick an existing epic initiative, create a new epic initiative, or start fresh (no initiative context).
+3. If an existing initiative is picked, proceed as Step 2a.
+4. If **create a new epic initiative** is chosen, run a guided Q&A using `vscode_askQuestions` to collect: Epic Title, one-sentence objective, Expected end date (YYYY-MM-DD), and name of the first Feature/Milestone. Then:
    - Derive the epic slug by kebab-casing the title, keeping at most 7 words.
-   - Determine the epic NNN by scanning `[scope]/bdrs/operations/plans/` for existing plan files and using the next available number (start at 001).
-   - Create the file at `.xdrs/[scope]/bdrs/operations/plans/NNN-epic-slug.md` with the required `_core-adr-policy-007` sections:
+   - Determine the epic NNN by scanning `[scope]/bdrs/operations/initiatives/` for existing initiative files and using the next available number (start at 001).
+   - Create the file at `.xdrs/[scope]/bdrs/operations/initiatives/NNN-epic-slug.md` with the required `_core-adr-policy-007` sections:
      ```markdown
-     # [scope]-bdr-plan-NNN: [Epic Title]
+     # [scope]-bdr-initiative-NNN: [Epic Title]
 
      ## Executive Summary
      [To be completed.]
@@ -96,22 +98,55 @@ 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.
+   - Proceed as Step 2a (the new initiative is now the active initiative context, Milestone 1 is the target).
+5. If "start fresh" is chosen, continue to Phase 1 Step 3 (Context Enrichment) with no active initiative 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.`
+
+---
+
+**Initiative context record:** note the active initiative 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.
+| 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.) |
 
-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.
-
----
+**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.
 
-### Phase 2: Requirements Qualification
+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.
 
-#### Step 1 — Ask follow-up questions
-
-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.
-
-- **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 initiative's `.assets/` folder (when an initiative 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,39 +358,41 @@ 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 initiative doc is active** (Phase 1 selected or created an initiative): skip this prompt entirely. Deferred slices are handled as placeholder files with task links in the initiative doc by the Initiative 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.
-- **"Save to a different file"** (open box) — human specifies the file path; append there instead.
+**When no XDRS initiative doc is active**: use `vscode_askQuestions` with:
+- **"Save to TODO.md"** (recommended) — append an entry under a `## Deferred Stories` heading in `TODO.md` at the workspace root (create the file if it does not exist), using the template below.
+- **"Save to a different file"** (open box) — human specifies the file path; append there instead using the same template.
 - **"Skip — do not save"** — proceed without saving.
 
 This step is skipped if no stories were deferred and no Deferred Risks were recorded.
 
-### Plan document integration
+**Deferred Stories template**: new `### Group: [title] — deferred [YYYY-MM-DD]` per split (1+ parts, never merged) with **Origin**, **Original objective**, **Split rationale**; one `#### [slice title]` per slice with **Objective**, **Scope**, **Context captured so far**, **Suggested prompt to resume**.
+
+### Initiative 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 initiative context from Phase 1.
 
-**When an XDRS plan doc is active (Phase 0 selected or created a plan):**
+**When an XDRS initiative doc is active (Phase 1 selected or created an initiative):**
 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`.
-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}`.
+   - **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 initiative'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 initiative'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 initiative 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:
    - `**Story ID:** userstory-NNN-slug`
    - `**Status:** to-be-refined`
    - A `## Title` with the preliminary description of the slice.
    - A `## Notes from intake` section with any relevant context captured in this session: split rationale, relationship to the current story, any API or business details already known.
    - A `## Related` section linking to the current story being refined.
-   Assign NNNs sequentially after the highest existing one in `.assets/` (the current story's file already written by step 2 counts as existing). Insert a task entry `- [Slice description — pending]{.assets/userstory-NNN-slug.md}` in the same Milestone (or a new Milestone if the split reveals a distinct Feature). Do NOT offer BACKLOG.md for deferred slices.
-5. Add a back-link to the epic plan at the bottom of the story detail file: `**Epic plan:** [NNN-epic-slug.md]{../NNN-epic-slug.md}` (the `../` resolves from `.assets/` up to `plans/`).
+   Assign NNNs sequentially after the highest existing one in `.assets/` (the current story's file already written by step 2 counts as existing). Insert a task entry `- [Slice description — pending]{.assets/userstory-NNN-slug.md}` in the same Milestone (or a new Milestone if the split reveals a distinct Feature). Do NOT offer TODO.md for deferred slices.
+5. Add a back-link to the epic initiative at the bottom of the story detail file: `**Epic initiative:** [NNN-epic-slug.md]{../NNN-epic-slug.md}` (the `../` resolves from `.assets/` up to `initiatives/`).
 
-**When no XDRS plan doc is active ("start fresh" or no XDRS scope):**
+**When no XDRS initiative doc is active ("start fresh" or no XDRS scope):**
 - Ask the user where to save the refined story (default: `userstory-NNN-slug.md` at workspace root).
-- If split/deferred stories exist, use `vscode_askQuestions` to ask whether to add them to an existing epic plan, create a new epic plan, or save to `BACKLOG.md`. Apply the chosen action.
+- If split/deferred stories exist, use `vscode_askQuestions` to ask whether to add them to an existing epic initiative, create a new epic initiative, or save to `TODO.md` per the template in Phase 8. Apply the chosen action.
 
 ### Output Template
 
@@ -368,10 +438,51 @@ As a [role], I want to [action], so that [benefit].
 ## Attachments
 [highly desirable — screenshots, mockups, or diagrams illustrating the feature.]
 - [attachment]
+
+**Epic initiative:** [NNN-epic-slug.md](../NNN-epic-slug.md)
+*(omit when no XDRS initiative 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 +504,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)