fujian_water_biz_doc/.specify/templates/spec-template.md

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)

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.