docs: replace placeholder personas with defined stakeholder personas in PRD (#1396)

* docs: replace placeholder personas with defined stakeholder personas in PRD

Replace the three illustrative placeholder personas (Sarah Meyer, Marcus
Klein, Jing Liu) with four agreed stakeholder personas — Anna Becker
(Project Manager), Dr. Jonas Weber (Researcher), Laura Hoffmann (Data
Steward), and Dr. Minh Tran (Data Scientist) — using a consistent
Role / Primary need / Pain point structure.

* docs: implement Feature layer governance with complete fixes

Add Feature ID schema (DOMAIN-FEAT-NN) as an intermediate traceability level
between Requirements and Stories. This establishes clear governance hierarchy:

  PRD → Requirements → Features → Stories → Tasks → Implementation

Key changes:

* Add Feature ID Schema section to AGENTS.md §0 with rules and examples
* Define Feature structure: ID, Title, Requirement IDs, Description, Rationale,
  Acceptance Criteria, Status, Dependencies, Child Stories
* Add .github/ISSUE_TEMPLATE/feature.yml GitHub issue template
  - Required fields: feature_id, requirement_ids, description, scope
  - Optional fields: notes, dependencies, child_stories
* Update story.yml with required parent_feature field (first required field)
* Update AGENTS.md traceability rules to mandate Feature parent for Stories
* Add Feature, Story, Task sequencing rules to prevent orphaned issues
* Update Section 11 (Agent Patterns) with Feature creation guidance
* Update Section 12 (Human Review Gates) with Feature slug change guardrails
* Add docs/requirements-guide.md with comprehensive authoring conventions
  - Requirement ID scheme and examples
  - Requirement format template and field definitions
  - When to create/edit/retire requirements
  - Common pitfalls and best practices
* Add 12 x "### Features" placeholder subsections to all domains
  in docs/requirements.md
* Fix terminology: "Scheme" → "Schema" for consistency (Requirement ID
  and Feature ID schemas)
* Fix domain list: add USER and COMM (now 12/12 domains complete)
* Fix zero-padding rule: "at least two digits" → "exactly two digits"
  with explicit invalid examples (1, 010)
* Fix story.yml Notes placeholder to clarify cross-story dependencies
  vs parent Feature link
* Add AGENTS.md §13 Key Files entry for requirements-guide.md
* Add missing --- section separator before AGENTS.md §1

This establishes unambiguous traceability from PRD through implementation,
enables release planning at the Feature level, and prevents Stories from
becoming orphaned requirements.

Backward compatible: existing requirements, stories, and tasks remain valid.

---------

Co-authored-by: Sven F. <9976560+sven1103@users.noreply.github.com>
Co-authored-by: Sven Fillinger <sven.fillinger@qbic.uni-tuebingen.de>
Co-authored-by: KochTobi <kochtobi@users.noreply.github.com>

Author: 3 people

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,67 @@
+name: Feature
+description: A named, user-visible capability that groups related Stories
+title: "[Feature] "
+labels: ["type:feature"]
+body:
+  - type: input
+    id: feature_id
+    attributes:
+      label: Feature ID
+      description: "A unique FEAT-<SLUG> identifier for this feature (e.g., FEAT-SAMPLE-REGISTRATION). The slug must be uppercase, hyphen-separated, and stable — do not change it once Stories reference this Feature."
+      placeholder: "FEAT-SAMPLE-REGISTRATION"
+    validations:
+      required: true
+
+  - type: input
+    id: requirement_ids
+    attributes:
+      label: Requirement IDs
+      description: "Reference one or more functional (R) or non-functional (NFR) requirement IDs from docs/requirements.md. At least one R-<NN> or NFR-<NN> ID is required. Constraint IDs (C-<NN>) must NOT be the sole references — they may appear in notes only."
+      placeholder: "SAMPLE-R-01, SAMPLE-NFR-01"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: "High-level summary of the user-visible capability this Feature delivers. What can a user do once this Feature is complete?"
+      placeholder: |
+        Researchers can register biological samples into the system individually or in batches,
+        providing required metadata (sample type, organism, collection date) and linking samples
+        to an existing experiment. Registered samples are immediately available for measurement
+        assignment and downstream analysis workflows.
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope / Boundaries
+      description: "Explicitly state what is in scope and what is out of scope for this Feature. This prevents scope creep and clarifies what Stories belong here."
+      placeholder: |
+        In scope:
+        - Individual sample registration via UI form
+        - Batch sample registration via XLSX/TSV upload
+        - Linking samples to an existing experiment
+        - Validation of required metadata fields
+
+        Out of scope:
+        - Sample deletion (covered by FEAT-SAMPLE-MANAGEMENT)
+        - Measurement assignment (covered by FEAT-MEASUREMENT-UPLOAD)
+        - OpenBIS synchronisation (covered by FEAT-LAB-INTEGRATION)
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes & Context (optional)
+      description: "Dependencies on other Features, related ADRs, constraints that influence design, or links to PRD sections."
+      placeholder: |
+        - Depends on: FEAT-USER-AUTH (users must be authenticated before registering samples)
+        - Related PRD section: §4.2 Sample Registration
+        - Architectural constraint: SAMPLE-C-01 (all samples must be assigned a QBiC barcode)
+        - ADR reference: ADR-012 (Batch upload file format selection)
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/story.yml

@@ -3,6 +3,15 @@ description: User-facing functionality derived from PRD/Requirements
 title: "[Story] "
 labels: ["type:story"]
 body:
+  - type: input
+    id: parent_feature
+    attributes:
+      label: Parent Feature
+      description: "Link to the Feature issue this story belongs to (e.g., #101)"
+      placeholder: "#101"
+    validations:
+      required: true
+
   - type: input
     id: requirement_ids
     attributes:
@@ -42,7 +51,7 @@ body:
       label: Notes & Context (optional)
       description: "Dependencies, design notes, links to PRD section, related constraints (e.g., references to AUTH-C-01)"
       placeholder: |
-        - Depends on: #123 (parent story for user registration)
+        - Related issue: Story #123 (user registration must complete first)
         - Design reference: See ADR-005 for authentication framework
         - Related requirement: AUTH-C-01 (MFA is optional in Phase 1)
     validations:

AGENTS.md

@@ -8,7 +8,27 @@
 
 ## 0. Requirements and Issue Governance
 
-### Requirement ID Scheme
+### Governance Hierarchy
+
+The governance model for this project follows a strict top-down traceability chain:
+
+```
+PRD (docs/prd.md)
+  └── Features  (.github/ISSUE_TEMPLATE/feature.yml)
+        └── Stories  (.github/ISSUE_TEMPLATE/story.yml)
+              └── Tasks  (.github/ISSUE_TEMPLATE/task.yml)
+                    └── Implementation (code, PRs)
+```
+
+- **PRD** defines product vision, user personas, and business objectives.
+- **Features** group related Stories under a named, user-visible capability. A Feature references one or more requirement IDs and describes the high-level scope.
+- **Stories** describe user-facing workflows derived from a Feature. Each Story references a parent Feature and one or more requirement IDs.
+- **Tasks** are concrete technical work items derived from a Story.
+- **Implementation** traces back through Tasks → Stories → Features → Requirements → PRD.
+
+---
+
+### Requirement ID Schema
 
 All requirements must follow the domain-based ID structure:
 
@@ -17,7 +37,7 @@ All requirements must follow the domain-based ID structure:
 Where:
 
 -   **DOMAIN** --- functional area (e.g. `API`, `PROJECT`, `SAMPLE`,
-    `MEASUREMENT`, `DATA`, `FAIR`, `CARE`, `QUALITY`, `LAB`, `AUTH`)
+    `MEASUREMENT`, `DATA`, `FAIR`, `CARE`, `QUALITY`, `LAB`, `AUTH`, `USER`, `COMM`)
 -   **TYPE** --- requirement type:
     -   `R` = Functional requirement (system capability)
     -   `NFR` = Non-functional requirement (quality attribute)
