From bd64fd999c6fa172205de9861958182ddb29b1a5 Mon Sep 17 00:00:00 2001 From: sven1103 codex agent <261423644+sven1103-agent@users.noreply.github.com> Date: Thu, 12 Mar 2026 16:55:04 +0100 Subject: [PATCH 1/2] docs: replace placeholder personas with defined stakeholder personas in PRD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/prd.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/docs/prd.md b/docs/prd.md index ce10398cd4..748c7e66af 100644 --- a/docs/prd.md +++ b/docs/prd.md @@ -9,22 +9,25 @@ By combining structured metadata capture, quality assessment, and interoperabili ## 2. Users & primary use cases - - -**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 From 25fb0270b5209f9cd95a7d8c0e3d870973072556 Mon Sep 17 00:00:00 2001 From: sven1103 codex agent <261423644+sven1103-agent@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:23:14 +0100 Subject: [PATCH 2/2] docs: implement Feature layer governance with complete fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .github/ISSUE_TEMPLATE/feature.yml | 67 ++++++++++++ .github/ISSUE_TEMPLATE/story.yml | 11 +- AGENTS.md | 117 +++++++++++++++++++-- docs/requirements-guide.md | 159 +++++++++++++++++++++++++++++ docs/requirements.md | 94 ++++++++++++++++- 5 files changed, 436 insertions(+), 12 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 docs/requirements-guide.md diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000000..cc45b7bc20 --- /dev/null +++ b/.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- 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- or NFR- ID is required. Constraint IDs (C-) 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 diff --git a/.github/ISSUE_TEMPLATE/story.yml b/.github/ISSUE_TEMPLATE/story.yml index 428e659b9a..8c0260446b 100644 --- a/.github/ISSUE_TEMPLATE/story.yml +++ b/.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: diff --git a/AGENTS.md b/AGENTS.md index 57b2eab35a..f9e8e655fc 100644 --- a/AGENTS.md +++ b/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-` IDs only in Task Technical Notes. -- The sequential number `` must be zero-padded to at least two digits (e.g., `01`, `02`, `10`). IDs without zero-padding are invalid. +- The sequential number `` 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- + +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-` or `NFR-`). +- Constraints (`C-`) 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,6 +127,30 @@ 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-` identifier (e.g., `FEAT-SAMPLE-REGISTRATION`) +- **Requirement IDs** + - At least one `R-` or `NFR-` 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-`) 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 @@ -87,6 +158,8 @@ the PRD or requirements. Required fields: +- **Parent Feature** + - Link to the parent Feature issue (e.g. `#101`) - **Requirement IDs** - At least one `R-` reference - May include related `NFR-` @@ -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,11 +203,13 @@ 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. --- @@ -141,6 +217,7 @@ Rules: ### Traceability Rules - Every Story must reference at least one functional requirement ID (`R-`). +- 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-` or `NFR-` requirement ID. +- Do not create a Feature whose sole requirement reference is a Constraint (`C-`). +- A Feature slug (`FEAT-`) 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 | diff --git a/docs/requirements-guide.md b/docs/requirements-guide.md new file mode 100644 index 0000000000..c771ab4610 --- /dev/null +++ b/docs/requirements-guide.md @@ -0,0 +1,159 @@ +# Requirements Authoring Guide + +This guide provides conventions for creating, documenting, and maintaining requirements in `docs/requirements.md`. + +## Quick Start + +1. **Check the current requirements** in `docs/requirements.md` to confirm you're not duplicating an existing requirement. +2. **Choose a domain** from the allowed list: `AUTH`, `PROJECT`, `SAMPLE`, `MEASUREMENT`, `DATA`, `FAIR`, `CARE`, `QUALITY`, `LAB`, `API`, `USER`, `COMM`. +3. **Choose a type**: `R` (functional requirement), `NFR` (non-functional requirement), or `C` (constraint). +4. **Assign a number**: Sequential, zero-padded to exactly two digits within your domain+type pair (e.g., `01`, `02`, `03`). +5. **Write the requirement** using the format specified below. + +--- + +## Requirement ID Schema + +All requirement IDs follow this pattern: + +``` +-- +``` + +- **DOMAIN** — Functional area (AUTH, PROJECT, SAMPLE, MEASUREMENT, DATA, FAIR, CARE, QUALITY, LAB, API, USER, COMM) +- **TYPE** — Requirement classification: + - `R` = Functional requirement ("the system shall…") + - `NFR` = Non-functional requirement (performance, security, usability, scalability, etc.) + - `C` = Constraint (solution boundary, architectural decision, "must use…", "must not…") +- **NN** — Sequential number per (DOMAIN, TYPE) pair, zero-padded to exactly two digits: `01`, `02`, `10`, `99` + +### Examples + +- `AUTH-R-01` — Functional requirement (auth domain) +- `PROJECT-NFR-02` — Non-functional requirement (project domain) +- `SAMPLE-C-01` — Constraint (sample domain) +- `FAIR-R-03` — Functional requirement (FAIR domain) + +### Rules + +- IDs are **stable** and must never be renumbered or reused, even if a requirement is deprecated. +- IDs must not encode sprint numbers, versions, or document order. +- One requirement may be referenced by multiple Stories. +- Constraints (`*-C-*`) influence architecture and must not be referenced in Stories — reference them only in Task Technical Notes and ADRs. + +--- + +## Requirement Format + +Each requirement entry in `docs/requirements.md` must contain: + +```markdown +### : + + + +**Rationale:** + + +**Source (optional but recommended):** + +``` + +### Field Definitions + +- **ID** — Use the scheme above (e.g., `AUTH-R-01`) +- **Short Title** — One line, noun-focused, describing the capability or quality attribute +- **Statement** — 1–3 sentences describing what the system shall do (for R/NFR) or the solution boundary (for C) +- **Rationale** — Why this requirement exists: strategic importance, regulatory drivers, stakeholder requests, technical necessity +- **Source** — Link(s) to the upstream authority: PRD section, FAIR/CARE principle reference, standards document, ADR, or stakeholder issue + +### Example + +```markdown +### AUTH-R-01: User Authentication via Local Credentials + +The system shall allow users to create a local account using an email address and password, +and shall authenticate subsequent login attempts against the stored, hashed password. + +**Rationale:** +Users require a low-friction on-ramp to the system without requiring external identity providers. +Local credentials are a foundational capability enabling all downstream workflows. ORCID is an optional, +secondary authentication pathway. + +**Source:** +PRD §2.1 User Onboarding; User story: "As a researcher, I want to log in with my email." +``` + +--- + +## When to Create a New Requirement + +Create a new requirement when: + +1. **A user-facing capability is missing** from the system (a Story or Feature references it but no R/NFR exists) +2. **A quality attribute is not yet documented** (e.g., performance target, accessibility standard) +3. **An architectural constraint is not yet recorded** (e.g., "must use Java 21", "OpenBIS integration required") + +**Do NOT create a requirement for:** + +- A specific implementation detail (use Task Technical Notes instead) +- A feature that will be deprecated soon (mark existing requirement as superseded first) +- A one-off bug fix (use a bug report, not a requirement) + +--- + +## Editing Requirements + +### Adding a new requirement + +1. Add the requirement entry to the appropriate domain section in `docs/requirements.md` +2. Assign a new sequential number (do not reuse retired IDs) +3. Create a PR with the requirement change +4. Include a changelog entry in the PR description: "Added [ID]: [Short Title]" + +### Modifying an existing requirement + +1. Update the statement, rationale, or source as needed +2. **Do not change the ID** — IDs are stable +3. Create a PR with the change +4. Include a changelog entry: "Modified [ID]: [reason for change]" + +### Retiring a requirement + +1. Mark it as **[RETIRED]** in the ID line +2. Add a note explaining why and when it was retired +3. Create a PR +4. Include a changelog entry: "Retired [ID]: [reason]" + +--- + +## Common Pitfalls + +❌ **Avoid:** Creating a requirement for a specific story (too granular) +✅ **Do:** Create a requirement for a capability that multiple stories might address + +❌ **Avoid:** Renumbering or reusing IDs (breaks traceability) +✅ **Do:** Retire the old ID and assign a new number to a new requirement + +❌ **Avoid:** Referencing Constraints in Stories +✅ **Do:** Reference Constraints only in Task Technical Notes + +❌ **Avoid:** Vague rationales ("because we need it") +✅ **Do:** Explain the strategic, regulatory, or architectural driver + +❌ **Avoid:** Mixing multiple capabilities in one requirement +✅ **Do:** Split into separate requirements per capability/quality attribute + +--- + +## Related Documents + +- **AGENTS.md § Section 0** — Full requirement governance rules and issue templates +- **docs/requirements.md** — Authoritative requirements registry +- **AGENTS.md § Section 11** — Agent delegation patterns for requirement changes + +--- + +## Questions? + +Consult AGENTS.md Section 12 for what to ask a human reviewer before making requirement changes. diff --git a/docs/requirements.md b/docs/requirements.md index 63643b40ab..a87f52c934 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -8,13 +8,49 @@ This file is the **authoritative requirements registry** for the Data Manager Ap - **PRD (`docs/prd.md`):** The Product Requirements Document contains the product vision, user personas, and business objectives. It is the upstream input to this registry. - **This Registry:** Formalises PRD objectives into traceable, ID-tagged requirements. Each requirement is derived from and traces back to the PRD, stakeholder requests, regulatory drivers, or architectural decisions. -- **GitHub Stories and Tasks:** Requirements are one level above Stories. A Story references one or more requirement IDs and describes a user-facing workflow. A Task references a Story and implements concrete work towards that Story's acceptance criteria. +- **GitHub Features, Stories, and Tasks:** Requirements sit above Features in the governance hierarchy. A Feature groups related Stories under a named, user-visible capability and references one or more requirement IDs. A Story references a parent Feature and one or more requirement IDs, describing a user-facing workflow. A Task references a Story and implements concrete work towards that Story's acceptance criteria. ### Workflow -1. **PRD → Requirements → Stories → Tasks → Implementation** -2. Before making any change to the system, check this file to confirm the change is covered by an existing requirement. If the change introduces new system capability not covered by any existing requirement, update this file first (see `docs/requirements-guide.md` for full authoring conventions). -3. **Agents:** You must read this file and `AGENTS.md` Section 11 step 0 before making any code change. +1. **PRD → Requirements → Features → Stories → Tasks → Implementation** +2. Before making any change to the system, check this file to confirm the change is covered by an existing requirement. If the change introduces new system capability not covered by any existing requirement, update this file first. Consult `docs/requirements-guide.md` for full authoring conventions. +3. Before creating a Story, confirm a parent Feature issue exists in the GitHub repository. If no Feature exists for the area of work, create the Feature first using `.github/ISSUE_TEMPLATE/feature.yml`. +4. **Agents:** You must read this file and `AGENTS.md` Section 11 step 0 before making any code change. + +--- + +## Feature Layer + +Features are the bridge between requirements and Stories. A Feature represents a named, user-visible capability — a coherent set of functionality that a user can understand and benefit from as a whole. + +### Feature ID Schema + +Features are identified using a short, human-readable slug: + +``` +FEAT- +``` + +- **SLUG** — A concise, uppercase, hyphen-separated label describing the user-visible capability. + - Valid: `FEAT-SAMPLE-REGISTRATION`, `FEAT-FAIR-EXPORT`, `FEAT-USER-AUTH` + - Invalid: `FEAT-01`, `feat-sample`, `FEATURE_REGISTRATION` + +### Feature Rules + +- A Feature slug must be **unique and stable** — never rename it once Stories reference it. +- A Feature must reference at least one `R-` or `NFR-` requirement ID from this registry. +- Constraints (`*-C-*`) must not be the sole requirement references for a Feature. They may appear in Feature notes but at least one `R` or `NFR` ID must be cited. +- One Feature may span multiple domains if the user-visible capability is coherent and the Stories it groups share a unified purpose. +- A Feature must be created in GitHub (using `.github/ISSUE_TEMPLATE/feature.yml`) before any Story references it. + +### Feature Format + +Features are tracked as GitHub issues using the Feature issue template. Each Feature issue must include: + +- **Feature ID** — The `FEAT-` identifier +- **Requirement IDs** — One or more `R-` or `NFR-` references +- **Description** — What the user can do once this Feature is complete +- **Scope / Boundaries** — What is in scope and explicitly out of scope --- @@ -45,7 +81,7 @@ All requirements follow a domain-based ID structure: - `NFR` — Non-functional requirement (quality attribute: performance, scalability, security, usability, etc.) - `C` — Constraint (solution boundary: "must use…", "must not…", architectural decision) -- **NN** — Sequential number per (DOMAIN, TYPE) pair, zero-padded to two digits: +- **NN** — Sequential number per (DOMAIN, TYPE) pair, zero-padded to exactly two digits: - Valid: `01`, `02`, `10`, `99` - Invalid: `1`, `2`, `010` (no leading zeros beyond two digits) @@ -99,6 +135,10 @@ PRD §3.1 Core Data Management; User story: "As a researcher, I want to create a ## AUTH — Authentication and User Identity +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -115,6 +155,10 @@ _No requirements defined yet._ ## PROJECT — Project Management and Experimental Design +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -131,6 +175,10 @@ _No requirements defined yet._ ## SAMPLE — Sample Registration and Batch Management +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -147,6 +195,10 @@ _No requirements defined yet._ ## MEASUREMENT — Measurement Metadata and Data Tracking +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -163,6 +215,10 @@ _No requirements defined yet._ ## DATA — Raw Data File Handling +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -179,6 +235,10 @@ _No requirements defined yet._ ## FAIR — FAIR Data Principles and Export +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -195,6 +255,10 @@ _No requirements defined yet._ ## CARE — CARE Principles and Data Governance +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -211,6 +275,10 @@ _No requirements defined yet._ ## QUALITY — Data Quality and Validation +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -227,6 +295,10 @@ _No requirements defined yet._ ## LAB — Laboratory Operations and External Integrations +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -243,6 +315,10 @@ _No requirements defined yet._ ## API — Programmatic Access and API Design +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -259,6 +335,10 @@ _No requirements defined yet._ ## USER — User Management, Roles, and Permissions +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._ @@ -275,6 +355,10 @@ _No requirements defined yet._ ## COMM — Communication, Notifications, and Announcements +### Features + +_No features defined yet._ + ### Functional Requirements _No requirements defined yet._