Chore: Minimal human and agent-friendly requirements setup#1384
Merged
sven1103 merged 19 commits intodevelopmentfrom Mar 11, 2026
Merged
Chore: Minimal human and agent-friendly requirements setup#1384sven1103 merged 19 commits intodevelopmentfrom
sven1103 merged 19 commits intodevelopmentfrom
Conversation
Add explicit guidance for agents on which GitHub issue template to use and what fields are required for each (Story vs Task templates). Also add both template files to the Key Files Quick Reference table.
- Adopt <DOMAIN>-<TYPE>-<NN> naming scheme (AUTH-R-01, PROJECT-NFR-01, etc.) - Organize requirements by feature domain - Move acceptance criteria to user stories (per AGENTS.md) - Add comprehensive rationale with strategic/regulatory/stakeholder context - Capture all source references (PRD sections, ADRs, regulatory, stakeholder) - Structure: Statement + Rationale + Source for each requirement - Include 6 domains: AUTH, PROJECT, QUALITY, FAIR, USER, COMM - Add R (Functional), NFR (Non-functional), C (Constraint) types - Updated introduction to document ID schema and cross-reference patterns
Add a checklist for authors to self-review requirements before submitting PRs. This reduces review burden and ensures consistent quality. Includes verification of ID format, statement clarity, rationale completeness, and dependency tracking. Also updated PR review checklist to reference the pre-submission checklist.
Add comprehensive guidance for writing testable acceptance criteria in Stories. Includes Given/When/Then format, 3 complete examples (PAT, MFA, Project Creation), common mistakes to avoid, and tips for clarity. Emphasizes behavior-focused, testable criteria that trace back to requirements.
Add optional Dependencies section (4th section) to requirement structure. Explains how to track prerequisites, related requirements, and supersession. Shows examples with AUTH-R-04 and AUTH-NFR-02 including dependencies. Helps with impact analysis and implementation sequencing.
Add comprehensive glossary (docs/glossary.md) defining domain-specific terms used in requirements and design: TOTP, FAIR, RO-Crate, RBAC, ACL, ORCID, Personal Access Token, Experiment, Sample, Measurement, OpenBIS, Spring Security ACL, GDPR, OAuth2, etc. Cross-reference glossary in requirements-guide.md to reduce ambiguity and ensure consistent terminology across requirements, PRD, and code.
Story template (.github/ISSUE_TEMPLATE/story.yml): - Fix requirement ID placeholder: remove non-existent 'AC-xx' references - Use domain-based schema examples (AUTH-R-02, PROJECT-NFR-01) - Improve user story description with concrete example - Add link to requirements-guide.md AC conventions and examples - Provide concrete placeholder for acceptance criteria using Given/When/Then - Clarify notes field for dependencies, design references, constraints Task template (.github/ISSUE_TEMPLATE/task.yml): - Clarify requirement ID field with type explanation (R/NFR/C) - Add placeholder examples showing technical scope - Add 'Acceptance Criteria Reference' field to copy parent Story AC - Improve technical notes section with examples (modules, libraries, ADRs, blocking/blocked tasks) - All changes help align tasks with parent Story requirements
… AGENTS.md Apply all High and Medium severity findings from the SUGGESTIONS_AGENTS.md review report to improve agent governance, clarity, and traceability: - Section 0: Add number to Requirements and Issue Governance heading (D-1) - Add reciprocal rule: a story may reference multiple requirement IDs (A-5) - Rewrite constraints rule: C-<NN> IDs must not appear in Stories (A-2) - Add zero-padding rule for <NN> sequential numbers (A-3/C-3) - Standardize R-xx/NFR-xx/C-xx placeholders to R-<NN>/NFR-<NN>/C-<NN> (A-3) - Remove redundant constraints bullet from Task Rules (A-4) - Add 'new capability' definition to Story Rules (C-5) - Add Story and Task Sequencing sub-section with explicit ordering rules (C-1) - Reconcile Traceability Rules to require functional R-<NN> reference (A-1) - Replace vague agent requirement edit note with actionable 3-step rule (C-2) - Add step 0 to Section 11 pre-change checklist for requirements check (B-2) - Add docs/requirements.md as first entry in Section 13 Key Files table (B-1) - Add two requirement-related escalation bullets to Section 12 (B-3) - Standardize long-dash horizontal rules to --- throughout Section 0 (D-2) Also remove all resolved findings from SUGGESTIONS_AGENTS.md, retaining only the 7 remaining Low/Medium open items (B-4, C-6, C-7, C-8, D-2, D-3, D-4).
Replace the populated requirements.md with a clean template-based registry and remove the separate requirements-guide.md, consolidating authoring conventions into AGENTS.md and the registry's own intent section.
KochTobi
requested changes
Mar 11, 2026
Contributor
KochTobi
left a comment
KochTobi
left a comment
There was a problem hiding this comment.
Some inconsistencies I noticed with the help of Sonnet 4.6
| @@ -0,0 +1,161 @@ | |||
| # Findings Report: "Requirements and Issue Governance" Section — AGENTS.md | |||
Contributor
There was a problem hiding this comment.
Can this document be removed?
Contributor
Author
There was a problem hiding this comment.
No, there are still open points that otherwise would get lost :)
| - Every Task must reference: | ||
| - A parent Story | ||
| - At least one requirement ID | ||
| - Every PR must: |
Contributor
There was a problem hiding this comment.
.github/PULL_REQUEST_TEMPLATE.md was added as an empty file. Given that the Traceability Rules say "Every PR must reference the issue it implements and list the requirement IDs addressed" — the PR template should enforce this. At minimum it should have a checklist like:
## Traceability
- Closes #
- Requirement IDs addressed:
## Checklist
- [ ] Story and Task issues exist for this work
- [ ] No new system capability introduced without a requirement updateCurrently PULL_REQUEST_TEMPLATE is empty??
…th examples - Add .github/PULL_REQUEST_TEMPLATE.md enforcing AGENTS.md traceability rules: issue linking, requirement ID listing (R/NFR only, no C IDs), requirement update confirmation or justification, and sensitive-change flagging - Enrich docs/prd.md with illustrative placeholder examples for all sections (personas, scope, metrics, constraints, open questions), clearly marked with HTML placeholder comments for replacement with real content - Minor: remove requirements guide reference from story.yml acceptance criteria description (guide was removed from docs in earlier commit)
Co-authored-by: Tobias Koch <tobias.koch@uni-tuebingen.de>
Constraint IDs (C-<NN>) may only be referenced in Technical Notes, never in the Requirement IDs field. Updated the field descriptions and placeholder to enforce this rule explicitly for both human contributors and AI agents.
|
KochTobi
approved these changes
Mar 11, 2026
Contributor
KochTobi
left a comment
KochTobi
left a comment
There was a problem hiding this comment.
LGTM
Looking forward to seeing it in action and how it performs
KochTobi
added a commit
that referenced
this pull request
Apr 20, 2026
* Chore: Minimal human and agent-friendly requirements setup (#1384) * Add scaffold for requirements tracking * Draft scaffold * docs: document issue template usage in AGENTS.md Add explicit guidance for agents on which GitHub issue template to use and what fields are required for each (Story vs Task templates). Also add both template files to the Key Files Quick Reference table. * Submit product goal * Add claude suggestions for requirements * refactor: align requirements with domain-based ID schema from AGENTS.md - Adopt <DOMAIN>-<TYPE>-<NN> naming scheme (AUTH-R-01, PROJECT-NFR-01, etc.) - Organize requirements by feature domain - Move acceptance criteria to user stories (per AGENTS.md) - Add comprehensive rationale with strategic/regulatory/stakeholder context - Capture all source references (PRD sections, ADRs, regulatory, stakeholder) - Structure: Statement + Rationale + Source for each requirement - Include 6 domains: AUTH, PROJECT, QUALITY, FAIR, USER, COMM - Add R (Functional), NFR (Non-functional), C (Constraint) types - Updated introduction to document ID schema and cross-reference patterns * docs: add pre-submission checklist for requirement authors Add a checklist for authors to self-review requirements before submitting PRs. This reduces review burden and ensures consistent quality. Includes verification of ID format, statement clarity, rationale completeness, and dependency tracking. Also updated PR review checklist to reference the pre-submission checklist. * docs: add acceptance criteria conventions guide Add comprehensive guidance for writing testable acceptance criteria in Stories. Includes Given/When/Then format, 3 complete examples (PAT, MFA, Project Creation), common mistakes to avoid, and tips for clarity. Emphasizes behavior-focused, testable criteria that trace back to requirements. * docs: add dependency and relationship tracking to requirements Add optional Dependencies section (4th section) to requirement structure. Explains how to track prerequisites, related requirements, and supersession. Shows examples with AUTH-R-04 and AUTH-NFR-02 including dependencies. Helps with impact analysis and implementation sequencing. * docs: create glossary and cross-reference in requirements guide Add comprehensive glossary (docs/glossary.md) defining domain-specific terms used in requirements and design: TOTP, FAIR, RO-Crate, RBAC, ACL, ORCID, Personal Access Token, Experiment, Sample, Measurement, OpenBIS, Spring Security ACL, GDPR, OAuth2, etc. Cross-reference glossary in requirements-guide.md to reduce ambiguity and ensure consistent terminology across requirements, PRD, and code. * docs: improve story and task template clarity and guidance Story template (.github/ISSUE_TEMPLATE/story.yml): - Fix requirement ID placeholder: remove non-existent 'AC-xx' references - Use domain-based schema examples (AUTH-R-02, PROJECT-NFR-01) - Improve user story description with concrete example - Add link to requirements-guide.md AC conventions and examples - Provide concrete placeholder for acceptance criteria using Given/When/Then - Clarify notes field for dependencies, design references, constraints Task template (.github/ISSUE_TEMPLATE/task.yml): - Clarify requirement ID field with type explanation (R/NFR/C) - Add placeholder examples showing technical scope - Add 'Acceptance Criteria Reference' field to copy parent Story AC - Improve technical notes section with examples (modules, libraries, ADRs, blocking/blocked tasks) - All changes help align tasks with parent Story requirements * Rename TEAMPLATE to TEMPLATE * docs: apply High and Medium suggestions from SUGGESTIONS_AGENTS.md to AGENTS.md Apply all High and Medium severity findings from the SUGGESTIONS_AGENTS.md review report to improve agent governance, clarity, and traceability: - Section 0: Add number to Requirements and Issue Governance heading (D-1) - Add reciprocal rule: a story may reference multiple requirement IDs (A-5) - Rewrite constraints rule: C-<NN> IDs must not appear in Stories (A-2) - Add zero-padding rule for <NN> sequential numbers (A-3/C-3) - Standardize R-xx/NFR-xx/C-xx placeholders to R-<NN>/NFR-<NN>/C-<NN> (A-3) - Remove redundant constraints bullet from Task Rules (A-4) - Add 'new capability' definition to Story Rules (C-5) - Add Story and Task Sequencing sub-section with explicit ordering rules (C-1) - Reconcile Traceability Rules to require functional R-<NN> reference (A-1) - Replace vague agent requirement edit note with actionable 3-step rule (C-2) - Add step 0 to Section 11 pre-change checklist for requirements check (B-2) - Add docs/requirements.md as first entry in Section 13 Key Files table (B-1) - Add two requirement-related escalation bullets to Section 12 (B-3) - Standardize long-dash horizontal rules to --- throughout Section 0 (D-2) Also remove all resolved findings from SUGGESTIONS_AGENTS.md, retaining only the 7 remaining Low/Medium open items (B-4, C-6, C-7, C-8, D-2, D-3, D-4). * docs: restructure requirements registry and remove requirements guide Replace the populated requirements.md with a clean template-based registry and remove the separate requirements-guide.md, consolidating authoring conventions into AGENTS.md and the registry's own intent section. * docs: add PR template with traceability enforcement and enrich PRD with examples - Add .github/PULL_REQUEST_TEMPLATE.md enforcing AGENTS.md traceability rules: issue linking, requirement ID listing (R/NFR only, no C IDs), requirement update confirmation or justification, and sensitive-change flagging - Enrich docs/prd.md with illustrative placeholder examples for all sections (personas, scope, metrics, constraints, open questions), clearly marked with HTML placeholder comments for replacement with real content - Minor: remove requirements guide reference from story.yml acceptance criteria description (guide was removed from docs in earlier commit) * docs: remove glossary.md * Apply suggestions from code review Co-authored-by: Tobias Koch <tobias.koch@uni-tuebingen.de> * docs: clarify C-ID placement in task issue template Constraint IDs (C-<NN>) may only be referenced in Technical Notes, never in the Requirement IDs field. Updated the field descriptions and placeholder to enforce this rule explicitly for both human contributors and AI agents. --------- Co-authored-by: sven1103 codex agent <261423644+sven1103-agent@users.noreply.github.com> Co-authored-by: Tobias Koch <tobias.koch@uni-tuebingen.de> Co-authored-by: Masterful Biscuit Agent (MBA) <263631132+KochTobi-Agent@users.noreply.github.com> * docs: add Requirements Documentation & Workflow section to README (#1393) Adds a comprehensive section explaining the requirements-driven development process to the README, making it accessible to collaborators and stakeholders. Covers the requirement ID scheme, docs/requirements.md as the source of truth, the Story → Task → PR traceability chain, and the golden rule for new capabilities. * 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> * Ignore local agent config files and dirs * Add .worktrees to gitignore * feat(raw-data): Add Measurement Name column to raw data view (#1411) Add Measurement Name column to the raw data grid for both genomics (NGS) and proteomics (PxP) measurement types. This allows users to correlate measurement names with raw data without switching between measurement view and raw data views. Changes: - Add measurementName to v_ngs_measurement_sample_json and v_pxp_measurement_sample_json SQL views - Add measurementName field to LocalRawDatasetNgsEntry and LocalRawDatasetPxpEntry JPA entities - Add measurementName to RawDatasetInformationNgs and RawDatasetInformationPxP API records - Update convert methods in LocalRawDatasetRepositoryImpl - Add Measurement Name column to both NGS and PxP grids in RawDataDetailsComponent Refs: #1403 Co-authored-by: Sven Fillinger <sven.fillinger@qbic.uni-tuebingen.de> --------- Co-authored-by: Sven F. <9976560+sven1103@users.noreply.github.com> Co-authored-by: sven1103 codex agent <261423644+sven1103-agent@users.noreply.github.com> Co-authored-by: Masterful Biscuit Agent (MBA) <263631132+KochTobi-Agent@users.noreply.github.com> Co-authored-by: KochTobi <kochtobi@users.noreply.github.com> Co-authored-by: Sven Fillinger <sven.fillinger@qbic.uni-tuebingen.de>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.