126 lines
5.9 KiB
Markdown
126 lines
5.9 KiB
Markdown
# Feature Specification: [FEATURE NAME]
|
|
|
|
**Feature Branch**: `[###-feature-name]`
|
|
**Created**: [DATE]
|
|
**Status**: Draft
|
|
**Input**: User description: "$ARGUMENTS"
|
|
|
|
## Document Scope & Sources *(mandatory)*
|
|
|
|
- **Target documents**: [List the exact files intended to be updated]
|
|
- **Primary source of truth**: [List the authoritative main docs]
|
|
- **Reference sources**: [List allowed Archive/guides/supporting docs]
|
|
- **Scope decision**: [State whether this request is in scope, needs confirmation, or is out of scope]
|
|
|
|
## Repository Scope *(mandatory)*
|
|
|
|
- **Target repos**:
|
|
- `water-docs`: [Required / Not Required]
|
|
- `water-backend`: [Required / Not Required]
|
|
- `water-frontend`: [Required / Not Required]
|
|
- **Expected delivery type**: [Document closure / Code evidence alignment / Backend implementation / Frontend implementation / Mixed]
|
|
- **Out of scope for this round**: [List anything explicitly excluded]
|
|
|
|
## Code Baseline *(mandatory for brownfield work)*
|
|
|
|
- **Backend baseline**: [commit SHA / branch / N/A]
|
|
- **Frontend baseline**: [commit SHA / branch / N/A]
|
|
- **Baseline capture rule**: [How the implementation evidence will be tied back to a specific code version]
|
|
|
|
## Evidence Scope *(mandatory)*
|
|
|
|
- **Document evidence required**: [Which formal docs or specs must be updated]
|
|
- **Backend evidence required**: [Controllers / services / tests / compile / N/A]
|
|
- **Frontend evidence required**: [Pages / routes / build / smoke / N/A]
|
|
- **Verification artifacts required**: [baseline.md / docs-validation.md / backend-validation.md / frontend-validation.md / final-verdict.md]
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
<!--
|
|
For this repository, user stories should describe independently reviewable
|
|
document-maintenance, implementation, or verification outcomes.
|
|
-->
|
|
|
|
### User Story 1 - [Brief Title] (Priority: P1)
|
|
|
|
[Describe the primary independently reviewable outcome in plain language]
|
|
|
|
**Why this priority**: [Explain the value and why it has this priority level]
|
|
|
|
**Independent Test**: [Describe how this can be reviewed independently]
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
|
|
---
|
|
|
|
### User Story 2 - [Brief Title] (Priority: P2)
|
|
|
|
[Describe this user journey in plain language]
|
|
|
|
**Why this priority**: [Explain the value and why it has this priority level]
|
|
|
|
**Independent Test**: [Describe how this can be tested independently]
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
|
|
---
|
|
|
|
### User Story 3 - [Brief Title] (Priority: P3)
|
|
|
|
[Describe this user journey in plain language]
|
|
|
|
**Why this priority**: [Explain the value and why it has this priority level]
|
|
|
|
**Independent Test**: [Describe how this can be tested independently]
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when the formal document conclusion and the current code evidence do not align?
|
|
- What happens when a requested change is only supported by Archive history but not by current main docs?
|
|
- How does the workflow handle broken relative links, unstable anchors, or Mermaid syntax regressions introduced by edits?
|
|
- What happens when the backend and frontend are on different commits and the feature must still produce a single verdict?
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: Specification MUST identify the exact target documents that will be changed.
|
|
- **FR-002**: Specification MUST identify the main source-of-truth documents that govern the change.
|
|
- **FR-003**: Specification MUST identify which repositories are in scope and which are explicitly out of scope for the round.
|
|
- **FR-004**: Specification MUST record backend/frontend code baselines or explicitly mark them N/A.
|
|
- **FR-005**: System MUST preserve the single-source-of-truth model and MUST NOT assume creation of new parallel formal documents unless explicitly approved.
|
|
- **FR-006**: Specification MUST list the validation actions needed after the change, including file validation and any required link or Mermaid checks.
|
|
- **FR-007**: Specification MUST state whether management ledgers need updates in `01_Project_Progress.md` and `03_Task_Checklist.md`.
|
|
- **FR-008**: Specification MUST capture cross-document consistency impacts when terminology, numbering, diagrams, references, or interface contracts may change.
|
|
- **FR-009**: Specification MUST define what evidence artifacts are required before the feature can be marked complete.
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
|
|
- **Target Document**: A Markdown file that will be modified as part of the request.
|
|
- **Source of Truth Document**: A main document or governance document that constrains allowed conclusions.
|
|
- **Reference Source**: Archive or guide material used only for verification, traceability, or scope judgment.
|
|
- **Code Baseline**: A backend or frontend commit reference used to anchor brownfield implementation evidence.
|
|
- **Evidence Artifact**: A document under `specs/` or `evidence/` that records validation, code proof, or the final verdict.
|
|
- **Ledger Update**: A required change to project progress or task checklist records after important modifications.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: Every target document and in-scope repository is explicitly named before implementation begins.
|
|
- **SC-002**: Every completed change can be traced to at least one source-of-truth or approved reference source.
|
|
- **SC-003**: Required validation and evidence actions are explicitly listed and can be executed without ambiguity.
|
|
- **SC-004**: Reviewers can determine from the spec alone whether ledger updates, code-baseline capture, and cross-document sync are required.
|
|
- **SC-005**: The feature can produce a final verdict without relying on unstated assumptions about backend or frontend implementation status.
|