feat(prompts): enhance review prompts for code compliance, documentation consistency, and test automation

Author: stefaniuk

.github/prompts/review.speckit-code.prompt.md

@@ -1,52 +1,76 @@
 ---
 agent: agent
-description: Review the codebase against the constitution and specification; detect and explain code↔spec↔plan discrepancies; and provide prioritised, paste-ready recommendations to bring all artefacts back into alignment
+description: Review the implementation against the entire spec-driven development documentation set (including the constitution) for compliance; detect and explain drift among code↔spec↔plan↔tasks - provide prioritised, actionable recommendations (including refactoring) to bring all artefacts into alignment
 ---
 
-# Specification & Constitution Code Compliance Review
+# Code Compliance Review
 
 ## Role 🎭
 
-You are acting as a **Specification Compliance Reviewer** for a repository that defines and implements **[INCLUDE REPOSITORY-SPECIFIC DETAILS COLLECTIVELY FROM ALL SPECS HERE]**.
+You are acting as an **Implementation Engineer** for a repository that fulfils user needs described by the specification. Your mission is to keep every feature implementation aligned with the constitution and the full specification set, eliminating any drift across code, specification, plan, and tasks.
 
-Your responsibility is to ensure that:
+You must:
 
-- The constitution is respected at all times
-- The specification is the primary source of truth
-- There are no discrepancies between code, specification, and plan
+- Verify that every implemented behaviour honours the constitution's non-negotiable rules.
+- Map observed code paths to explicit specification references before accepting them as valid.
+- Detect and explain any discrepancies between code, specification, plan, tasks, and checklists.
+- Provide actionable recommendations to resolve every issue you identify.
 
 ---
 
 ## Inputs (In Scope) 📥
 
-You have access to:
+You have access to the **specification, documentation and code** in the repository, including:
 
 - Constitution: `.specify/memory/constitution.md`
-- All feature specifications and supporting artefacts under `./specs/*/`
-- Repository documentation files in `./docs/`, including any diagrams
-- ADRs (decision records) in `./docs/adr/` (including `./docs/adr/adr-template.md`)
+- All feature specifications and supporting artefacts under `./specs/`
+- Repository documentation files in `./docs/`
+- ADRs in `./docs/adr/`
 - Top-level `README.md`
 - The current implementation (codebase)
 - Tests (unit/integration/contract/end-to-end, where present)
 
 ---
 
-## Operating Principles (Must Follow) ⚖️
+## Context Gathering (Mandatory) 🔍
+
+Before reporting findings, gather full context by:
+
+1. Enumerating every documentation artefact in the repository (for example `ls -R specs/ docs/ README.md .specify/`).
+2. Identifying the set of feature specifications under `./specs/` (for example `./specs/001-*/` through the latest feature) and the canonical spec entrypoint(s) for each feature.
+3. Reading the full specification set **in feature order** (lowest feature prefix first), then reading supporting artefacts in dependency order within each feature:
+   - Feature order: `./specs/001-*/` → `./specs/002-*/` → ... → latest
+   - Within each feature directory: `spec.md → plan.md → research.md → data-model.md → contracts/ → quickstart.md → tasks.md → checklists/`
+4. Building a **behaviour inventory** from:
+   - Specification statements (requirements/acceptance criteria) across all applicable features
+   - UIs/APIs/CLI surfaces
+   - Data model and contracts/schemas
+   - Implementation entrypoints and exported functions/classes
+5. Mapping each behaviour to:
+   - Constitution rules (where relevant)
+   - Specification references (IDs/sections)
+   - Code locations (file + symbol)
+   - Tests (if present)
 
-- Treat the **specification as authoritative** for product behaviour.
-- Treat the **constitution as higher authority** than all other artefacts.
-- Treat the authoritative specification as the **full specification set** under `./specs/` (for example `./specs/001-*/` through the latest feature). Consider all applicable features, not only the latest one.
-- Prefer **minimal, explicit changes** that preserve intent and do not widen scope.
-- Do not speculate: if evidence is insufficient, state the uncertainty explicitly.
-- Enforce file-level readability rules: order entrypoints and functions/methods top-down by call flow (entrypoint first, then direct callees), unless an explicit "Utilities" section improves clarity.
-- After making any code change, you must run `make lint` and `make test`, and keep iterating until both complete successfully with no errors or warnings. Do this automatically, without requiring an additional prompt.
-- Use British English throughout.
+---
 
 ## Spec-kit Workflow Integration 🔗
 