@@ -41,7 +61,34 @@ Where:
 -   One requirement may be referenced by multiple stories.
 -   A story may reference multiple requirement IDs when a single user workflow spans multiple requirements. If a story spans more than two domains, consider splitting it.
 -   Constraints (`C`) influence architecture and must not be referenced in Stories. Reference `C-<NN>` IDs only in Task Technical Notes.
--   The sequential number `<NN>` must be zero-padded to at least two digits (e.g., `01`, `02`, `10`). IDs without zero-padding are invalid.
+-   The sequential number `<NN>` must be zero-padded to exactly two digits (e.g., `01`, `02`, `10`). IDs without zero-padding are invalid (e.g., `1`, `010`).
+
+---
+
+### Feature ID Schema
+
+Features are identified using a short, human-readable slug:
+
+    FEAT-<SLUG>
+
+Where:
+
+-   **SLUG** --- a concise, uppercase, hyphen-separated identifier describing the user-visible capability (e.g., `FEAT-SAMPLE-REGISTRATION`, `FEAT-FAIR-EXPORT`, `FEAT-USER-AUTH`).
+
+#### Examples
+
+    FEAT-SAMPLE-REGISTRATION
+    FEAT-FAIR-EXPORT
+    FEAT-USER-AUTH
+    FEAT-MEASUREMENT-UPLOAD
+
+#### Rules
+
+-   Feature slugs must be unique across the project.
+-   Feature slugs must be stable; do not rename a Feature once Stories reference it.
+-   A Feature must reference at least one requirement ID (`R-<NN>` or `NFR-<NN>`).
+-   Constraints (`C-<NN>`) must not be used as the sole reference in a Feature — they may appear in Feature notes but Features must cite at least one `R` or `NFR` ID.
+-   One Feature may group multiple Stories across different domains, provided the Stories share a coherent user-visible purpose.
 
 ---
 
