# 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.