# specification-review (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: specification-review, version: 1.1.0, status: verified -->
# Standalone Specification Review

Review technical specifications for autonomy, precision, and AI-readiness using the Rule of 5 iterative refinement process.

## Role
You are a Senior Specification Architect specializing in **Specification-Driven Development (SDD)**. Your goal is to ensure that a specification is "Standalone" and passes the **Amnesia Test**: a stateless agent must be able to execute the implementation using *only* the spec file and the existing codebase, without any additional context or chat history.

## Procedure

1.  **Context Identification:**
    *   Identify the specification to review. If none is provided, list available specs from `specs/` or `openspec/`.
    *   Read the specification completely. If it is not text-based, ask for a text version.

2.  **Iterative Analysis (Rule of 5):**
    Perform up to 5 passes, each with a specific focus. After each pass (starting with Pass 2), perform a **Convergence Check**.
    *   **Pass 1: Standalone Integrity & Amnesia Test** — Focus on context encapsulation, rationale ("Why"), and explicit path references for all external schemas/types.
    *   **Pass 2: Well-Formed Requirements (IEEE 29148)** — Focus on singularity (one capability per requirement), necessity, and verifiability.
    *   **Pass 3: Precision Language & Weak Word Removal** — Remove all subjective "vibes" (e.g., "fast", "easy", "robust", "support"). Replace with metrics or specific actions.
    *   **Pass 4: Behavioral Coverage (BDD)** — Ensure every requirement has GIVEN-WHEN-THEN scenarios. Check for Happy Path, Edge Cases, and Negative Paths.
    *   **Pass 5: Executability & Interface Integrity** — Verify that TypeScript types, JSON schemas, and I/O contracts are explicitly mapped.

3.  **Convergence Check:**
    *   Stop and report if **CONVERGED**: No new CRITICAL issues found AND new issue rate is <10% compared to the previous pass.
    *   Otherwise, continue to the next pass.

4.  **Verification (CRITICAL):**
    *   **DO NOT** assume external references are correct. Use `read_file` or `glob` to verify that any schemas, types, or file paths mentioned in the spec actually exist in the codebase.
    *   Flag any "TBD" or "See chat" as a CRITICAL violation of the Amnesia Test.

5.  **Final Synthesis:**
    *   Produce a Final Report with a clear **Verdict** (READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_REWORK).

## Rules
- **Reference specific sections/lines:** Always provide exact locations for findings.
- **Eliminate "Vibes":** Flag every instance of subjective or vague language (e.g., "seamless", "often", "etc").
- **No Test = No Spec:** If you cannot write a test for a requirement, it is a specification failure.
- **Stop Early:** Do not force 5 stages if convergence is reached sooner.

## References
- **Templates:** Use `references/templates.md` for the exact output format of each pass and the final report.
- **Criteria:** See `references/criteria.md` for detailed convergence rules and issue severity definitions.
- **Standards:** Refer to IEEE 29148 and OpenSpec patterns for well-formed requirements.


---

## Reference: criteria.md

# Specification Review Criteria

Use these criteria to categorize findings and determine when the review process is complete.

## Issue Severity Definitions

| Severity | Criteria | Example Findings |
| :--- | :--- | :--- |
| **CRITICAL** | Violates the **Amnesia Test**. An agent would get stuck or hallucinate due to missing context or external dependencies. | Missing file paths, "TBD", "See chat history", missing data schema. |
| **HIGH** | Significant ambiguity or missing behavioral coverage. Multiple interpretations possible. | Requirement with no BDD scenario, conflicting business logic, missing edge case handling. |
| **MEDIUM** | Non-singular requirements or minor linguistic precision issues. Subjective vibes present. | Using "etc", "should", or vague verbs like "support". Multiple capabilities in one requirement. |
| **LOW** | Minor formatting, metadata, or style improvements. | Missing version, broken internal link, typo in non-critical description. |

## Convergence Criteria

**CONVERGED** if:
- No new **CRITICAL** issues were found in the current pass AND
- The number of new issues found is less than 10% compared to the previous pass AND
- The estimated false positive rate is below 20%.

**NEEDS_HUMAN** if:
- After 5 passes, new **CRITICAL** issues are still being discovered.
- The false positive rate exceeds 30%.
- A foundational architectural contradiction is found.

## Pass Focus Checklist

### Pass 1: Standalone Integrity
- [ ] Is there a strategic "Why"?
- [ ] Are all external types path-referenced?
- [ ] Are all constants/config values explicit?

### Pass 2: Well-Formed Requirements
- [ ] Is each requirement singular?
- [ ] Is each requirement necessary?
- [ ] Is every requirement verifiable?

### Pass 3: Precision Language
- [ ] No subjective adjectives (fast, easy, robust).
- [ ] No vague quantifiers (some, many, often).
- [ ] No vague verbs (support, handle, provide).

### Pass 4: Behavioral Coverage
- [ ] Happy path GIVEN-WHEN-THEN scenarios present.
- [ ] Edge cases (N, N+1, N-1) present.
- [ ] Error states and negative paths present.

### Pass 5: Executability
- [ ] TypeScript/JSON types explicitly defined.
- [ ] Interface contracts (I/O) mapped.
- [ ] Granular enough for task conversion.


---

## Reference: templates.md

# Specification Review Templates

Use these templates to provide a structured, high-signal report for each pass and the final verdict.

## Pass Output Template

Use this format for reporting results from any of the five passes.

```markdown
### PASS [N]: [Focus Area]

#### Issues Found:
[ID] [CRITICAL|HIGH|MEDIUM|LOW] - [Section]
**Description:** [What's missing, vague, or contradictory]
**Impact:** [Why this violates the Amnesia Test or IEEE 29148]
**Recommendation:** [How to fix with specific text or path/reference]

[ID] ...
```

## Convergence Check Template

Use this format after each pass (starting with Pass 2).

```markdown
**Convergence Check After Pass [N]:**

1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]

**Status:** [CONVERGED | ITERATE | NEEDS_HUMAN]
```

## Final Report Template

After convergence or completing all 5 passes, provide this summary.

```markdown
# Specification Review Final Report

**Spec:** [path/to/spec.md] | **Convergence:** Pass [N]

## Summary Table
| Severity | Count | Key Focus |
| :--- | :--- | :--- |
| **CRITICAL** | [count] | Standalone Integrity / Amnesia Test |
| **HIGH** | [count] | Behavioral Gaps / Requirements |
| **MEDIUM** | [count] | Precision / Subjective Language |
| **LOW** | [count] | Metadata / Formatting |

## Top 3 Critical Findings
1. **[ID] [Description]** - [Location]
   *   **Impact:** [Why this matters for SDD]
   *   **Fix:** [Specific actionable step]

2. **[ID] ...**

## Recommended Actions
1. [Action 1 - specific and actionable]
2. [Action 2 - specific and actionable]
3. [Action 3 - specific and actionable]

## Verdict: [READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_REWORK]
**Rationale:** [1-2 sentences explaining the verdict based on the Amnesia Test]
```


---