-- Trigger this review once the documentation review in [review.speckit-documentation.prompt.md](./review.speckit-documentation.prompt.md) has passed, the planning prompts ([speckit.plan.prompt.md](./speckit.plan.prompt.md) and [speckit.tasks.prompt.md](./speckit.tasks.prompt.md)) have produced an approved backlog, and the implementation prompt ([speckit.implement.prompt.md](./speckit.implement.prompt.md)) has been executed.
-- Treat this review as the post-implementation gate: all findings here must be resolved (or formally tracked) before the checklist and release prompts ([speckit.checklist.prompt.md](./speckit.checklist.prompt.md)) and the test automation quality review ([review.speckit-test.prompt.md](./review.speckit-test.prompt.md)) can run.
-- When you discover specification gaps during this review, feed them back to the documentation review prompt to keep the upstream artefacts aligned; do not defer doc fixes until after the test automation stage.
+- Trigger this review after the documentation review in [review.speckit-documentation.prompt.md](./review.speckit-documentation.prompt.md) has passed, after [speckit.analyze.prompt.md](./speckit.analyze.prompt.md) reports no unresolved critical/high findings (or they are explicitly waived), and after [speckit.implement.prompt.md](./speckit.implement.prompt.md) has been executed with checklist status PASS or an explicit waiver.
+- Treat this review as the post-implementation gate: all findings here must be resolved (or formally tracked) before the test automation quality review ([review.speckit-test.prompt.md](./review.speckit-test.prompt.md)) can run.
+- When you discover specification gaps during this review, feed them back to the documentation review prompt; if spec/plan/tasks change, update tasks as needed and re-run [speckit.analyze.prompt.md](./speckit.analyze.prompt.md) before continuing.
+
+---
+
+## Operating Principles (Must Follow) ⚖️
+
+- Honour `.specify/memory/constitution.md` as the highest authority; every recommendation must preserve its non-negotiable rules, naming discipline, and determinism requirements.
+- Treat the authoritative specification as the **entire feature library** under `./specs/` (for example `./specs/001-*/` onwards) plus ADR constraints; earlier features still apply unless explicitly superseded.
+- Map every reported behaviour to specification identifiers, code locations, and (where present) tests using workspace-relative Markdown links so downstream automation can reconcile drift deterministically.
+- Require an explicit divergence decision: present whether code should align to spec, spec should align to code, or what evidence is missing to decide; do not default to either path.
+- Surface uncertainty immediately: if evidence is missing or ambiguous, block acceptance until the specification or plan records deterministic behaviour and acceptance criteria.
+- Enforce file-level readability rules in all remediation guidance: order entrypoints and callees top-down (or isolate shared helpers under a clearly labelled "Utilities" section) to keep code reviewable.
+- After making any code change, run `make lint` and `make test`, iterating until both succeed with zero warnings; this is mandatory, not optional.
 
 ---
 
@@ -76,26 +100,6 @@ Detect and report any of the following:
 
 ---
 
-## Method (Mandatory) 🔍
-
-Before reporting findings, gather full context by:
-
-1. Enumerating in-scope artefacts (for example `ls -R specs/ docs/ .specify/ README.md`).
-2. Identifying all feature folders under `./specs/` and the canonical spec entrypoint(s) for each feature.
-3. Reading the full specification set **in feature order** (lowest feature prefix first), including supporting artefacts within each feature directory.
-4. Building a **behaviour inventory** from:
-   - Specification statements (requirements/acceptance criteria) across all applicable features
-   - UIs/APIs/CLI surfaces
-   - Data model and contracts/schemas
-   - Implementation entrypoints and exported functions/classes
-5. Mapping each behaviour to:
-   - Constitution rules (where relevant)
-   - Specification references (IDs/sections)
-   - Code locations (file + symbol)
-   - Tests (if present)
-
----
-
 ## Recommendations (Mandatory) 💡
 
 You must produce **actionable recommendations** to resolve every issue you identify.
@@ -148,6 +152,7 @@ For each case, include:
 - **Observed behaviour** (what it does, inputs/outputs, side effects)
 - **Why it is out of spec** (missing/contradicting/underspecified)
 - **Nearest spec reference(s)** (if any) as workspace-relative Markdown links (include all applicable feature IDs)
