-
Type:
Task
-
Resolution: Unresolved
-
Priority:
Unknown
-
None
-
Component/s: Cross Spec Consistency
-
None
-
Not Needed
Summary
PR #1992 adds specification standards to CONTRIBUTING.md, but there is no agreed definition of which documents those standards apply to. The location-based definition proposed in the PR ("any Markdown document at the top level of a subdirectory inside source/") misclassifies legitimate non-spec files that live alongside specs, e.g. source/max-staleness/max-staleness-tests.md.
Motivation
Who is the affected end user?
Spec authors, reviewers, new engineers, external readers of the specifications repo, and LLM-based tooling that reads the repo (e.g. via AGENTS.md).
How does this affect the end user?
Without a definition, readers cannot reliably tell which documents must follow the specification standards
How likely is it that this problem or use case will occur?
Every new or modified document under source/ raises the question, and several non-spec Markdown files already exist (e.g. source/index.md, source/drivers-mantras.md, source/max-staleness/max-staleness-tests.md).
If the problem does occur, what are the consequences and how severe are they?
Standards may be applied inconsistently or to the wrong documents, causing review churn and confusion
Is this issue urgent?
No
Is this ticket required by a downstream team?
No
Is this ticket only for tests?
No
Acceptance Criteria
A single, unambiguous rule for identifying a specification document is agreed by the spec owners and added to CONTRIBUTING.md.
- related to
-
DRIVERS-3693 Determine what to do about the Status line in specifications
-
- Backlog
-