feat: add discovery sessions (DS-xxx)

docs/guides/personas.md

@@ -16,11 +16,11 @@ The Product Owner focuses on product vision, stakeholder needs, backlog prioriti
 - Make decisions about scope, priority, and trade-offs
 - Accept or reject work results based on acceptance criteria
 
-**Document types:** decisions, questions, actions, features, use-cases
+**Document types:** decisions, questions, actions, features, use-cases, discoveries
 
 **Contribution types:** stakeholder-feedback, acceptance-result, priority-change, market-insight
 
-**When to use:** When you need to define what to build and why — prioritizing features, making scope decisions, capturing stakeholder requirements, or evaluating delivered work against acceptance criteria.
+**When to use:** When you need to define what to build and why — prioritizing features, making scope decisions, capturing stakeholder requirements, conducting discovery sessions with stakeholders, or evaluating delivered work against acceptance criteria.
 
 ```bash
 marvin chat --as po
@@ -40,7 +40,7 @@ The Delivery Manager focuses on project delivery, risk management, team coordina
 - Ensure governance processes are followed (decisions logged, actions tracked)
 - Facilitate meetings and ensure outcomes are captured
 
-**Document types:** actions, decisions, meetings, questions, features, epics, tasks, sprints
+**Document types:** actions, decisions, meetings, questions, features, epics, tasks, sprints, discoveries
 
 **Contribution types:** risk-finding, blocker-report, dependency-update, status-assessment
 
@@ -66,7 +66,7 @@ The Technical Lead focuses on technical architecture, code quality, technical de
 - Guide the team on best practices and patterns
 - Evaluate technical risks and propose mitigations
 
-**Document types:** decisions, actions, questions, epics, tasks, sprints
+**Document types:** decisions, actions, questions, epics, tasks, sprints, discoveries
 
 **Contribution types:** action-result, spike-findings, technical-assessment, architecture-review
 

docs/reference/document-types.md

@@ -45,6 +45,7 @@ to specify exactly the fields they need...
 | meeting | M | meetings/ | scheduled, completed, cancelled |
 | report | R | reports/ | — |
 | contribution | C | contributions/ | — |
+| discovery | DS | discoveries/ | draft, in-review, needs-input, accepted, parked |
 
 ## SAP AEM types (sap-aem methodology only)
 
@@ -80,4 +81,4 @@ These fields are defined on `DocumentFrontmatter` in `src/storage/types.ts`. Add
 | `dueDate` | string | no | ISO date |
 | `source` | string | no | Source artifact ID |
 
-Additional fields vary by type (e.g., sprints have `startDate`, `endDate`, `goal`, `linkedEpics`; features have `linkedEpics`; tasks have `linkedEpic`, `complexity`, `estimatedPoints`).
+Additional fields vary by type (e.g., sprints have `startDate`, `endDate`, `goal`, `linkedEpics`; features have `linkedEpics`; tasks have `linkedEpic`, `complexity`, `estimatedPoints`; discoveries have `stakeholder`, `session`, `parent`).

src/core/statuses.ts

@@ -16,3 +16,10 @@ export const ACTION_STATUSES = ["open", "in-progress", "done"] as const;
 export const MEETING_STATUSES = ["scheduled", "completed"] as const;
 export const DECISION_STATUSES = ["open", "decided", "superseded"] as const;
 export const QUESTION_STATUSES = ["open", "answered"] as const;
+export const DISCOVERY_STATUSES = [
+  "draft",
+  "in-review",
+  "needs-input",
+  "accepted",
+  "parked",
+] as const;

src/doctor/health/checks/index.ts

@@ -1,6 +1,7 @@
 import type { HealthCheck } from "../types.js";
 import { emptyProjectCheck } from "./empty-project.js";
 import { unprocessedSourcesCheck } from "./unprocessed-sources.js";
+import { noDiscoveriesCheck } from "./no-discoveries.js";
 import { noSprintsCheck } from "./no-sprints.js";
 import { unassignedActionsCheck } from "./unassigned-actions.js";
 import { noJiraProjectCheck } from "./no-jira-project.js";
@@ -10,6 +11,7 @@ import { phaseReadinessCheck } from "./phase-readiness.js";
 export const allHealthChecks: HealthCheck[] = [
   emptyProjectCheck,
   unprocessedSourcesCheck,
+  noDiscoveriesCheck,
   noSprintsCheck,
   unassignedActionsCheck,
   noJiraProjectCheck,

src/doctor/health/checks/no-discoveries.ts

@@ -0,0 +1,32 @@
+import type { HealthCheck, HealthContext, HealthFinding } from "../types.js";
+
+const CHECK_ID = "no-discoveries";
+const CHECK_NAME = "Missing Discovery Sessions";
+
+/** Flags projects that have features but no discovery sessions. */
+export const noDiscoveriesCheck: HealthCheck = {
+  id: CHECK_ID,
+  name: CHECK_NAME,
+  description: "Detects projects with features but no discovery sessions to validate requirements",
+
+  run(ctx: HealthContext): HealthFinding[] {
+    const counts = ctx.store.counts();
+
+    const featureCount = counts["feature"] ?? 0;
+    if (featureCount === 0) return [];
+
+    const hasDiscoveries = (counts["discovery"] ?? 0) > 0;
+    if (hasDiscoveries) return [];
+
+    return [
+      {
+        checkId: CHECK_ID,
+        checkName: CHECK_NAME,
+        severity: "recommendation",
+        message: `Project has ${featureCount} feature(s) but no discovery sessions.`,
+        suggestion:
+          "Consider conducting discovery sessions with stakeholders to validate requirements and identify gaps before refinement.",
+      },
+    ];
+  },
+};

src/doctor/health/onboarding.ts

@@ -72,7 +72,18 @@ export function buildOnboardingGuide(ctx: HealthContext): OnboardingGuide {
     });
   }
 
-  // Step 3: Capture decisions and actions
+  // Step 3: Conduct discovery sessions
+  const hasDiscoveries = (counts["discovery"] ?? 0) > 0;
+  steps.push({
+    order: order++,
+    title: "Conduct discovery sessions",
+    description:
+      "As PO or DM, start discovery sessions with functional stakeholders to validate extracted requirements, identify gaps, and refine features before committing to decisions and epics.",
+    tool: "start_discovery",
+    done: hasDiscoveries,
+  });
+
+  // Step 4: Capture decisions and actions
   steps.push({
     order: order++,
     title: "Capture key decisions and actions",
@@ -82,7 +93,7 @@ export function buildOnboardingGuide(ctx: HealthContext): OnboardingGuide {
     done: (counts["decision"] ?? 0) > 0 && hasActions,
   });
 
-  // Step 4: Break down into epics
+  // Step 5: Break down into epics
   steps.push({
     order: order++,
     title: "Break work into epics",
@@ -93,7 +104,7 @@ export function buildOnboardingGuide(ctx: HealthContext): OnboardingGuide {
     done: hasEpics,
   });
 
-  // Step 5: Set up Sprint 0
+  // Step 6: Set up Sprint 0
   steps.push({
     order: order++,
     title: "Set up Sprint 0",
@@ -103,7 +114,7 @@ export function buildOnboardingGuide(ctx: HealthContext): OnboardingGuide {
     done: hasSprints,
   });
 
-  // Step 6: Configure Jira integration
+  // Step 7: Configure Jira integration
   steps.push({
     order: order++,
     title: "Configure Jira integration",
@@ -112,7 +123,7 @@ export function buildOnboardingGuide(ctx: HealthContext): OnboardingGuide {
     done: hasJira,
   });
 
-  // Step 7: Run health check
+  // Step 8: Run health check
   steps.push({
     order: order,
     title: "Run a health check",

src/personas/builtin/delivery-manager.ts

@@ -46,6 +46,16 @@ Sprint 0 ends when the team is ready to start Sprint 1 with a refined backlog an
     "Epic scheduling and tracking",
     "Sprint planning and tracking",
   ],
-  documentTypes: ["action", "decision", "meeting", "question", "feature", "epic", "task", "sprint"],
+  documentTypes: [
+    "action",
+    "decision",
+    "meeting",
+    "question",
+    "feature",
+    "epic",
+    "task",
+    "sprint",
+    "discovery",
+  ],
   contributionTypes: ["risk-finding", "blocker-report", "dependency-update", "status-assessment"],
 };

src/personas/builtin/product-owner.ts

@@ -35,7 +35,7 @@ export const productOwner: PersonaDefinition = {
     "Acceptance criteria",
     "Feature definition and prioritization",
   ],
-  documentTypes: ["decision", "question", "action", "feature", "use-case"],
+  documentTypes: ["decision", "question", "action", "feature", "use-case", "discovery"],
   contributionTypes: [
     "stakeholder-feedback",
     "acceptance-result",

src/personas/builtin/tech-lead.ts

@@ -37,7 +37,7 @@ export const techLead: PersonaDefinition = {
     "Task creation and breakdown",
     "Sprint scoping and technical execution",
   ],
-  documentTypes: ["decision", "action", "question", "epic", "task", "sprint"],
+  documentTypes: ["decision", "action", "question", "epic", "task", "sprint", "discovery"],
   contributionTypes: [
     "action-result",
     "spike-findings",

src/personas/prompt-builder.ts

@@ -41,6 +41,7 @@ You have access to governance tools for managing project artifacts:
 - **Features** (F-xxx): List, get, create, and update feature definitions
 - **Epics** (E-xxx): List, get, create, and update implementation epics (must link to approved features)
 - **Sprints** (SP-xxx): List, get, create, and update time-boxed iterations with linked epics and delivery dates
+- **Discoveries** (DS-xxx): Start, record findings/gaps, complete, and review stakeholder elicitation sessions
 - **Documents**: Search and read any project document
 - **Sources**: List source documents and view their processing status and derived artifacts
 

src/plugins/builtin/generic-agile.ts

@@ -18,6 +18,7 @@ export const genericAgilePlugin: MarvinPlugin = {
     "contribution",
     "sprint",
     "task",
+    "discovery",
   ],
   documentTypeRegistrations: [...COMMON_REGISTRATIONS],
   tools: (store) => [...createCommonTools(store)],
@@ -49,7 +50,18 @@ export const genericAgilePlugin: MarvinPlugin = {
 - Available contribution types: stakeholder-feedback, acceptance-result, priority-change, market-insight.
 
 **Sprint Tools (read-only for awareness):**
-- **list_sprints** / **get_sprint**: View sprints to understand delivery timelines and iteration scope.`,
+- **list_sprints** / **get_sprint**: View sprints to understand delivery timelines and iteration scope.
+
+**Discovery Tools:**
+- **start_discovery**: Start a new discovery session with a stakeholder to validate requirements and elicit gaps.
+- **record_finding** / **record_gap**: Record findings and gaps during the session. Use \`spawn_question: true\` on gaps to create linked Q-xxx artifacts.
+- **complete_discovery**: Finalize the session and transition to in-review.
+- **list_discoveries** / **get_discovery**: Browse discovery sessions.
+
+**Discovery Workflow:**
+- Focus on value alignment: validate that findings map to business outcomes.
+- Use gaps to identify missing acceptance criteria or scope ambiguities.
+- Review completed discoveries to refine features before committing to epics.`,
 
     "tech-lead": `You own epics and break approved features into implementation work.
 
@@ -92,6 +104,16 @@ export const genericAgilePlugin: MarvinPlugin = {
 - Tag technical actions and decisions with \`sprint:SP-xxx\` to associate them with a sprint.
 - Use **generate_sprint_progress** to track technical work completion within an iteration.
 
+**Discovery Tools (review focus):**
+- **list_discoveries** / **get_discovery**: Review discovery sessions for technical feasibility.
+- **add_discovery_review**: Annotate findings and gaps with technical assessments (feasibility, NFRs, architecture impact).
+- **resolve_gap**: Resolve technical gaps with rationale.
+
+**Discovery Review Guidelines:**
+- Assess findings for architectural feasibility and non-functional requirement impacts.
+- Flag gaps that require spikes or proof-of-concepts before resolution.
+- Annotate gap resolutions with technical rationale and links to relevant decisions.
+
 **Sprint Planning:**
 - When asked to plan or propose a sprint, ALWAYS call **gather_sprint_planning_context** first.
 - Focus on: technical readiness of each epic, open technical questions or spikes, effort balance across the sprint, and feature coverage.
@@ -154,6 +176,20 @@ export const genericAgilePlugin: MarvinPlugin = {
 - Track delivery dates and flag at-risk sprints.
 - Register past/completed sprints for historical tracking.
 
+**Discovery Tools:**
+- **start_discovery**: Start discovery sessions with functional stakeholders. Chain sessions using \`parent\` to carry forward open gaps.
+- **record_finding** / **record_gap**: Capture structured findings and gaps during elicitation. Use \`spawn_question: true\` to create linked Q-xxx for gaps.
+- **complete_discovery**: Finalize sessions and transition to in-review.
+- **add_discovery_review**: Add review annotations.
+- **resolve_gap** / **request_followup**: Resolve gaps or request follow-up input.
+- **list_discoveries** / **get_discovery**: Browse and read discovery sessions.
+
+**Discovery Workflow:**
+- Use structured elicitation techniques (interviews, workshops, walk-throughs) to validate requirements.
+- Track gaps systematically — spawn Q-xxx for items that need stakeholder input.
+- Ensure all gaps are resolved or parked before moving features to epics.
+- Chain discovery sessions to iterate on unresolved items.
+
 **Sprint Planning:**
 - When asked to plan or propose a sprint, ALWAYS call **gather_sprint_planning_context** first. It aggregates approved features, backlog epics, active sprint status, velocity from recent sprints, blockers, and summary stats in one call.
 - Reason through: priority (critical/high features first), capacity (compare backlog effort to velocity reference), dependencies and blockers, balance across features, and risk.
@@ -175,6 +211,8 @@ export const genericAgilePlugin: MarvinPlugin = {
 - **update_meeting**: Update meeting status or notes.
 - **analyze_meeting**: Analyze a meeting to extract decisions, actions, and questions as governance artifacts.
 
+**Discoveries** (DS-xxx): Stakeholder elicitation sessions that validate requirements and identify gaps. Status: draft -> in-review -> needs-input -> accepted | parked.
+
 **Contributions** (C-xxx): Structured inputs from personas outside of meetings (e.g. action results, risk findings, stakeholder feedback). Contributions are analyzed to produce governance effects.
 - **list_contributions** / **get_contribution**: Browse and read contribution records.
 - **create_contribution**: Record a contribution with persona, type, and optional related artifact.

src/plugins/builtin/sap-aem.ts

@@ -23,6 +23,7 @@ export const sapAemPlugin: MarvinPlugin = {
     "use-case",
     "tech-assessment",
     "extension-design",
+    "discovery",
   ],
   documentTypeRegistrations: [
     ...COMMON_REGISTRATIONS,
@@ -62,7 +63,18 @@ export const sapAemPlugin: MarvinPlugin = {
 - Assess and approve use cases before they move to technology assessment.
 - Do NOT create tech assessments or extension designs — those are the Tech Lead's responsibility.
 - Use priorities (critical, high, medium, low) to communicate business value.
-- Tag use cases with relevant business processes for traceability.`,
+- Tag use cases with relevant business processes for traceability.
+
+**Discovery Tools:**
+- **start_discovery**: Start discovery sessions with business stakeholders to validate extension use cases and elicit requirements.
+- **record_finding** / **record_gap**: Capture findings about extension needs and gaps in business process understanding.
+- **complete_discovery**: Finalize sessions and transition to in-review.
+- **list_discoveries** / **get_discovery**: Browse discovery sessions.
+
+**Discovery Workflow for AEM:**
+- Focus on validating extension use cases with business process owners.
+- Use gaps to identify missing business scenarios or unclear extension requirements.
+- Review discoveries to refine use cases before technology assessment.`,
 
     "tech-lead": `You are the Solution Architect in the SAP Application Extension Methodology (AEM).
 