@@ -80,13 +127,39 @@ When creating issues, use the correct template for the scenario.
 
 ---
 
+#### Feature (`.github/ISSUE_TEMPLATE/feature.yml`)
+
+Use when creating issues for a **named, user-visible capability** that groups multiple related Stories.
+
+Required fields:
+
+-   **Feature ID**
+    -   A unique `FEAT-<SLUG>` identifier (e.g., `FEAT-SAMPLE-REGISTRATION`)
+-   **Requirement IDs**
+    -   At least one `R-<NN>` or `NFR-<NN>` reference
+-   **Description**
+    -   High-level summary of the user-visible capability
+-   **Scope / Boundaries**
+    -   What is in scope and what is explicitly out of scope for this Feature
+
+Rules:
+
+-   A Feature must be created before any Story references it.
+-   A Feature slug must be unique and stable — do not rename it once Stories reference it.
+-   Features must not reference Constraint IDs (`C-<NN>`) as their sole requirement references.
+-   One Feature may span multiple domains if the user-visible capability is coherent.
+
+---
+
 #### Story (`.github/ISSUE_TEMPLATE/story.yml`)
 
 Use when creating issues for **user-facing functionality** derived from
 the PRD or requirements.
 
 Required fields:
 
+-   **Parent Feature**
+    -   Link to the parent Feature issue (e.g. `#101`)
 -   **Requirement IDs**
     -   At least one `R-<NN>` reference
     -   May include related `NFR-<NN>`
@@ -98,6 +171,7 @@ Required fields:
 Rules:
 
 -   Stories describe value and workflow context.
+-   Stories must reference a parent Feature. Create the Feature first if one does not exist.
 -   Stories must not introduce new system capabilities not covered by an
     existing requirement.
 -   If new capability is needed, update `docs/requirements.md` first. A change introduces **new capability** if it enables a user or system to perform an action that was not previously possible, or if it changes the externally observable behavior of an existing capability in a way not described by any existing requirement.
@@ -129,18 +203,21 @@ Rules:
 
 ---
 
-#### Story and Task Sequencing
+#### Feature, Story, and Task Sequencing
 
+- A Feature must be created before any Story references it. Create the Feature first.
+- A Story must always reference a parent Feature. Never create a Story without a parent Feature issue.
 - A Task must always be preceded by a Story. Create the Story first, then create the Task referencing it.
 - Never create a Task without a parent Story issue.
-- If no parent Story exists for a piece of work (e.g., when acting on a direct implementation request), create the Story first before proceeding with implementation.
+- If no parent Feature exists for a piece of work (e.g., when acting on a direct implementation request), create the Feature first, then the Story, then the Task.
 - A single Story may have multiple Tasks; a Task must not span multiple Stories.
 
 ---
 
 ### Traceability Rules
 
 - Every Story must reference at least one functional requirement ID (`R-<NN>`).
