| name | freshness-gate |
| description | Use this skill when checking whether requirements, SDD documents, ADRs, code, tests, approvals, or deployment evidence are stale relative to their source references. Applies before implementation, review, approval, release, or when a user asks if docs/code/tests are up to date. |
Freshness Gate
Use this skill to detect stale context before work proceeds.
Purpose
Freshness is a first-class quality signal. A document, approval, test, or implementation can be correct for an old version and wrong for the current one.
Workflow
- Identify the artifact under review:
- requirement source
- SDD document
- ADR
- code change
- test plan
- approval
- deployment or incident evidence
- Identify upstream sources:
- Jira / Confluence / PRD / uploaded requirement
- earlier SDD stage
- ADRs
- code paths
- tests
- Compare freshness evidence:
- timestamps
- commit SHA
- blob SHA
- document version
- approval version
- changed file list
- Classify status.
- Recommend the smallest repair path.
Status Values
Fresh - artifact is current relative to known upstream sources.Stale - upstream changed after this artifact was created, approved, or verified.Unknown - missing version evidence prevents a confident answer.Blocked - stale or unknown status must be resolved before proceeding.
Common Checks
| Check | Stale When |
|---|
| Requirement to spec | requirement source changed after spec version |
| Spec to design | spec changed after design version |
| Design to code | implementation changed outside design scope or design changed after implementation |
| Test to requirement | tests do not reference latest requirement/spec IDs |
| Approval to document | document blob changed after approval |
| Deployment to code | deployed version does not match reviewed commit |
Output Format
# Freshness Gate Report
## Verdict
Fresh | Stale | Unknown | Blocked
## Evidence
| Artifact | Version / Time | Source | Status |
|---|---|---|---|
## Findings
- [Finding]
## Minimal Repair Path
1. [Step]
## Open Risks
- [Risk]
Rules
- Do not approve work based on unpinned "latest" context.
- If a version is missing, say
Unknown; do not infer freshness.
- Prefer commit/blob SHAs over timestamps when available.
- If freshness is blocked, stop implementation and ask for source update or approval.