@@ -93,7 +105,12 @@ export const sapAemPlugin: MarvinPlugin = {
 - Only create tech assessments for assessed/approved use cases — the system enforces this.
 - Only create extension designs for recommended tech assessments — the system enforces this.
 - Document BTP services (e.g., SAP Build Work Zone, SAP Event Mesh, SAP Integration Suite) in assessments.
-- Use epics to break extension designs into implementation work packages.`,
+- Use epics to break extension designs into implementation work packages.
+
+**Discovery Tools (review focus):**
+- **list_discoveries** / **get_discovery**: Review discovery sessions for technical feasibility.
+- **add_discovery_review**: Annotate findings with BTP technology assessments and extension point feasibility.
+- **resolve_gap**: Resolve technical gaps with rationale on BTP service capabilities.`,
 
     "delivery-manager": `You are the Project Manager in the SAP Application Extension Methodology (AEM).
 
@@ -124,6 +141,18 @@ export const sapAemPlugin: MarvinPlugin = {
 - Generate tech readiness reports to identify BTP service gaps.
 - Track risks via actions and questions. Flag unresolved items before phase gates.
 
+**Discovery Tools:**
+- **start_discovery**: Start discovery sessions with business stakeholders to validate extension scenarios.
+- **record_finding** / **record_gap**: Capture findings and gaps during elicitation. Use \`spawn_question: true\` to create linked Q-xxx for gaps.
+- **complete_discovery**: Finalize sessions and transition to in-review.
+- **add_discovery_review** / **resolve_gap** / **request_followup**: Review and resolve discovery outcomes.
+- **list_discoveries** / **get_discovery**: Browse discovery sessions.
+
+**Discovery Workflow for AEM:**
+- Conduct discovery sessions before each phase gate to validate readiness.
+- Track gaps that block phase transitions and escalate via actions.
+- Chain sessions to iterate on unresolved extension requirements.
+
 **Sprint 0 for AEM Projects:**
 When setting up Sprint 0, also include AEM-specific bootstrapping:
 - **Phase gate preparation**: Define soft gate checklists with readiness criteria for each AEM phase transition.
@@ -147,6 +176,8 @@ When setting up Sprint 0, also include AEM-specific bootstrapping:
 - **Meetings**: Meeting records. **Reports** (R-xxx): Persisted project reports.
 - Core governance: **Decisions** (D-xxx), **Actions** (A-xxx), **Questions** (Q-xxx).
 
+**Discoveries** (DS-xxx): Stakeholder elicitation sessions that validate extension use cases and identify gaps. Status: draft -> in-review -> needs-input -> accepted | parked.
+
 **Key Workflow:** Use cases → Tech assessments → Extension designs. Each level links to the previous. The system enforces that linked artifacts must be in the right status.`,
   },
 };