+- Every Story must reference a parent Feature issue.
 - Every Task must reference:
     -   A parent Story
     -   At least one requirement ID
@@ -165,6 +242,22 @@ When editing requirements:
 
 **Agent rule — requirement changes require human approval:** Before modifying `docs/requirements.md`, an agent must: (1) pause and confirm the change with a human reviewer (see Section 12); (2) create a dedicated PR for the requirement change alone — do not bundle requirement changes with implementation changes; (3) include the mandatory changelog entry in the PR description per the rules above.
 
+---
+
+### Feature Edits
+
+When editing or retiring a Feature:
+
+-   Use a Pull Request.
+-   Include a changelog entry in the PR description summarizing:
+    -   Added / Modified / Retired Feature IDs
+    -   Reason for change
+    -   Impact on dependent Stories (list affected Story issues)
+
+**Agent rule — Feature slug changes require human approval:** A Feature slug must never be renamed once Stories reference it. Before retiring or splitting a Feature, an agent must: (1) pause and confirm with a human reviewer; (2) list all Story issues that reference the Feature in the PR description; (3) update Story issues to reference the replacement Feature if applicable.
+
+
+---
 
 ## 1. Project Overview
 
@@ -513,13 +606,21 @@ When working on this codebase, an AI agent should:
 
 ### Before making changes
 
-0. **Check `docs/requirements.md`** to confirm the change is covered by an existing requirement. If the change introduces new system capability not covered by any existing requirement, update `docs/requirements.md` first (see "Requirements and Issue Governance"). If `docs/requirements.md` does not exist, do not create it — pause and notify a human reviewer.
+0. **Check `docs/requirements.md`** to confirm the change is covered by an existing requirement. If the change introduces new system capability not covered by any existing requirement, update `docs/requirements.md` first (see "Requirements and Issue Governance"). If `docs/requirements.md` does not exist, do not create it — pause and notify a human reviewer. Then confirm a parent Feature issue exists before creating any Story or Task.
 1. **Identify the bounded context** the change belongs to (`identity`, `project-management`,
    `finances`, or cross-cutting).
 2. **Identify the layer** (`domain`, `application`, `infrastructure`, `views`/UI).
 3. Check `ExceptionHandling.md` and `service_api.md` for patterns relevant to the change.
 4. Read existing tests in the same module before writing new code.
 
+### Creating Features
+
+- Before creating a Story, confirm a parent Feature issue exists. If none exists, create the Feature first using `.github/ISSUE_TEMPLATE/feature.yml`.
+- A Feature must reference at least one `R-<NN>` or `NFR-<NN>` requirement ID.
+- Do not create a Feature whose sole requirement reference is a Constraint (`C-<NN>`).
+- A Feature slug (`FEAT-<SLUG>`) must be unique and must not be changed once Stories reference it.
+- If you are unsure whether a new Feature is needed or an existing Feature should be extended, pause and ask a human reviewer.
+
 ### Making domain changes
 
 - New domain concepts go in `domain/model/` of the relevant bounded context.
@@ -567,6 +668,8 @@ An agent should pause and request human review/approval before:
 - Changing the Artemis messaging topic names or JMS consumer configuration.
 - Adding, modifying, or removing any entry in `docs/requirements.md`.
 - Implementing a change that introduces new system capability not covered by an existing requirement.
+- Retiring or renaming a Feature slug once Stories reference it.
+- Splitting a Feature into multiple Features when Stories already reference the original Feature.
 
 ---
 
@@ -575,6 +678,7 @@ An agent should pause and request human review/approval before:
 | File / Path | Purpose |
 |---|---|
 | `docs/requirements.md` | Authoritative requirement registry — all R/NFR/C requirements documented here; must be updated before new capabilities are implemented |
+| `docs/requirements-guide.md` | Authoring conventions for creating, editing, and retiring requirements |
 | `README.md` | Setup, configuration reference, how to run |
 | `ExceptionHandling.md` | Exception handling conventions (read before touching error handling) |
 | `service_api.md` | Service API design patterns (Mono/Flux, request/response shapes) |
@@ -586,6 +690,7 @@ An agent should pause and request human review/approval before:
 | `datamanager-app/src/main/resources/application.properties` | Full application configuration with env var mappings |
 | `datamanager-bom/pom.xml` | All dependency version pins |
 | `.github/labeler.yml` | PR/branch labeling rules |
