During my dev career, I have many times witness the case that business requirements (and thus, consequently, functional specifications) were not treated with the same scrutiny as the source code. The source code usually passes at-least from one human reviewer that actively tries to improve the quality of it, there are standards defined regarding the quality of the code, and formal tools (usually git) are used to track the changes and the reason behind them.

Business Requirements are ofter described in issues on a separate issue management system and are usually incomplete and separated from source code. Thus it is easier for the code and requirements to fall out of sync (ie a new issue is created for an updated Business Requirement, but the old commits still point to the old issue that holds an outdated business requirement).

To handle both the issue of sub-par business requirements and their "distance" from the codebase I'm thinking of defining a "standard" that would require the business requirements to be stored in markdown files inside the source code repository.

My current approach is:

• Possibly split business requirements from functional requirements (functional requirements are written based on business requirements but are more technical)
• Allow hierarchical structures to be defined by referencing parent requirements.
• Provide meta-data (like front-matter in static site generators)
• Link acceptance criteria to test cases

A command-line utility will be built that will:

• enforce Definition of Ready by presenting requirements without acceptance criteria as not ready
• provide the current status of the project based on the state of each business requirement (not ready, no tests are written, tests are written but fail, tests are written and passing)
• be able to run on pre-commit or pre-merge to either indicate issues or fail the commit/merge
• be able to run on ci/cd to generate and publish the current state of the project

So, what are your opinions about this? Do you see any value on this approach? What would you require to use this approach instead of what you are already using?