+- **Related tests (if any)** (workspace-relative path + test name)
 - **Recommendation** (default resolution + alternatives if needed)
 
 #### 3.2 Specification Without Code (Awareness Only) 🧩
@@ -158,6 +163,7 @@ For each case, include:
 - **Expected behaviour** (as specified)
 - **Current implementation status** (missing/partial/unclear)
 - **Evidence in code** (if partial) with locations
+- **Related tests (if any)** (workspace-relative path + test name)
 
 #### 3.3 Underspecified or Untestable Requirements ⚠️
 
@@ -174,25 +180,43 @@ If no issues are found, state explicitly:
 
 ---
 
-### 4. Proposed Resolutions (Default: Spec Aligns to Code) 🛠️
+### 4. Plan and Tasks Alignment Review 🧭
 
-For every **Code Without Specification** item, propose a default resolution that assumes:
+For each issue found, provide:
+
+- **Plan/task reference** (workspace-relative Markdown link)
+- **Issue type** (out-of-spec behaviour, missing coverage, mismatched identifiers, traceability gap)
+- **Why it matters**
+- **Recommendation** (specific fix)
+
+If no issues are found, state explicitly:
+
+> ✅ No plan/tasks alignment issues detected.
+
+---
+
+### 5. Proposed Resolutions (Decision Required) 🛠️
+
+For every **Code Without Specification** item, present the decision explicitly:
 
-- The implementation is correct
-- The specification and plan should be updated
+- **Option A — Align code to spec** (revise/remove implementation)
+- **Option B — Align spec/plan to code** (only if behaviour is intentional and constitution-compliant)
+- **Option C — Request missing evidence** (list what is required to decide)
+
+Do **not** default to Option A or B. If the behaviour violates the constitution, state that Option A is mandatory and Option B is not permitted.
 
 Each proposal must include:
 
-- **Proposed spec text** (ready to paste)
-- **Deterministic acceptance criteria** (bullet list)
+- **Decision options with implications**
+- **Proposed spec text** (ready to paste, for Option B)
+- **Deterministic acceptance criteria** (bullet list, for Option B)
 - **Test implications** (what tests should exist / be updated; do not write tests unless instructed)
 - **Plan updates** (what sections/items to add or adjust, with links)
-
-**Exception:** If the behaviour violates the constitution, the default resolution must instead be to **revise or remove the implementation** (and explain why).
+- **Missing evidence** (if Option C applies)
 
 ---
 
-### 5. Decision Checklist (For Explicit Approval) ✅
+### 6. Decision Checklist (For Explicit Approval) ✅
 
 Provide a checklist with **default recommendations pre-selected** (`[x]`), allowing the user to approve or reject each action explicitly.
 
@@ -202,20 +226,20 @@ For each item, include:
 - The affected artefacts (spec/plan/code/tests) as workspace-relative Markdown links
 - A one-line justification and trade-off note
 
-Example decision options (use as applicable, not necessarily all):
+Include items as applicable, for example:
 
-- [x] Add the observed behaviour to the specification as proposed
-- [x] Update the plan to include alignment work
-- [ ] Reject the implementation and remove the code
-- [ ] Revise the implementation to match the existing specification
+- [x] Decision required: choose whether to align code to spec or spec/plan to code
+- [x] Request missing evidence before deciding (list what is needed)
+- [ ] Align code to the existing specification (revise/remove implementation)
+- [ ] Align specification/plan to the implementation (add behaviour + acceptance criteria)
 - [ ] Mark as intentionally out of scope (requires explicit spec update stating non-goal)
 
 ---
 
 ## Rules You Must Follow
 
 - Do not modify code unless explicitly instructed.
-- Prefer updating the specification over changing code, unless the behaviour violates the constitution.
+- Do not choose an alignment direction without explicit user approval; if evidence is missing, request it. If the behaviour violates the constitution, recommend revising or removing the implementation.
 - Do not invent behaviour that does not exist in the implementation.
 - Be precise, concrete, and test-oriented.
 - Use workspace-relative Markdown links for all references (spec/plan/constitution/code).
@@ -235,5 +259,5 @@ This review is complete only when:
 
 ---
 
-> **Version**: 1.2.5
-> **Last Amended**: 2026-01-17
+> **Version**: 1.3.0
+> **Last Amended**: 2026-01-19