@exaudeus/workrail 3.15.0 → 3.17.0

package/workflows/documentation-update-workflow.json

@@ -3,6 +3,13 @@
   "name": "Documentation Update & Maintenance Workflow",
   "version": "2.0.0",
   "description": "Use this to update and maintain existing documentation. Uses git history to detect staleness, maps sections to current code, and refreshes outdated content while preserving what's still accurate.",
+  "about": "## Documentation Update & Maintenance Workflow\n\nUse this when you have **existing** documentation that may be out of date and needs to be refreshed to match the current state of the codebase. The workflow uses git history as its primary evidence source: it checks when the docs were last committed, what changed in the relevant code since then, and classifies staleness before touching anything.\n\n### What it produces\n\nUpdated documentation files with stale or inaccurate sections corrected, missing coverage added, and removed content pruned. A completion summary is written to notes for future maintainers, including maintenance recommendations and sections at risk of going stale again quickly.\n\n### When to use it\n\n- A feature shipped and the docs were never updated.\n- You suspect a doc is outdated but aren't sure which parts.\n- You want a systematic, section-by-section audit rather than a quick edit.\n- The repo has git history covering both code and docs (the workflow degrades gracefully without git, but git history is the primary evidence source).\n\n### When NOT to use it\n\n- You are writing a doc from scratch -- use the Document Creation workflow instead.\n- You only need to fix a single known typo or sentence -- just edit the file directly.\n\n### How to get good results\n\n- Point the workflow at the specific documentation files and the code directories they describe.\n- The workflow will ask you to approve an update plan before making any edits -- review it carefully. This is the main checkpoint where you control scope.\n- If you want to defer lower-priority improvements, say so during plan review.",
+  "examples": [
+    "Update the API docs for the search service after last month's v3 endpoint changes",
+    "Refresh the developer onboarding guide -- it hasn't been updated since we migrated to Gradle 8",
+    "Audit the architecture decision records in docs/adr/ for accuracy against the current codebase",
+    "Update the GraphQL schema documentation to reflect recent breaking changes"
+  ],
   "preconditions": [
     "Target documentation files are accessible",
     "Agent has git access to the repository containing both docs and code",
@@ -14,15 +21,15 @@
     "GIT-EVIDENCE-FIRST: staleness judgment must be grounded in actual git log output. Do not assert a doc is stale based on reading it alone. Run git log; record commit SHAs and messages as evidence.",
     "PRESERVATION-FIRST: keep accurate, well-written content unchanged. Only update what is demonstrably stale or incorrect. Targeted updates are better than wholesale rewrites.",
     "VERIFY AGAINST CODE: all updated technical content must be checked against current codebase state. Code examples and API references must match what is actually in the code today.",
-    "DEGRADE AND DISCLOSE: if git history is unavailable or shallow for some paths, classify staleness as medium and note what evidence is missing. Never block \u2014 proceed with what is available.",
+    "DEGRADE AND DISCLOSE: if git history is unavailable or shallow for some paths, classify staleness as medium and note what evidence is missing. Never block — proceed with what is available.",
     "SELF-EXECUTE: explore first with tools. Ask the user only what you genuinely cannot determine from the codebase and git history. The one real confirmation gate is the update plan before executing edits.",
-    "LOOP DISCIPLINE: the update loop runs without per-section gates \u2014 the plan was approved in phase-2. Only pause if a section requires changes beyond what the approved plan covers; note the deviation and ask."
+    "LOOP DISCIPLINE: the update loop runs without per-section gates — the plan was approved in phase-2. Only pause if a section requires changes beyond what the approved plan covers; note the deviation and ask."
   ],
   "steps": [
     {
       "id": "phase-0-assess",
       "title": "Phase 0: Assess Documentation & Establish Git Baseline",
-      "prompt": "Locate the target documentation and establish an evidence-based staleness assessment before you decide anything.\n\n**Step 1: Locate and inventory target docs**\n- Identify all documentation files in scope\n- Note file formats, structure, and rough section organization\n- Infer the code paths these docs reference (scopePaths)\n\n**Step 2: Git baseline**\n- Run `git log -1 <docPath>` for each target doc to get the last commit SHA and date\n- Run `git log <lastCommitSha>..HEAD -- <scopePaths>` to get all code changes since the doc was last updated\n- For each commit, classify impact: API/breaking (new exports, changed interfaces, removed functions), behavioral (changed logic), config (schema/option changes), or minor (refactor, rename, test-only)\n\n**Step 3: Staleness classification (rubric-based)**\n\nScore these three dimensions:\n- **Impact**: any API/breaking changes? any behavioral or config changes?\n- **Volume**: how many commits changed the relevant scope since last doc update?\n- **Age**: how many days since the doc was last committed?\n\nDerive `stalenessLevel`:\n- `high`: any API/breaking impact, OR volume > 5 commits AND age > 90 days\n- `medium`: volume > 2 commits, OR age > 60 days, OR behavioral/config changes present\n- `low`: few changes, nothing impacting documented behavior, age < 60 days\n- If git history is unavailable: `medium` \u2014 note what is missing\n\nDerive `updateUrgency`:\n- `high` staleness \u2192 `immediate`\n- `medium` staleness \u2192 `scheduled`\n- `low` staleness \u2192 `monitor` \u2014 if user did not request a forced update, document why and offer to exit\n\n**Capture:**\n- `targetDocPaths`, `scopePaths`\n- `gitLastDocCommitSha`, `gitLastDocCommitDate`\n- `stalenessLevel`, `updateUrgency`\n- `gitChangeSummary` \u2014 prose summary of what changed and why it matters for the docs",
+      "prompt": "Locate the target documentation and establish an evidence-based staleness assessment before you decide anything.\n\n**Step 1: Locate and inventory target docs**\n- Identify all documentation files in scope\n- Note file formats, structure, and rough section organization\n- Infer the code paths these docs reference (scopePaths)\n\n**Step 2: Git baseline**\n- Run `git log -1 <docPath>` for each target doc to get the last commit SHA and date\n- Run `git log <lastCommitSha>..HEAD -- <scopePaths>` to get all code changes since the doc was last updated\n- For each commit, classify impact: API/breaking (new exports, changed interfaces, removed functions), behavioral (changed logic), config (schema/option changes), or minor (refactor, rename, test-only)\n\n**Step 3: Staleness classification (rubric-based)**\n\nScore these three dimensions:\n- **Impact**: any API/breaking changes? any behavioral or config changes?\n- **Volume**: how many commits changed the relevant scope since last doc update?\n- **Age**: how many days since the doc was last committed?\n\nDerive `stalenessLevel`:\n- `high`: any API/breaking impact, OR volume > 5 commits AND age > 90 days\n- `medium`: volume > 2 commits, OR age > 60 days, OR behavioral/config changes present\n- `low`: few changes, nothing impacting documented behavior, age < 60 days\n- If git history is unavailable: `medium` — note what is missing\n\nDerive `updateUrgency`:\n- `high` staleness → `immediate`\n- `medium` staleness → `scheduled`\n- `low` staleness → `monitor` — if user did not request a forced update, document why and offer to exit\n\n**Capture:**\n- `targetDocPaths`, `scopePaths`\n- `gitLastDocCommitSha`, `gitLastDocCommitDate`\n- `stalenessLevel`, `updateUrgency`\n- `gitChangeSummary` — prose summary of what changed and why it matters for the docs",
       "requireConfirmation": {
         "var": "updateUrgency",
         "equals": "monitor"
@@ -31,13 +38,13 @@
     {
       "id": "phase-1-analyze",
       "title": "Phase 1: Section-by-Section Gap Analysis",
-      "prompt": "Now map each documentation section to current code and classify what needs to change.\n\nFor each section in the target docs:\n1. **Map to code** \u2014 which files, functions, APIs, or behaviors does this section describe?\n2. **Assess accuracy** \u2014 does the current code match what the section says? Check API signatures, config options, behavioral descriptions, examples, and file paths.\n3. **Classify the section action**:\n   - `preserve` \u2014 still accurate, well-written; keep unchanged\n   - `update` \u2014 needs correction or expansion; note specifically what changed\n   - `remove` \u2014 describes something that no longer exists\n\n4. **Assign update type** for sections marked `update`:\n   - `corrective` \u2014 fix inaccurate information\n   - `additive` \u2014 add missing coverage for new features\n   - `expansive` \u2014 expand thin explanations\n   - `reductive` \u2014 remove deprecated or removed content\n   - `structural` \u2014 reorganize while preserving content\n\n5. **Assign priority** for sections marked `update`:\n   - `critical` \u2014 inaccurate content that would cause errors or confusion for users\n   - `important` \u2014 missing or outdated content for significant features or workflows\n   - `beneficial` \u2014 improvements that add value but aren't blocking\n\n**Capture:**\n- `sectionInventory` \u2014 list of all sections with: sectionId, action (preserve/update/remove), updateType, priority, and a one-line reason\n\nEvery section must be classified before moving on.",
+      "prompt": "Now map each documentation section to current code and classify what needs to change.\n\nFor each section in the target docs:\n1. **Map to code** — which files, functions, APIs, or behaviors does this section describe?\n2. **Assess accuracy** — does the current code match what the section says? Check API signatures, config options, behavioral descriptions, examples, and file paths.\n3. **Classify the section action**:\n   - `preserve` — still accurate, well-written; keep unchanged\n   - `update` — needs correction or expansion; note specifically what changed\n   - `remove` — describes something that no longer exists\n\n4. **Assign update type** for sections marked `update`:\n   - `corrective` — fix inaccurate information\n   - `additive` — add missing coverage for new features\n   - `expansive` — expand thin explanations\n   - `reductive` — remove deprecated or removed content\n   - `structural` — reorganize while preserving content\n\n5. **Assign priority** for sections marked `update`:\n   - `critical` — inaccurate content that would cause errors or confusion for users\n   - `important` — missing or outdated content for significant features or workflows\n   - `beneficial` — improvements that add value but aren't blocking\n\n**Capture:**\n- `sectionInventory` — list of all sections with: sectionId, action (preserve/update/remove), updateType, priority, and a one-line reason\n\nEvery section must be classified before moving on.",
       "requireConfirmation": false
     },
     {
       "id": "phase-2-plan",
       "title": "Phase 2: Update Plan",
-      "prompt": "Build the ordered update plan based on the section inventory, then confirm it with me before you start editing anything.\n\nFrom `sectionInventory`, create `updatePlan` as an ordered list:\n1. All `critical` updates first\n2. `important` updates next\n3. `beneficial` updates last (may defer if scope is large)\n\nFor each entry in the plan:\n- Section name and location\n- Update type (corrective / additive / expansive / reductive / structural)\n- Specific description of what to change and why\n- What content to preserve unchanged\n\nAlso note:\n- Total sections to update vs total sections to preserve\n- Any `remove` entries that need explicit deletion\n- Any sections that are `beneficial` you recommend deferring\n\n**This step requires confirmation** \u2014 I need to review the plan before you make edits to the documentation files.\n\n**Capture:**\n- `updatePlan` \u2014 ordered list as described above\n- `sectionsRemaining` \u2014 total count of sections to update (for loop tracking)",
+      "prompt": "Build the ordered update plan based on the section inventory, then confirm it with me before you start editing anything.\n\nFrom `sectionInventory`, create `updatePlan` as an ordered list:\n1. All `critical` updates first\n2. `important` updates next\n3. `beneficial` updates last (may defer if scope is large)\n\nFor each entry in the plan:\n- Section name and location\n- Update type (corrective / additive / expansive / reductive / structural)\n- Specific description of what to change and why\n- What content to preserve unchanged\n\nAlso note:\n- Total sections to update vs total sections to preserve\n- Any `remove` entries that need explicit deletion\n- Any sections that are `beneficial` you recommend deferring\n\n**This step requires confirmation** — I need to review the plan before you make edits to the documentation files.\n\n**Capture:**\n- `updatePlan` — ordered list as described above\n- `sectionsRemaining` — total count of sections to update (for loop tracking)",
       "requireConfirmation": true
     },
     {
@@ -69,7 +76,7 @@
         {
           "id": "verify-section",
           "title": "Verify the Updated Section",
-          "prompt": "Verify that the update to `currentSection` is correct before moving on.\n\nCheck:\n1. **Technical accuracy** \u2014 does every technical claim match the current codebase? Check the code directly if needed.\n2. **Code examples** \u2014 are all code blocks in this section syntactically valid and behaviorally correct against current APIs?\n3. **Preservation** \u2014 what did you keep unchanged? Confirm the preserved content is still present and intact.\n4. **Cross-references** \u2014 are any internal links pointing to or from this section still working?\n\nDecrement `sectionsRemaining` by 1.\n\nRecord findings in notes: what you changed, what you preserved, any issues found.\n\n**Capture:** updated `sectionsRemaining`",
+          "prompt": "Verify that the update to `currentSection` is correct before moving on.\n\nCheck:\n1. **Technical accuracy** — does every technical claim match the current codebase? Check the code directly if needed.\n2. **Code examples** — are all code blocks in this section syntactically valid and behaviorally correct against current APIs?\n3. **Preservation** — what did you keep unchanged? Confirm the preserved content is still present and intact.\n4. **Cross-references** — are any internal links pointing to or from this section still working?\n\nDecrement `sectionsRemaining` by 1.\n\nRecord findings in notes: what you changed, what you preserved, any issues found.\n\n**Capture:** updated `sectionsRemaining`",
           "requireConfirmation": false
         },
         {
@@ -87,7 +94,7 @@
     {
       "id": "phase-4-validate",
       "title": "Phase 4: End-to-End Validation",
-      "prompt": "Read through all updated documentation as a fresh reader and validate it as a whole.\n\n1. **End-to-end consistency** \u2014 read the docs in order. Is terminology consistent? Does the logical flow make sense? Do sections refer to each other correctly?\n\n2. **Technical accuracy pass** \u2014 for any section you feel uncertain about, verify it against current code now. If verification reveals a remaining inaccuracy, note it explicitly: what is wrong, where it is, and what the correct information should be. Do not silently pass a section you are unsure about.\n\n3. **User journey test** \u2014 walk through the key documented workflows from start to finish using only the documentation. Do setup instructions work? Are the most important use cases covered correctly?\n\n4. **Navigation and structure** \u2014 are all cross-references working? Is the table of contents (if present) accurate? Can a user find what they need?\n\n5. **Completeness check** \u2014 look back at the original gap analysis. Were all critical and important updates completed? Note explicitly if any were deferred.\n\nDocument what you found: any remaining issues, any sections that still need work, and your overall assessment of the documentation quality after the update.",
+      "prompt": "Read through all updated documentation as a fresh reader and validate it as a whole.\n\n1. **End-to-end consistency** — read the docs in order. Is terminology consistent? Does the logical flow make sense? Do sections refer to each other correctly?\n\n2. **Technical accuracy pass** — for any section you feel uncertain about, verify it against current code now. If verification reveals a remaining inaccuracy, note it explicitly: what is wrong, where it is, and what the correct information should be. Do not silently pass a section you are unsure about.\n\n3. **User journey test** — walk through the key documented workflows from start to finish using only the documentation. Do setup instructions work? Are the most important use cases covered correctly?\n\n4. **Navigation and structure** — are all cross-references working? Is the table of contents (if present) accurate? Can a user find what they need?\n\n5. **Completeness check** — look back at the original gap analysis. Were all critical and important updates completed? Note explicitly if any were deferred.\n\nDocument what you found: any remaining issues, any sections that still need work, and your overall assessment of the documentation quality after the update.",
       "requireConfirmation": false
     },
     {
@@ -97,4 +104,4 @@
       "requireConfirmation": false
     }
   ]
-}
+}

package/workflows/intelligent-test-case-generation.json

@@ -3,6 +3,13 @@
   "name": "Test Case Generation from Tickets",
   "version": "1.0.0",
   "description": "Use this to generate integration and end-to-end test cases from ticket requirements. Reads the ticket, traces affected code paths, identifies boundary conditions, and produces developer-readable test case descriptions.",
+  "about": "## Intelligent Test Case Generation\n\nThis workflow generates structured integration and end-to-end test cases directly from a ticket. It reads the ticket requirements, traces the affected code paths in the codebase, identifies boundary conditions and failure scenarios, and produces developer-readable test case descriptions that a developer can implement without guessing.\n\n**What it does:**\nThe workflow extracts every acceptance criterion from the ticket, traces which modules, endpoints, and integration boundaries are involved, identifies the existing test patterns in the repo (so generated cases match the team's style), then systematically generates happy path, boundary, and failure scenarios for each criterion. It checks coverage before writing, resolves ambiguities with you before generating anything uncertain, and finishes with a full test case list plus a coverage summary.\n\n**When to use it:**\n- When a ticket has clear acceptance criteria and you want comprehensive test coverage without manually reasoning through every edge case\n- When onboarding to a feature area and wanting to understand the expected behavior through its test scenarios\n- When a ticket spans multiple services or integration points and you need coverage across all of them\n- When preparing for a QA handoff or code review where test coverage must be explicitly demonstrated\n\n**What it produces:**\nNumbered test cases (TC-1, TC-2, ...) each with a title, acceptance criterion mapping, test type (Integration or E2E), risk level, preconditions, numbered test steps, expected result, and implementation notes. Cases are grouped by acceptance criterion and followed by a summary table. Open ambiguities and coverage gaps are disclosed explicitly.\n\n**How to get good results:**\nProvide the ticket in any standard format -- title, description, and acceptance criteria are enough. The workflow will trace the codebase itself. If the ticket has linked specs, API docs, or architecture diagrams, mention them. The more complete the acceptance criteria, the fewer clarifying questions the workflow will need to ask.",
+  "examples": [
+    "Generate test cases for ACEI-1591: expire cached conversations after 24 hours of inactivity",
+    "Write integration test scenarios for the ticket adding multi-factor authentication to the login flow",
+    "Generate E2E test cases for the checkout redesign ticket covering all payment method variations",
+    "Create test cases for the ticket migrating user profile storage from Postgres to the new profile service"
+  ],
   "preconditions": [
     "User provides a ticket (title, description, acceptance criteria) in any standard format.",
     "Agent has read access to the codebase for tracing affected paths and finding existing test patterns.",

package/workflows/learner-centered-course-workflow.json

@@ -3,6 +3,13 @@
   "name": "Personal Learning Course Design Workflow",
   "version": "1.0.0",
   "description": "Use this to design a personal learning course. Creates structured learning objectives, sequencing, and a course outline suited to your time constraints.",
+  "about": "## Personal Learning Course Design Workflow\n\nUse this to design a structured personal learning course -- defining clear objectives, sequencing, assessments, and a schedule that fits your time constraints. This workflow focuses on the **design** phase: building the blueprint for your learning program before you create any materials.\n\n### What it produces\n\nDepending on the path you choose:\n\n- **Quick Start (3-5 days)**: a functional learning plan with 2-3 focused objectives, a weekly schedule, a resource list, and basic progress tracking.\n- **Balanced (1-2 weeks)**: a comprehensive learning system with modules, structured assessments, active learning activities, and accountability measures.\n- **Comprehensive (2-3 weeks)**: a professional-grade learning system with full Bloom's Taxonomy-aligned objectives, spaced repetition design, multi-layer assessments, and long-term retention planning.\n\n### When to use it\n\n- You want to learn something specific and want a structured plan rather than ad-hoc resource consumption.\n- You are preparing for a certification, career transition, or skill upgrade and need a realistic timeline and sequence.\n- You've tried self-study before and found it hard to stay on track -- a well-designed plan with clear checkpoints helps.\n\n### When NOT to use it\n\n- You need to create the actual study materials -- use the Personal Learning Materials Creation workflow after this one.\n- You're designing a course for other learners, not for yourself -- consider an instructional design workflow instead.\n\n### How to get good results\n\n- Be honest about your weekly time budget. An ambitious plan that doesn't fit your schedule is worse than a modest plan you actually follow.\n- Start with the Quick Start path if you're uncertain -- you can always expand. Choosing Comprehensive when you're time-constrained leads to abandonment.\n- The more specific your goal (\"pass the AWS SAA exam in 3 months\"), the better the resulting plan will be compared to a vague goal (\"learn cloud\").",
+  "examples": [
+    "Design a 12-week self-study plan to pass the AWS Solutions Architect Associate exam",
+    "Create a balanced learning plan for learning Go, starting from zero, with 6 hours per week available",
+    "Build a comprehensive course design for mastering data visualization with Python over 3 months",
+    "Design a quick-start plan to get productive with Rust in 4 weeks"
+  ],
   "clarificationPrompts": [
     "What specific knowledge or skill do you want to master for yourself? (Be precise about the learning goal)",
     "How will you know you've successfully learned this? What will you be able to do, create, or solve? (Define your personal success criteria)",
@@ -29,7 +36,7 @@
     {
       "id": "select-design-path",
       "title": "Choose Your Learning Design Path",
-      "prompt": "Based on your time constraints and learning design experience, select the approach that best fits your needs:\n\n**\ud83d\ude80 QUICK START PATH (3-5 days)**\n- **Best for**: First-time course designers, tight timelines, simple learning goals\n- **What you get**: Essential structure with clear objectives, basic assessment, and simple schedule\n- **Time investment**: 3-5 days to complete design process\n- **Result**: Functional learning plan that covers the basics effectively\n\n**\u2696\ufe0f BALANCED PATH (1-2 weeks)**\n- **Best for**: Some learning design experience, moderate complexity goals, want good system without overwhelm\n- **What you get**: Solid instructional design plus engagement features, assessment strategy, and progress tracking\n- **Time investment**: 1-2 weeks to complete design process\n- **Result**: Comprehensive learning system with proven pedagogical principles\n\n**\ud83c\udf93 COMPREHENSIVE PATH (2-3 weeks)**\n- **Best for**: Complex learning goals, want professional-grade system, experienced with instructional design\n- **What you get**: Full pedagogical depth with spaced repetition, detailed accountability, and advanced monitoring\n- **Time investment**: 2-3 weeks to complete design process\n- **Result**: Professional-grade learning system with all advanced features\n\n**Please select your path:**\n- Type 'quick' for Quick Start Path (3-5 days)\n- Type 'balanced' for Balanced Path (1-2 weeks)\n- Type 'comprehensive' for Comprehensive Path (2-3 weeks)\n\nYour choice will customize the remaining steps to match your needs and time constraints.",
+      "prompt": "Based on your time constraints and learning design experience, select the approach that best fits your needs:\n\n**🚀 QUICK START PATH (3-5 days)**\n- **Best for**: First-time course designers, tight timelines, simple learning goals\n- **What you get**: Essential structure with clear objectives, basic assessment, and simple schedule\n- **Time investment**: 3-5 days to complete design process\n- **Result**: Functional learning plan that covers the basics effectively\n\n**⚖️ BALANCED PATH (1-2 weeks)**\n- **Best for**: Some learning design experience, moderate complexity goals, want good system without overwhelm\n- **What you get**: Solid instructional design plus engagement features, assessment strategy, and progress tracking\n- **Time investment**: 1-2 weeks to complete design process\n- **Result**: Comprehensive learning system with proven pedagogical principles\n\n**🎓 COMPREHENSIVE PATH (2-3 weeks)**\n- **Best for**: Complex learning goals, want professional-grade system, experienced with instructional design\n- **What you get**: Full pedagogical depth with spaced repetition, detailed accountability, and advanced monitoring\n- **Time investment**: 2-3 weeks to complete design process\n- **Result**: Professional-grade learning system with all advanced features\n\n**Please select your path:**\n- Type 'quick' for Quick Start Path (3-5 days)\n- Type 'balanced' for Balanced Path (1-2 weeks)\n- Type 'comprehensive' for Comprehensive Path (2-3 weeks)\n\nYour choice will customize the remaining steps to match your needs and time constraints.",
       "agentRole": "You are a learning design consultant who helps users choose the right level of complexity for their learning design process. Guide them to select a path that matches their experience, time constraints, and learning goals without overwhelming them.",
       "guidance": [
         "Help users honestly assess their time availability and design experience",
@@ -285,4 +292,4 @@
       "hasValidation": true
     }
   ]
-}
+}

package/workflows/mr-review-workflow.agentic.v2.json

@@ -3,6 +3,13 @@
   "name": "MR Review Workflow (Lean v2 \u2022 Notes-First \u2022 Evidence-Driven Reviewer Families)",
   "version": "2.4.0",
   "description": "Lean v2 MR review workflow. Merges intake, missing-input gating, context gathering, and re-triage into one structured front phase, then drives review through a shared fact packet, parallel reviewer families, contradiction-driven synthesis, and evidence-first final validation.",
+  "about": "## MR Review Workflow\n\nThis workflow conducts a structured, evidence-driven code review of a merge request or pull request. It is designed for cases where you want a thorough, audit-quality review rather than a quick glance -- particularly when the change touches critical surfaces, spans many files, or carries real production risk.\n\n**What it does:**\nThe workflow locates and bounds the review target, enriches it with PR context and ticket intent, classifies the change by risk and shape, then runs parallel \"reviewer family\" agents (covering correctness, architecture, runtime risk, tests/docs, and more) from a shared neutral fact packet. It reconciles contradictions between reviewer families, stress-tests the recommendation with adversarial validators, and produces a final handoff with severity-classified findings and ready-to-post MR comments.\n\n**When to use it:**\n- Before merging a PR that touches auth, data models, APIs, or critical paths\n- When you want independent perspectives on a change without the noise of an unstructured review\n- When the change is large or the reviewer is unfamiliar with the surrounding code\n- When you need a reproducible audit trail for compliance or team review processes\n\n**What it produces:**\nA final review recommendation (approve / request changes / needs discussion) with a confidence band, severity-graded findings (Critical / Major / Minor / Nit), ready-to-post MR comments, a coverage ledger showing which review domains were checked, and an honest disclosure of any context that could not be recovered.\n\n**How to get good results:**\nProvide the PR URL, branch name, or diff. The workflow can recover most context on its own -- ticket links, repo patterns, policy docs -- but if the change has non-obvious intent, a one-sentence description of the goal helps calibrate review sensitivity. The workflow will not post comments or approve/reject without explicit instruction.",
+  "examples": [
+    "Review PR #47 adding JWT refresh token rotation before it merges to main",
+    "Review the feature/cache-expiration branch for correctness and production risk before merging",
+    "Audit PR #312 refactoring the payment service data model for backward compatibility and rollout safety",
+    "Review the open MR for the new rate-limiting middleware against our API contract standards"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"

package/workflows/personal-learning-materials-creation-branched.json

@@ -2,7 +2,14 @@
   "id": "personal-learning-materials-creation-branched",
   "name": "Personal Learning Materials Creation Workflow (Branched)",
   "version": "1.1.0",
-  "description": "Use this to create learning materials for a course or subject. Adapts depth and format to your time budget \u2014 Quick Start, Balanced, or Comprehensive.",
+  "description": "Use this to create learning materials for a course or subject. Adapts depth and format to your time budget — Quick Start, Balanced, or Comprehensive.",
+  "about": "## Personal Learning Materials Creation Workflow\n\nUse this to create the actual study materials for a course or subject you are learning -- study guides, exercises, assessments, and spaced-repetition review materials. This workflow assumes you already have a learning plan or course design with defined objectives; it focuses on producing materials that directly support those objectives.\n\n### What it produces\n\nDepending on the path you choose:\n\n- **Quick Start (2-3 weeks)**: study guides and basic exercises for immediate use.\n- **Balanced (4-6 weeks)**: a complete learning system -- study guides, exercises, assessments, and spaced repetition materials.\n- **Comprehensive (8-12 weeks)**: a full learning ecosystem with interactive elements, effectiveness measurement, and a scalable update protocol.\n\n### When to use it\n\n- You have a learning plan and need to turn it into usable materials.\n- You are preparing for a certification, exam, or structured self-study program.\n- You want materials tailored to your specific objectives rather than relying entirely on off-the-shelf resources.\n\n### When NOT to use it\n\n- You haven't designed your learning course yet -- use the Personal Learning Course Design workflow first to define objectives and structure.\n- You need to design a course for others to take -- use the Learner-Centered Course workflow instead.\n\n### How to get good results\n\n- Select the path honestly based on available time. Starting with Quick Start and expanding later is better than committing to Comprehensive and abandoning it.\n- Have your learning objectives written out before starting -- the workflow maps every material directly to an objective.\n- Be specific about your preferred learning formats (text, diagrams, flashcards, practice problems) at the start.",
+  "examples": [
+    "Create study guides and exercises for my AWS Solutions Architect certification prep",
+    "Build a complete set of flashcards and practice problems for learning Rust ownership",
+    "Create materials for a 6-week self-study course on Bayesian statistics",
+    "Make a quick-start study guide for the CKAD Kubernetes exam"
+  ],
   "clarificationPrompts": [
     "Do you have a completed learning plan with defined objectives and modules?",
     "How much time can you dedicate weekly to materials creation?",
@@ -25,7 +32,7 @@
     {
       "id": "phase-0-select-thoroughness-path",
       "title": "Phase 0: Select Your Materials Creation Path",
-      "prompt": "Choose your learning materials creation approach based on your time, goals, and quality needs:\n\n\ud83d\udcda **Quick Start Path**\n\u2022 Timeline: 2-3 weeks (5-8 hours total)\n\u2022 Materials: Study guides + basic exercises\n\u2022 Best for: Time-constrained learners, getting started quickly\n\u2022 Outcome: Functional materials for immediate use\n\n\ud83c\udfaf **Balanced Path**\n\u2022 Timeline: 4-6 weeks (12-20 hours total)\n\u2022 Materials: Study guides + exercises + assessments + spaced repetition\n\u2022 Best for: Comprehensive learning support, professional quality\n\u2022 Outcome: Complete learning system with proven effectiveness\n\n\ud83c\udfc6 **Comprehensive Path**\n\u2022 Timeline: 8-12 weeks (25-40 hours total)\n\u2022 Materials: All types + interactive elements + full testing\n\u2022 Best for: Professional educators, enterprise-grade projects\n\u2022 Outcome: Optimized learning ecosystem with maximum effectiveness\n\nWhich path best matches your timeline and quality goals?",
+      "prompt": "Choose your learning materials creation approach based on your time, goals, and quality needs:\n\n📚 **Quick Start Path**\n• Timeline: 2-3 weeks (5-8 hours total)\n• Materials: Study guides + basic exercises\n• Best for: Time-constrained learners, getting started quickly\n• Outcome: Functional materials for immediate use\n\n🎯 **Balanced Path**\n• Timeline: 4-6 weeks (12-20 hours total)\n• Materials: Study guides + exercises + assessments + spaced repetition\n• Best for: Comprehensive learning support, professional quality\n• Outcome: Complete learning system with proven effectiveness\n\n🏆 **Comprehensive Path**\n• Timeline: 8-12 weeks (25-40 hours total)\n• Materials: All types + interactive elements + full testing\n• Best for: Professional educators, enterprise-grade projects\n• Outcome: Optimized learning ecosystem with maximum effectiveness\n\nWhich path best matches your timeline and quality goals?",
       "agentRole": "You are a learning materials consultant specializing in helping users choose the right approach for their constraints and goals. Guide users toward the path that best fits their needs. Set the thoroughnessLevel context variable based on their selection.",
       "guidance": [
         "Help users make realistic choices based on their actual time availability",
@@ -41,7 +48,7 @@
         "equals": "Quick"
       },
       "title": "Phase 1: Essential Learning Plan Analysis (Quick Start)",
-      "prompt": "Extract the core elements from your learning plan for rapid materials creation:\n\n**STEP 1: Core Objectives**\n\u2022 Identify your 3-5 most important learning objectives\n\u2022 Note success criteria for each objective\n\u2022 Skip complex prerequisite analysis\n\n**STEP 2: Essential Materials Map**\n\u2022 For each objective, identify if you need: study guide, basic exercises, or both\n\u2022 Focus on immediate learning needs, not comprehensive coverage\n\u2022 Note existing resources that can supplement your materials\n\n**STEP 3: Quick Resource Assessment**\n\u2022 List available source materials (books, courses, notes)\n\u2022 Identify 2-3 key resources for each objective\n\u2022 Note time constraints and creation priorities\n\nGoal: Practical roadmap for essential materials creation in minimal time.",
+      "prompt": "Extract the core elements from your learning plan for rapid materials creation:\n\n**STEP 1: Core Objectives**\n• Identify your 3-5 most important learning objectives\n• Note success criteria for each objective\n• Skip complex prerequisite analysis\n\n**STEP 2: Essential Materials Map**\n• For each objective, identify if you need: study guide, basic exercises, or both\n• Focus on immediate learning needs, not comprehensive coverage\n• Note existing resources that can supplement your materials\n\n**STEP 3: Quick Resource Assessment**\n• List available source materials (books, courses, notes)\n• Identify 2-3 key resources for each objective\n• Note time constraints and creation priorities\n\nGoal: Practical roadmap for essential materials creation in minimal time.",
       "agentRole": "You are an efficient learning analyst focused on rapid materials development. Help users identify core needs quickly without over-analysis. Emphasize practical, immediately actionable insights.",
       "guidance": [
         "Keep analysis focused and action-oriented",
@@ -75,7 +82,7 @@
         "equals": "Balanced"
       },
       "title": "Phase 1: Comprehensive Learning Plan Analysis (Balanced)",
-      "prompt": "Analyze your learning plan to guide professional-quality materials creation:\n\n**STEP 1: Objective Architecture**\n\u2022 Extract all learning objectives with success criteria\n\u2022 Identify prerequisite relationships between objectives\n\u2022 Note assessment strategies for each objective\n\u2022 Map objectives to modules and time allocations\n\n**STEP 2: Materials Requirements Matrix**\n\u2022 For each objective, determine needed materials: study guides, exercises, assessments\n\u2022 Identify concepts requiring multiple reinforcement approaches\n\u2022 Note which objectives need spaced repetition support\n\u2022 Flag areas requiring practical application or hands-on practice\n\n**STEP 3: Resource Integration Plan**\n\u2022 Evaluate existing resources for quality and coverage\n\u2022 Identify gaps where custom materials are essential\n\u2022 Plan integration between created materials and external resources\n\u2022 Design quality standards for materials consistency\n\nGoal: Strategic foundation for professional learning materials system.",
+      "prompt": "Analyze your learning plan to guide professional-quality materials creation:\n\n**STEP 1: Objective Architecture**\n• Extract all learning objectives with success criteria\n• Identify prerequisite relationships between objectives\n• Note assessment strategies for each objective\n• Map objectives to modules and time allocations\n\n**STEP 2: Materials Requirements Matrix**\n• For each objective, determine needed materials: study guides, exercises, assessments\n• Identify concepts requiring multiple reinforcement approaches\n• Note which objectives need spaced repetition support\n• Flag areas requiring practical application or hands-on practice\n\n**STEP 3: Resource Integration Plan**\n• Evaluate existing resources for quality and coverage\n• Identify gaps where custom materials are essential\n• Plan integration between created materials and external resources\n• Design quality standards for materials consistency\n\nGoal: Strategic foundation for professional learning materials system.",
       "agentRole": "You are a professional instructional designer specializing in systematic materials development. Help users create comprehensive yet practical plans that balance quality with efficiency. Focus on proven instructional design principles.",
       "guidance": [
         "Apply instructional design best practices systematically",
@@ -104,7 +111,7 @@
         "equals": "Comprehensive"
       },
       "title": "Phase 1: Expert Learning Plan Analysis (Comprehensive)",
-      "prompt": "Conduct thorough analysis of learning architecture for enterprise-grade materials:\n\n**STEP 1: Learning System Architecture**\n\u2022 Map complete learning objective hierarchy with dependencies\n\u2022 Analyze cognitive load and complexity progression\n\u2022 Identify multiple learning pathways and individual differences\n\u2022 Design assessment strategy aligned with learning taxonomies\n\n**STEP 2: Advanced Materials Strategy**\n\u2022 Determine optimal material types for each learning objective\n\u2022 Plan multi-modal approach for different learning styles\n\u2022 Design integration points for spaced repetition and active recall\n\u2022 Identify opportunities for interactive and adaptive elements\n\n**STEP 3: Quality & Effectiveness Framework**\n\u2022 Establish criteria for materials effectiveness measurement\n\u2022 Plan user testing and feedback integration\n\u2022 Design continuous improvement and iteration protocols\n\u2022 Create scalability and maintenance considerations\n\nGoal: Strategic foundation for optimized, enterprise-grade learning ecosystem.",
+      "prompt": "Conduct thorough analysis of learning architecture for enterprise-grade materials:\n\n**STEP 1: Learning System Architecture**\n• Map complete learning objective hierarchy with dependencies\n• Analyze cognitive load and complexity progression\n• Identify multiple learning pathways and individual differences\n• Design assessment strategy aligned with learning taxonomies\n\n**STEP 2: Advanced Materials Strategy**\n• Determine optimal material types for each learning objective\n• Plan multi-modal approach for different learning styles\n• Design integration points for spaced repetition and active recall\n• Identify opportunities for interactive and adaptive elements\n\n**STEP 3: Quality & Effectiveness Framework**\n• Establish criteria for materials effectiveness measurement\n• Plan user testing and feedback integration\n• Design continuous improvement and iteration protocols\n• Create scalability and maintenance considerations\n\nGoal: Strategic foundation for optimized, enterprise-grade learning ecosystem.",
       "agentRole": "You are an expert learning systems architect with deep expertise in advanced instructional design and learning optimization. Guide users in creating sophisticated materials that maximize learning effectiveness through evidence-based approaches.",
       "guidance": [
         "Apply advanced learning science principles and research",
@@ -133,7 +140,7 @@
         "equals": "Quick"
       },
       "title": "Phase 2: Efficient Materials Strategy (Quick Start)",
-      "prompt": "Create a focused strategy for essential materials creation:\n\n**STEP 1: Format Selection**\n\u2022 Choose 1-2 primary formats based on your learning style\n\u2022 Prioritize formats you can create quickly (text-based, simple templates)\n\u2022 Plan minimal but consistent formatting approach\n\u2022 Focus on immediate usability over visual polish\n\n**STEP 2: Creation Workflow**\n\u2022 Design simple templates for study guides and exercises\n\u2022 Plan batch creation approach to maximize efficiency\n\u2022 Set realistic quality standards (functional over perfect)\n\u2022 Create basic organization system for easy access\n\n**STEP 3: Quality Framework**\n\u2022 Establish minimum viable product standards\n\u2022 Plan quick self-review process\n\u2022 Design simple feedback collection for future improvement\n\u2022 Focus on completion over perfection\n\nGoal: Practical strategy for rapid materials creation without sacrificing core functionality.",
+      "prompt": "Create a focused strategy for essential materials creation:\n\n**STEP 1: Format Selection**\n• Choose 1-2 primary formats based on your learning style\n• Prioritize formats you can create quickly (text-based, simple templates)\n• Plan minimal but consistent formatting approach\n• Focus on immediate usability over visual polish\n\n**STEP 2: Creation Workflow**\n• Design simple templates for study guides and exercises\n• Plan batch creation approach to maximize efficiency\n• Set realistic quality standards (functional over perfect)\n• Create basic organization system for easy access\n\n**STEP 3: Quality Framework**\n• Establish minimum viable product standards\n• Plan quick self-review process\n• Design simple feedback collection for future improvement\n• Focus on completion over perfection\n\nGoal: Practical strategy for rapid materials creation without sacrificing core functionality.",
       "agentRole": "You are an efficiency expert specializing in rapid content creation. Help users design streamlined approaches that maximize output while maintaining essential quality. Focus on practical, time-saving strategies.",
       "guidance": [
         "Emphasize efficiency and speed over perfection",
@@ -162,7 +169,7 @@
         "equals": "Comprehensive"
       },
       "title": "Phase 2: Advanced Materials Strategy (Comprehensive)",
-      "prompt": "Develop sophisticated strategy for enterprise-grade materials:\n\n**STEP 1: Multi-Modal Format Strategy**\n\u2022 Design format variety to engage different learning modes\n\u2022 Plan advanced visual elements, interactive components, adaptive features\n\u2022 Create sophisticated template system with consistent branding\n\u2022 Consider accessibility, mobile optimization, and universal design\n\n**STEP 2: Integration Architecture**\n\u2022 Plan seamless connections between all material types\n\u2022 Design advanced spaced repetition integration with learning analytics\n\u2022 Create sophisticated cross-referencing and linking systems\n\u2022 Plan for collaborative features and social learning elements\n\n**STEP 3: Quality Excellence Framework**\n\u2022 Establish enterprise-grade quality standards and measurement\n\u2022 Design comprehensive user testing and feedback integration\n\u2022 Plan continuous optimization based on learning effectiveness data\n\u2022 Create scalable maintenance and update protocols\n\nGoal: Strategic foundation for learning materials that optimize effectiveness through sophisticated design.",
+      "prompt": "Develop sophisticated strategy for enterprise-grade materials:\n\n**STEP 1: Multi-Modal Format Strategy**\n• Design format variety to engage different learning modes\n• Plan advanced visual elements, interactive components, adaptive features\n• Create sophisticated template system with consistent branding\n• Consider accessibility, mobile optimization, and universal design\n\n**STEP 2: Integration Architecture**\n• Plan seamless connections between all material types\n• Design advanced spaced repetition integration with learning analytics\n• Create sophisticated cross-referencing and linking systems\n• Plan for collaborative features and social learning elements\n\n**STEP 3: Quality Excellence Framework**\n• Establish enterprise-grade quality standards and measurement\n• Design comprehensive user testing and feedback integration\n• Plan continuous optimization based on learning effectiveness data\n• Create scalable maintenance and update protocols\n\nGoal: Strategic foundation for learning materials that optimize effectiveness through sophisticated design.",
       "agentRole": "You are a learning systems architect with expertise in enterprise-grade materials design. Help users create sophisticated strategies that maximize learning effectiveness through advanced features and optimization.",
       "guidance": [
         "Apply advanced instructional design and learning optimization principles",
@@ -185,4 +192,4 @@
       "hasValidation": true
     }
   ]
-}
+}

package/workflows/presentation-creation.json

@@ -3,6 +3,13 @@
   "name": "Presentation Creation Workflow",
   "version": "1.0.0",
   "description": "Use this to create a compelling presentation. Covers audience analysis, content strategy, slide structure, and delivery preparation. Output works with any presentation tool.",
+  "about": "## Presentation Creation Workflow\n\nUse this to build a compelling, audience-specific presentation from scratch -- whether for a conference talk, internal strategy review, client pitch, or team demo. The workflow grounds every content decision in a concrete audience profile, so the result is written for real people in a real context rather than a generic slide deck.\n\n### What it produces\n\n- An audience profile and context map.\n- A content strategy with a single core message, supporting arguments, and a call-to-action.\n- A numbered slide outline with content types and timing estimates.\n- Full slide content and speaker notes for every slide.\n- Backup slides for anticipated deep-dive questions.\n- A delivery preparation plan including practice schedule, Q&A prep, and technical checklist.\n\n### When to use it\n\n- You are building a presentation that needs to persuade, inform, or motivate a specific audience.\n- You want structured help moving from \"I have a topic\" to \"I have a complete, rehearsal-ready deck.\"\n- The presentation has real stakes -- a client pitch, a leadership review, a conference talk.\n\n### When NOT to use it\n\n- You just need to slap a few bullets onto slides quickly -- this workflow is for presentations where quality matters.\n\n### How to get good results\n\n- The more specific you are about your audience, the better the content strategy will be. \"Engineering managers at a Series B fintech\" beats \"technical people.\"\n- The workflow has two confirmation gates: after the audience profile and after the slide outline. Use these to redirect before content gets written.\n- Bring source materials, data, and any existing slides you want to incorporate -- the content development step can ingest these.",
+  "examples": [
+    "Create a 20-minute conference talk on migrating a monolith to microservices for a senior engineering audience",
+    "Build a 10-slide investor pitch deck for our Series A fundraise",
+    "Prepare a quarterly product roadmap presentation for internal stakeholders",
+    "Create a client workshop deck introducing our platform migration methodology"
+  ],
   "preconditions": [
     "You have a clear presentation topic or objective.",
     "You know roughly who your audience is.",
@@ -56,9 +63,9 @@
       "promptBlocks": {
         "goal": "Define the core message and argument structure that will guide every slide and talking point. Using your audience profile from the previous step, build a content strategy grounded in their specific needs.",
         "constraints": [
-          "Start with one core message \u2014 a single, memorable sentence. Everything else should support it.",
+          "Start with one core message — a single, memorable sentence. Everything else should support it.",
           "Supporting arguments should directly address the audience motivations and pain points you identified.",
-          "The narrative arc should feel natural for this audience in this context \u2014 not a generic template unless it actually fits."
+          "The narrative arc should feel natural for this audience in this context — not a generic template unless it actually fits."
         ],
         "procedure": [
           "State your core message: one clear, memorable sentence that captures the single most important thing you want the audience to take away.",
@@ -85,7 +92,7 @@
         "constraints": [
           "One key idea per slide. If a slide is trying to say two things, split it.",
           "Plan for pacing: balance information-dense slides with breathing room and interaction moments.",
-          "Think about how the slides will work if someone reads them later without you \u2014 titles should be informative, not just labels."
+          "Think about how the slides will work if someone reads them later without you — titles should be informative, not just labels."
         ],
         "procedure": [
           "Opening (1-3 slides): attention-grabbing hook, context framing, and agenda or roadmap.",
@@ -109,7 +116,7 @@
       "id": "content-development",
       "title": "Content Development",
       "promptBlocks": {
-        "goal": "Write the actual presentation content \u2014 slide text and speaker notes \u2014 following the approved outline. Every piece of content should be grounded in your audience profile and core message.",
+        "goal": "Write the actual presentation content — slide text and speaker notes — following the approved outline. Every piece of content should be grounded in your audience profile and core message.",
         "constraints": [
           "Write for the ear, not the eye. Slide text should be sparse; speaker notes should sound natural when spoken aloud.",
           "Use active voice and concrete language. Replace abstractions with specific examples.",
@@ -162,4 +169,4 @@
       "requireConfirmation": false
     }
   ]
-}
+}

package/workflows/production-readiness-audit.json

@@ -3,6 +3,13 @@
   "name": "Production Readiness Audit (v2 \u2022 Evidence-Driven Readiness Review)",
   "version": "0.1.0",
   "description": "Use this to audit a codebase scope for production readiness. Checks debugging correctness, runtime operability, artifact realism, technical debt, and anything that would prevent honest production deployment.",
+  "about": "## Production Readiness Audit\n\nThis workflow performs a structured, evidence-driven audit to answer one question honestly: is this code actually ready for production? It goes beyond style and lint -- it looks for debugging correctness, runtime operability under real conditions, artifact realism (stale code, fake completeness, placeholder behavior), maintainability debt, test and observability gaps, and security or performance risks.\n\n**What it does:**\nThe workflow bounds the audit scope, states a readiness hypothesis, freezes a neutral fact packet, then runs parallel reviewer families -- each specializing in a different readiness dimension. It reconciles contradictions through an evidence loop and produces a final verdict: `ready`, `ready_with_conditions`, `not_ready`, or `inconclusive`.\n\n**When to use it:**\n- Before shipping a new service, feature, or major refactor to production\n- When a codebase has been under rapid development and you want an honest readiness check before a launch deadline\n- When onboarding to a codebase and wanting a structured assessment of its production posture\n- When a post-incident review surfaces questions about whether the system was truly ready\n\n**What it produces:**\nA verdict with a confidence band, a prioritized list of blocker-grade and major findings, debugging leads, runtime and operational risk callouts, artifact-realism concerns (misleading completeness, stale docs, dead paths), a coverage ledger by audit domain, and a remediation order with specific follow-up recommendations.\n\n**How to get good results:**\nProvide a clear scope -- a service name, a module path, or a feature boundary. The narrower and more concrete the scope, the sharper the findings. If \"production-ready\" has a specific meaning for your team (e.g. SLA requirements, specific deployment constraints), mention it. The workflow will try to infer the production bar from repo patterns and context, but explicit criteria improve accuracy.",
+  "examples": [
+    "Audit the notifications service for production readiness before the Q3 launch",
+    "Check if the new checkout flow feature is ready to ship -- focus on runtime operability and error handling",
+    "Production readiness review of the auth module after the recent login refactor",
+    "Assess whether the data ingestion pipeline is ready for production given the volume targets in the launch brief"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"

package/workflows/relocation-workflow-us.json

@@ -1,8 +1,15 @@
 {
   "id": "relocation-workflow-us",
-  "name": "US Relocation Decision Workflow (Evidence-Driven \u2022 AreaSpec \u2022 Ranked Dossier)",
+  "name": "US Relocation Decision Workflow (Evidence-Driven • AreaSpec • Ranked Dossier)",
   "version": "1.0.0",
   "description": "Use this to evaluate US cities or regions for a potential relocation. Discovers your preferences, generates candidate areas, screens them, and produces a ranked dossier with evidence.",
+  "about": "## US Relocation Decision Workflow\n\nUse this to evaluate US cities and regions for a potential move. The workflow takes a structured, evidence-driven approach: it starts by calibrating your preferences and dealbreakers, generates a broad diverse pool of candidate areas (including non-obvious ones), screens them systematically, and produces a ranked dossier you can actually act on.\n\n### What it produces\n\n- A `RELOCATION_DOSSIER.md` with your full preference model, screening results, and comparison matrix.\n- Individual per-candidate profiles at `relocation-profiles/<slug>.md` covering housing, cost of living, taxes, safety, climate risk, schools, healthcare, commute, and any other modules you activate.\n- A scored ranking with explainable reasoning and an explicit disclosure of any data gaps.\n- A next-steps plan: visit recommendations, open questions per candidate, and pivot triggers.\n\n### When to use it\n\n- You are seriously considering a US relocation and want a rigorous, evidence-backed shortlist.\n- You want to surface non-obvious candidates you wouldn't have considered on your own.\n- You've been anchoring on a handful of cities and want a structured process to either validate or challenge that.\n\n### How to get good results\n\n- Be honest about dealbreakers upfront -- the workflow builds these into screening and filters candidates early.\n- The MaxDiff weight calibration exercise (offered in Phase 1) is worth doing if you're unsure how to weight competing priorities. It takes 5-10 minutes and produces more reliable weights than guessing.\n- The calibration deck in Phase 1 shows you lifestyle archetypes and asks for reactions -- engage with this seriously. Surprises in your reactions are valuable signal.\n- The workflow activates only the research modules you need. Keep it focused on what actually matters to your household.",
+  "examples": [
+    "Help me find the best US city to relocate my family, prioritizing top schools, low cost of living, and outdoor access",
+    "Evaluate mid-size metros in the Southeast as alternatives to Atlanta for a remote worker with a $400k housing budget",
+    "Find the best US cities for a couple relocating from San Francisco who need to stay within a 2-hour flight of NYC",
+    "Compare Denver, Austin, and Raleigh as relocation options and surface 5 non-obvious alternatives I haven't considered"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
@@ -20,14 +27,14 @@
   ],
   "metaGuidance": [
     "DEFAULT BEHAVIOR: self-execute with tools. Ask the user only for true preferences, real confirmations, and any external context you cannot find yourself.",
-    "V2 DURABILITY: use output.notesMarkdown and explicit context variables as the durable record. RELOCATION_DOSSIER.md and profile docs are human-facing artifacts \u2014 they are NOT required workflow memory and are never read back for routing.",
+    "V2 DURABILITY: use output.notesMarkdown and explicit context variables as the durable record. RELOCATION_DOSSIER.md and profile docs are human-facing artifacts — they are NOT required workflow memory and are never read back for routing.",
     "ANTI-ANCHORING: generate a broad pool first; screen second; deep-dive only the shortlist. Do not deep-dive a single favorite area early.",
     "AREA BOUNDARIES: every candidate must have an AreaSpec before entering the pool. Use areaId = <candidateType>-<slug(displayName)>-<sortedStateCodes> (e.g. metro-raleigh-durham-nc). Never switch a candidate's boundary mid-run without logging it.",
     "CLAIMS LEDGER: every key claim about a location must include source (URL or citation), retrievedAt (date), and confidenceGrade (High/Medium/Low). If a claim cannot be sourced, grade it Low.",
     "MISSING DATA: when a data point is unavailable, record it as Unknown and apply the chosen missingDataPolicy consistently. Never silently assume a value for an Unknown.",
     "ARTIFACTS: try to write files (RELOCATION_DOSSIER.md, relocation-profiles/<slug>.md). If file writing is unavailable, paste full canonical content in chat and treat that as the record.",
     "MODULES: activate only sections relevant to activeModules. Do not include placeholder sections for inactive modules.",
-    "SCREENING CAPS: first-pass screening must stay fast \u2014 dealbreakers plus top weighted criteria only, strict claim and time caps. Deep research belongs in Phase 6 deep dives.",
+    "SCREENING CAPS: first-pass screening must stay fast — dealbreakers plus top weighted criteria only, strict claim and time caps. Deep research belongs in Phase 6 deep dives.",
     "NON-OBVIOUS CANDIDATES: non-obvious = not in userTopOfMind AND not in top-100 US metros. If you cannot map a candidate to the top-100 list deterministically, mark obviousness Unknown and do not count it toward non-obvious requirements."
   ],
   "steps": [
@@ -37,18 +44,18 @@
       "promptBlocks": {
         "goal": "Establish the scope and structure for this relocation search, then discover calibrated preferences and a stable weight model before any research begins.",
         "constraints": [
-          "Do not start researching candidates yet \u2014 preferences and boundary rules must be locked first.",
+          "Do not start researching candidates yet — preferences and boundary rules must be locked first.",
           "Activate only modules the user actually needs; do not load everything by default.",
           "If the user is unsure about weights, offer the MaxDiff helper before finalizing."
         ],
         "procedure": [
-          "Step 1 \u2014 Confirm scope and initialize artifacts. Confirm this is a US-only v1 relocation search. Ask for userTopOfMind (0-10 areas the user already has in mind; empty is fine). Initialize RELOCATION_DOSSIER.md with sections: User Context & Modules, Boundary & Definitions, Preferences (Draft), Constraints & Dealbreakers, Missing Data Policy, Sources Strategy, Candidate Pool, Screened Candidates, Screening Claims Ledger, Baseline Flags (Not Scored), Red Flag Gate Decisions (append-only), Shortlist, Profiles Index, Comparison & Ranking, Decision Log (append-only). Create the relocation-profiles/ directory.",
-          "Step 2 \u2014 Capture user context. Ask about and record: timelineToMove (0-3 months / 3-12 months / 12+ months), householdProfile (single / couple / family with kids / multi-generational), housingPlan (rent/buy/either and budget range), workConstraints (remote/hybrid/onsite; time zones allowed), geoExclusions (states or regions to exclude).",
-          "Step 3 \u2014 Select modules. Present the module list and activate all that apply: kids/schools, commute, transit, climate-risk, healthcare-access, career-job-market, outdoors, nightlife-arts, safety, taxes, diversity-community, disability-accessibility, amenities-errands, air-quality, noise, internet-infra. Record as activeModules.",
-          "Step 4 \u2014 Lock boundary rules. Set candidateType (default: metro; options: city, county, custom). Record the AreaSpec model: areaId = <candidateType>-<slug(displayName)>-<sortedStateCodes>. For metro candidates, record the definition source and treat the full metro area as the boundary (not just the city). For custom areas (v1), use radius mode: center (place + stateCode) + radiusMiles. Update RELOCATION_DOSSIER.md Boundary & Definitions section.",
-          "Step 5 \u2014 Elicit preferences. Ask about: hard constraints (must-have geography, climate, budget, job, family, health), anti-goals (explicit non-goals), dealbreakers. Draft 6-10 weighted criteria across active modules; weights must sum to 100. If the user is unsure, start with equal-weight draft and offer MaxDiff.",
-          "Step 6 \u2014 Optional MaxDiff weight derivation. Ask: 'Do you want help deriving weights using Most/Least comparisons?' If yes: build deterministic rotation sets (N<=7: 3 sets of 4; N>=8: 4 sets of 5). For each set ask which criterion is MOST important and which is LEAST. Derive weights: raw[c] = mostCount[c] - leastCount[c]; shifted[c] = raw[c] - min(raw) + 1; weight[c] = round(shifted[c] / sum(shifted) * 100); adjust largest weight so sum = exactly 100. Allow one small tweak pass (up to 2 weights adjusted, then re-normalize).",
-          "Step 7 \u2014 Calibration deck. Generate 8-12 diverse US location archetypes (dense transit metro, college town, mountain small city, coastal mid-size, sunbelt suburb, rust-belt revival city, DC-adjacent, etc.). For each: 2-3 sentences on lifestyle and tradeoffs, who it fits, who it frustrates. Ask the user to rank top 3 and bottom 3 and name 1-2 surprises. Update weights and constraints if calibration reveals new signal. Record derivedSignals (densityLeaning, climateLeaning, regionLeaning).",
+          "Step 1 — Confirm scope and initialize artifacts. Confirm this is a US-only v1 relocation search. Ask for userTopOfMind (0-10 areas the user already has in mind; empty is fine). Initialize RELOCATION_DOSSIER.md with sections: User Context & Modules, Boundary & Definitions, Preferences (Draft), Constraints & Dealbreakers, Missing Data Policy, Sources Strategy, Candidate Pool, Screened Candidates, Screening Claims Ledger, Baseline Flags (Not Scored), Red Flag Gate Decisions (append-only), Shortlist, Profiles Index, Comparison & Ranking, Decision Log (append-only). Create the relocation-profiles/ directory.",
+          "Step 2 — Capture user context. Ask about and record: timelineToMove (0-3 months / 3-12 months / 12+ months), householdProfile (single / couple / family with kids / multi-generational), housingPlan (rent/buy/either and budget range), workConstraints (remote/hybrid/onsite; time zones allowed), geoExclusions (states or regions to exclude).",
+          "Step 3 — Select modules. Present the module list and activate all that apply: kids/schools, commute, transit, climate-risk, healthcare-access, career-job-market, outdoors, nightlife-arts, safety, taxes, diversity-community, disability-accessibility, amenities-errands, air-quality, noise, internet-infra. Record as activeModules.",
+          "Step 4 — Lock boundary rules. Set candidateType (default: metro; options: city, county, custom). Record the AreaSpec model: areaId = <candidateType>-<slug(displayName)>-<sortedStateCodes>. For metro candidates, record the definition source and treat the full metro area as the boundary (not just the city). For custom areas (v1), use radius mode: center (place + stateCode) + radiusMiles. Update RELOCATION_DOSSIER.md Boundary & Definitions section.",
+          "Step 5 — Elicit preferences. Ask about: hard constraints (must-have geography, climate, budget, job, family, health), anti-goals (explicit non-goals), dealbreakers. Draft 6-10 weighted criteria across active modules; weights must sum to 100. If the user is unsure, start with equal-weight draft and offer MaxDiff.",
+          "Step 6 — Optional MaxDiff weight derivation. Ask: 'Do you want help deriving weights using Most/Least comparisons?' If yes: build deterministic rotation sets (N<=7: 3 sets of 4; N>=8: 4 sets of 5). For each set ask which criterion is MOST important and which is LEAST. Derive weights: raw[c] = mostCount[c] - leastCount[c]; shifted[c] = raw[c] - min(raw) + 1; weight[c] = round(shifted[c] / sum(shifted) * 100); adjust largest weight so sum = exactly 100. Allow one small tweak pass (up to 2 weights adjusted, then re-normalize).",
+          "Step 7 — Calibration deck. Generate 8-12 diverse US location archetypes (dense transit metro, college town, mountain small city, coastal mid-size, sunbelt suburb, rust-belt revival city, DC-adjacent, etc.). For each: 2-3 sentences on lifestyle and tradeoffs, who it fits, who it frustrates. Ask the user to rank top 3 and bottom 3 and name 1-2 surprises. Update weights and constraints if calibration reveals new signal. Record derivedSignals (densityLeaning, climateLeaning, regionLeaning).",
           "Capture these context variables: activeModules, candidateType, userTopOfMind, timelineToMove, householdProfile, housingPlan, workConstraints, geoExclusions, dealbreakers, weights (array of {criterion, weight}), weightsCount, derivedSignals."
         ],
         "verify": [
@@ -67,17 +74,17 @@
       "promptBlocks": {
         "goal": "Lock the decision mechanics and gate parameters before any candidate research begins. These policies govern how ambiguity, missing data, and diversity requirements are handled throughout the workflow.",
         "constraints": [
-          "Every policy must be explicit \u2014 no implicit defaults allowed past this gate.",
+          "Every policy must be explicit — no implicit defaults allowed past this gate.",
           "The user must confirm these settings before Phase 3 begins."
         ],
         "procedure": [
-          "Step 1 \u2014 Missing data policy. Ask the user to choose one: (a) neutral \u2014 Unknown scores 0.5; (b) penalize \u2014 Unknown scores 0.25; (c) followup_required \u2014 Unknown scores 0.5 AND candidates with Unknown on any criterion with weight >= 15 are ineligible for the top 3. Record as missingDataPolicy.",
-          "Step 2 \u2014 Intake completeness check. Confirm you have enough context to set dealbreakers and weights. If not, note missingInputs and resolve before proceeding.",
-          "Step 3 \u2014 Anti-anchoring gate parameters. Propose defaults and ask the user to confirm or adjust: minCandidatePool (default 20), minNonObviousCandidates (default 6), minCoverageRegions (default 3), minCoverageClimateBands (default 2).",
-          "Step 4 \u2014 Shortlist range. Propose defaults and ask the user to confirm or adjust: shortlistMin (default 8), shortlistMax (default 12).",
-          "Step 5 \u2014 Screening caps. Propose defaults and ask the user to confirm or adjust: screeningTopCriteriaCount (default 3 \u2014 screen dealbreakers + top N weighted criteria only), screeningMaxClaimsPerCandidate (default 3), screeningTimeboxMinutesPerCandidate (default 5), screeningBatchSize (default 10).",
-          "Step 6 \u2014 Discovery caps. Propose defaults and ask the user to confirm or adjust: perSourceCandidateCap (default 8 \u2014 cap per curated-list source to avoid editorial bias).",
-          "Step 7 \u2014 Baseline flags caps. Propose defaults and ask the user to confirm or adjust: baselineMaxFlagsPerCandidate (default 2), baselineMaxSourcesPerFlag (default 1), baselineTimeboxMinutesPerCandidate (default 2).",
+          "Step 1 — Missing data policy. Ask the user to choose one: (a) neutral — Unknown scores 0.5; (b) penalize — Unknown scores 0.25; (c) followup_required — Unknown scores 0.5 AND candidates with Unknown on any criterion with weight >= 15 are ineligible for the top 3. Record as missingDataPolicy.",
+          "Step 2 — Intake completeness check. Confirm you have enough context to set dealbreakers and weights. If not, note missingInputs and resolve before proceeding.",
+          "Step 3 — Anti-anchoring gate parameters. Propose defaults and ask the user to confirm or adjust: minCandidatePool (default 20), minNonObviousCandidates (default 6), minCoverageRegions (default 3), minCoverageClimateBands (default 2).",
+          "Step 4 — Shortlist range. Propose defaults and ask the user to confirm or adjust: shortlistMin (default 8), shortlistMax (default 12).",
+          "Step 5 — Screening caps. Propose defaults and ask the user to confirm or adjust: screeningTopCriteriaCount (default 3 — screen dealbreakers + top N weighted criteria only), screeningMaxClaimsPerCandidate (default 3), screeningTimeboxMinutesPerCandidate (default 5), screeningBatchSize (default 10).",
+          "Step 6 — Discovery caps. Propose defaults and ask the user to confirm or adjust: perSourceCandidateCap (default 8 — cap per curated-list source to avoid editorial bias).",
+          "Step 7 — Baseline flags caps. Propose defaults and ask the user to confirm or adjust: baselineMaxFlagsPerCandidate (default 2), baselineMaxSourcesPerFlag (default 1), baselineTimeboxMinutesPerCandidate (default 2).",
           "Update RELOCATION_DOSSIER.md with all policies and caps. Capture all values as context variables: missingDataPolicy, minCandidatePool, minNonObviousCandidates, minCoverageRegions, minCoverageClimateBands, shortlistMin, shortlistMax, screeningTopCriteriaCount, screeningMaxClaimsPerCandidate, screeningTimeboxMinutesPerCandidate, screeningBatchSize, perSourceCandidateCap, baselineMaxFlagsPerCandidate, baselineMaxSourcesPerFlag, baselineTimeboxMinutesPerCandidate."
         ],
         "verify": [
@@ -99,10 +106,10 @@
           "Do not proceed to screening until the anti-anchoring gate passes."
         ],
         "procedure": [
-          "Step 1 \u2014 Sources strategy. Before generating candidates, document the sources strategy in RELOCATION_DOSSIER.md: Housing (Zillow + alternative), Taxes (state revenue sites), Climate normals (NOAA), Climate risk (FEMA flood maps), Employment (BLS / state labor stats), Transit/commute (local agencies), Air quality (AirNow/EPA), Noise (airport contour maps), Internet (FCC broadband map). Include only sources for active modules. Use this sources strategy as your research guide throughout candidate generation \u2014 generate the pool from actual data, not from memory alone.",
-          "Step 2 \u2014 Generate candidates. Use the weight model and dealbreakers as the filter. For each candidate: assign a stable areaId, record the full AreaSpec (candidateType, displayName, stateCodes, and boundary definition), record why included, tag with candidateFacets (region, climateBand, sizeTier, taxRegime, airportAccess, outdoorsBiome as applicable). Fill coverage gaps deliberately \u2014 include a mix of obvious and non-obvious candidates. Include at least minCandidatePool candidates total.",
-          "Step 3 \u2014 Anti-anchoring gate. Check: candidatePoolCount >= minCandidatePool, qualifyingNonObviousCandidateCount >= minNonObviousCandidates, coverageRegionsCount >= minCoverageRegions, coverageClimateBandsCount >= minCoverageClimateBands. A 'qualifying non-obvious' candidate is non-obvious AND plausibly passes dealbreakers. Record the top-100 list source used for non-obvious classification. If the gate fails, expand the pool by filling coverage gaps (prefer non-obvious candidates). Repeat until the gate passes.",
-          "Step 4 \u2014 Build screening batches. Divide candidatePool into batches of screeningBatchSize, preserving order. Each batch: { batchId, startIndex, endIndexExclusive, candidates }. Record screeningBatches and screeningBatchesCount.",
+          "Step 1 — Sources strategy. Before generating candidates, document the sources strategy in RELOCATION_DOSSIER.md: Housing (Zillow + alternative), Taxes (state revenue sites), Climate normals (NOAA), Climate risk (FEMA flood maps), Employment (BLS / state labor stats), Transit/commute (local agencies), Air quality (AirNow/EPA), Noise (airport contour maps), Internet (FCC broadband map). Include only sources for active modules. Use this sources strategy as your research guide throughout candidate generation — generate the pool from actual data, not from memory alone.",
+          "Step 2 — Generate candidates. Use the weight model and dealbreakers as the filter. For each candidate: assign a stable areaId, record the full AreaSpec (candidateType, displayName, stateCodes, and boundary definition), record why included, tag with candidateFacets (region, climateBand, sizeTier, taxRegime, airportAccess, outdoorsBiome as applicable). Fill coverage gaps deliberately — include a mix of obvious and non-obvious candidates. Include at least minCandidatePool candidates total.",
+          "Step 3 — Anti-anchoring gate. Check: candidatePoolCount >= minCandidatePool, qualifyingNonObviousCandidateCount >= minNonObviousCandidates, coverageRegionsCount >= minCoverageRegions, coverageClimateBandsCount >= minCoverageClimateBands. A 'qualifying non-obvious' candidate is non-obvious AND plausibly passes dealbreakers. Record the top-100 list source used for non-obvious classification. If the gate fails, expand the pool by filling coverage gaps (prefer non-obvious candidates). Repeat until the gate passes.",
+          "Step 4 — Build screening batches. Divide candidatePool into batches of screeningBatchSize, preserving order. Each batch: { batchId, startIndex, endIndexExclusive, candidates }. Record screeningBatches and screeningBatchesCount.",
           "Update RELOCATION_DOSSIER.md: Candidate Pool table (name, candidateType, region, why included, early risks/unknowns). Capture context variables: candidatePool, candidatePoolCount, nonObviousCandidateCount, qualifyingNonObviousCandidateCount, coverageRegionsCount, coverageClimateBandsCount, screeningBatches, screeningBatchesCount, discoverySourcesUsed, nonObviousDefinitionUsed."
         ],
         "verify": [
@@ -136,7 +143,7 @@
     {
       "id": "phase-4-baseline-flags",
       "title": "Phase 4b: Baseline Due Diligence (Not Scored)",
-      "prompt": "Run a lightweight baseline pass on all Pass or Maybe candidates from screenResults.\n\nScope \u2014 check only:\n- Climate risk (high-level: flood zone, wildfire, extreme heat)\n- Safety and crime (high-level: neighborhood-level variance)\n- Schools and healthcare access \u2014 only if kids/schools or healthcare-access modules are active\n\nCaps (apply strictly):\n- At most baselineMaxFlagsPerCandidate flags per candidate\n- At most baselineMaxSourcesPerFlag sources per flag\n- At most baselineTimeboxMinutesPerCandidate minutes per candidate\n\nFor each Pass/Maybe candidate, produce 0 to baselineMaxFlagsPerCandidate baseline flags. Each flag: category (climate/safety/schools/healthcare/policy/other), severity (yellow/orange/red), one-sentence summary, source, retrievedAt, confidenceGrade. A red flag has severity = red.\n\nDo NOT compute or modify any scores here. Do NOT silently turn flags into dealbreakers or weights. If evidence is unclear, record Unknown.\n\nUpdate RELOCATION_DOSSIER.md: add Baseline Flags (Not Scored) section with per-candidate table.\n\nCapture context variables: baselineFlags ({ [candidateKey]: { flags: array, unknowns: string[] } }), redFlagCandidates (string[]), redFlagCount (number).",
+      "prompt": "Run a lightweight baseline pass on all Pass or Maybe candidates from screenResults.\n\nScope — check only:\n- Climate risk (high-level: flood zone, wildfire, extreme heat)\n- Safety and crime (high-level: neighborhood-level variance)\n- Schools and healthcare access — only if kids/schools or healthcare-access modules are active\n\nCaps (apply strictly):\n- At most baselineMaxFlagsPerCandidate flags per candidate\n- At most baselineMaxSourcesPerFlag sources per flag\n- At most baselineTimeboxMinutesPerCandidate minutes per candidate\n\nFor each Pass/Maybe candidate, produce 0 to baselineMaxFlagsPerCandidate baseline flags. Each flag: category (climate/safety/schools/healthcare/policy/other), severity (yellow/orange/red), one-sentence summary, source, retrievedAt, confidenceGrade. A red flag has severity = red.\n\nDo NOT compute or modify any scores here. Do NOT silently turn flags into dealbreakers or weights. If evidence is unclear, record Unknown.\n\nUpdate RELOCATION_DOSSIER.md: add Baseline Flags (Not Scored) section with per-candidate table.\n\nCapture context variables: baselineFlags ({ [candidateKey]: { flags: array, unknowns: string[] } }), redFlagCandidates (string[]), redFlagCount (number).",
       "requireConfirmation": false
     },
     {
@@ -157,7 +164,7 @@
             "var": "redFlagCount",
             "gt": 0
           },
-          "text": "Red flags were found. Summarize each: candidate name, category, one-line summary, source. Ask the user to choose exactly one action: (a) promote_to_dealbreakers \u2014 update the `dealbreakers` context variable AND the RELOCATION_DOSSIER.md Constraints section with the new/updated dealbreakers, then re-check screenResults for affected candidates; (b) add_weighted_criterion \u2014 ask the user how to weight it and which existing weights decrease so the `weights` array still sums to 100; (c) fyi \u2014 record the decision and move on. Record redFlagDecision and redFlagDecisionNotes. Append to RELOCATION_DOSSIER.md Red Flag Gate Decisions (append-only)."
+          "text": "Red flags were found. Summarize each: candidate name, category, one-line summary, source. Ask the user to choose exactly one action: (a) promote_to_dealbreakers — update the `dealbreakers` context variable AND the RELOCATION_DOSSIER.md Constraints section with the new/updated dealbreakers, then re-check screenResults for affected candidates; (b) add_weighted_criterion — ask the user how to weight it and which existing weights decrease so the `weights` array still sums to 100; (c) fyi — record the decision and move on. Record redFlagDecision and redFlagDecisionNotes. Append to RELOCATION_DOSSIER.md Red Flag Gate Decisions (append-only)."
         }
       ],
       "prompt": "Handle baseline red flags before selecting the shortlist.",
@@ -216,16 +223,16 @@
         "goal": "Produce the final comparison matrix, explainable ranking, and a practical next-steps plan.",
         "constraints": [
           "The score formula must be applied consistently to every candidate.",
-          "Unknowns must be disclosed in the ranking narrative \u2014 never presented as if they were evidence-backed.",
+          "Unknowns must be disclosed in the ranking narrative — never presented as if they were evidence-backed.",
           "Baseline flags (not scored) are shown separately and do not change totalScore.",
           "One re-weight pass is allowed if the user says the ranking direction is wrong."
         ],
         "procedure": [
-          "Step 1 \u2014 Comparison matrix. Build a table in RELOCATION_DOSSIER.md: rows = shortlisted candidates, columns = weighted criteria. Mark Unknowns explicitly. Add a separate appendix table for baseline flags (Not Scored): red/orange flags per candidate.",
-          "Step 2 \u2014 Score each candidate. For each criterion, assign a normalized subscore: Strong fit = 1.0, Mixed/conditional = 0.5, Weak fit = 0.0. For Unknowns: neutral policy \u2192 0.5; penalize policy \u2192 0.25; followup_required policy \u2192 0.5 and flag candidate ineligible for top 3 if Unknown on any criterion with weight >= 15. Compute totalScore = sum(weight_i * subscore_i) for each candidate.",
-          "Step 3 \u2014 Ranking narrative. For each candidate write: 'Ranks #k because it wins on X and Y, loses on Z. Biggest tradeoff: ...' Make sure all Unknown subscores are called out explicitly in the narrative.",
-          "Step 4 \u2014 Re-weight gate. Ask the user: 'Does this ranking direction feel correct?' If not, allow one re-weight (user adjusts any number of criteria weights; must still sum to 100; re-run scoring). Record reweightUsed (true/false). Update Decision Log with any weight changes and rationale.",
-          "Step 5 \u2014 Next steps. Produce: suggested visit plan for top 2-4 candidates (what to validate in person), open questions per candidate (from Unknowns sections), pivot triggers (what evidence would change the ranking), optional neighborhood-level follow-ups if enough evidence exists. Update RELOCATION_DOSSIER.md with Next Steps and Pivot Triggers.",
+          "Step 1 — Comparison matrix. Build a table in RELOCATION_DOSSIER.md: rows = shortlisted candidates, columns = weighted criteria. Mark Unknowns explicitly. Add a separate appendix table for baseline flags (Not Scored): red/orange flags per candidate.",
+          "Step 2 — Score each candidate. For each criterion, assign a normalized subscore: Strong fit = 1.0, Mixed/conditional = 0.5, Weak fit = 0.0. For Unknowns: neutral policy → 0.5; penalize policy → 0.25; followup_required policy → 0.5 and flag candidate ineligible for top 3 if Unknown on any criterion with weight >= 15. Compute totalScore = sum(weight_i * subscore_i) for each candidate.",
+          "Step 3 — Ranking narrative. For each candidate write: 'Ranks #k because it wins on X and Y, loses on Z. Biggest tradeoff: ...' Make sure all Unknown subscores are called out explicitly in the narrative.",
+          "Step 4 — Re-weight gate. Ask the user: 'Does this ranking direction feel correct?' If not, allow one re-weight (user adjusts any number of criteria weights; must still sum to 100; re-run scoring). Record reweightUsed (true/false). Update Decision Log with any weight changes and rationale.",
+          "Step 5 — Next steps. Produce: suggested visit plan for top 2-4 candidates (what to validate in person), open questions per candidate (from Unknowns sections), pivot triggers (what evidence would change the ranking), optional neighborhood-level follow-ups if enough evidence exists. Update RELOCATION_DOSSIER.md with Next Steps and Pivot Triggers.",
           "Capture context variables: ranking ([{name, totalScore, rank}]), unknownsImpactSummary, reweightUsed."
         ],
         "verify": [
@@ -238,4 +245,4 @@
       "requireConfirmation": true
     }
   ]
-}
+}