+| `.github/ISSUE_TEMPLATE/feature.yml` | Issue template for named, user-visible capabilities (features) |
 | `.github/ISSUE_TEMPLATE/story.yml` | Issue template for user-facing functionality (user stories) |
 | `.github/ISSUE_TEMPLATE/task.yml` | Issue template for concrete technical implementation tasks |
 | `.github/release.yml` | Release changelog categories |

docs/prd.md

@@ -9,22 +9,25 @@ By combining structured metadata capture, quality assessment, and interoperabili
 
 ## 2. Users & primary use cases
 
-<!-- PLACEHOLDER: The personas and use cases below are illustrative only. Replace with actual stakeholder research and user feedback before finalising the PRD. -->
-
-**Persona A: Dr. Sarah Meyer – Principal Investigator (Biology Group)**
-- Role: Leads a translational cancer biology research group at University of Tübingen
-- Primary need: Design and track multi-year, multi-omics studies with 200+ samples from patient cohorts
-- Pain point: Tracks experimental metadata in spreadsheets; struggles to ensure consistent sample naming and measurement parameters across internal lab work and outsourced sequencing
-
-**Persona B: Marcus Klein – Lab Manager (QBiC Service Provider)**
-- Role: Manages high-throughput analysis services (NGS, proteomics) at QBiC for internal and external researchers
-- Primary need: Register samples from multiple projects, batch them for efficiency, upload measurement metadata from partner instruments, and track data transfer workflows
-- Pain point: Currently uses OpenBIS and manual scripts; needs a unified UI to manage project-level metadata and track which samples have been measured
-
-**Persona C: Jing Liu – Bioinformatician (Data Analyst)**
-- Role: Analyzes omics data for research collaborators; publishes datasets
-- Primary need: Download raw measurement data, review sample metadata, and export projects as FAIR-compliant research objects (RO-Crate) for archival and publication
-- Pain point: Data discovery across projects is fragmented; wants reproducibility and proper attribution (ORCID integration)
+**Persona 1: Anna Becker – Project Manager**
+- **Role:** Employed at the QBiC BioPM team; acts as the primary contact between end-users, customers, and member labs performing sample measurements. Manages service offers, tracks research project progress, and reports back to end-users.
+- **Primary need:** Quick overviews of important project updates and easy access to consolidated information for reporting — without switching between multiple systems.
+- **Pain point:** Manually checking many interfaces for information or updates, and acting as a communication proxy between end-users and internal teams.
+
+**Persona 2: Dr. Jonas Weber – Researcher**
+- **Role:** Scientist conducting a scientific study; responsible for defining the experimental setup, providing sample information, and setting quality demands on analysis outputs.
+- **Primary need:** A single place where all project information comes together, so hypotheses can be tested quickly and findings published to maximise scientific impact.
+- **Pain point:** Numerous FAIR data management and best-practice requirements with limited resources and no direct incentive to comply; gets frustrated when excessive manual tasks slow down actual scientific progress.
+
+**Persona 3: Laura Hoffmann – Data Steward**
+- **Role:** Operates at an institutional level (university research office or data governance team); oversees data management standards and FAIR/CARE compliance across multiple research groups and projects.
+- **Primary need:** Visibility into project metadata quality, data export readiness, and audit trails to support governance reporting and funder compliance documentation.
+- **Pain point:** Manually checking compliance status across dispersed projects and coordinating with researchers to resolve metadata gaps; gets frustrated when compliance workflows require extensive back-and-forth communication.
+
+**Persona 4: Dr. Minh Tran – Data Scientist**
+- **Role:** Based in a research group or core bioinformatics facility; downloads raw measurement data from the platform, integrates it with external datasets, and performs comparative analysis for publications and grant proposals.
+- **Primary need:** Structured, machine-readable metadata that minimises cleaning and reformatting work before analysis, with reliable sample tracking for reproducibility and traceability.
+- **Pain point:** Incomplete or inconsistent sample metadata that requires detective work to reconcile samples across projects; lack of standardised ontologies makes cross-project analysis cumbersome and delays publication timelines.
 
 **Top 3 jobs-to-be-done:**
 1. **Design and document an experiment** – Create a project, define experimental groups, specify variables and confounding factors, and invite collaborators without manual email coordination