---
name: reviewing-long-lived-specs
description: Use when reviewing a PR or pre-merge change that creates, moves, or edits canonical specs, architecture docs, product specs, guardrails, or long-lived policy documents.
---

# Reviewing Long-Lived Specs

## Core Principle

Canonical specs must serve future project evolution. They should describe durable behavior, architecture, constraints, ownership, rationale, and enforcement rules — not narrate the current task, PR, branch, commit, agent, or review process.

## Review Workflow

1. **Identify canonical surfaces**
   - Check all changed files under `specs/`, skills, guardrails, architecture docs, product specs, and repo entry docs such as `AGENTS.md`.
   - Separate canonical specs from temporary plans, handoffs, task notes, and PR descriptions.

2. **Scan for one-off wording**
   Treat these as suspicious in canonical specs:
   - PR / issue / task references used as requirements (`PR #...`, `#t...`, branch names, commit hashes, reviewer names, agent names).
   - Time-boxed language (`this PR`, `this task`, `this batch`, `current branch`, `Phase N deliverable`) unless it defines a lasting lifecycle model.
   - Frozen audit counts presented as eternal truth instead of generated inventory or dated evidence.

3. **Preserve durable content**
   Do not delete useful decisions. Rewrite one-off wording into stable forms:
   - `completed in #t651` -> `currently typed` or `already migrated`.
   - `tracked in #t663` -> `requires optional-body adapter support`.
   - `PR #457 added...` -> `The canonical layout is...`.
   - `run from branch X` -> `Use the repo-root guardrail script...`.

4. **Check source-of-truth ownership**
   - Ensure the spec has a canonical path and related-spec links that will stay valid after merge.
   - If specs and guardrails correspond by domain/subdomain, verify names and paths match.
   - Product behavior belongs in product specs; implementation constraints belong in architecture/API specs; executable checks belong in guardrails.

5. **Validate current-state claims**
   - If a spec classifies code state, verify it against the current diff or guardrail output.
   - A canonical classification must be updated in the same PR as code that changes the classification.
   - Counts should say how to regenerate them or be framed as an inventory snapshot, not as timeless facts.

## Blocker Criteria

Block the merge when a canonical spec:

- Depends on a PR/task/commit/branch reference to understand the rule.
- Says a migration is pending when the PR has completed it, or says completed when code does not match.
- Contains stale route, DTO, guardrail, or ownership facts after the code changed.
- Moves specs without updating canonical path links or corresponding guardrails.
- Uses temporary planning language as normative policy.

## Pass Criteria

Approve the spec portion when:

- The spec reads correctly six months from now without chat/PR context.
- Durable rationale and trade-offs are preserved.
- Current-state classifications match code and are easy to refresh.
- Guardrails or validation commands are named as long-lived checks, not one-time review evidence.
- Any remaining history is clearly non-normative provenance.

## Verification Hints

Use targeted grep before final approval:

```bash
rg -n 'PR #|#t[0-9]+|commit|branch|this PR|this task|current branch|tracked in #' specs AGENTS.md guardrails skills
```

Review hits manually. Some may be acceptable in non-canonical docs or explicit provenance, but canonical specs should not require them for normative meaning.