---
name: architect-lifecycle
description: |
  Your enterprise AI architect, in lifecycle-audit mode. Applies Doc Lifecycle
  discipline to AI artifacts (prompts, evals, model cards, runbooks,
  guardrails, agent manifests). Adds Last-reviewed / Review-cadence / Status
  frontmatter, recommends cadences tuned to AI decay patterns, and produces
  a staleness check plan. Use when creating, auditing, or organizing AI
  artifacts.
triggers:
  - audit our prompts
  - how often should we review
  - is this prompt stale
  - our docs are out of date
  - what's the lifecycle for evals
  - prompt lifecycle
  - eval lifecycle
  - artifact freshness
  - stale prompts
  - frontmatter check
---

<!-- MIRRORED FROM: AI-Architect/skills/architect-lifecycle/SKILL.md -->
<!-- MIRRORED AT: 2026-04-28 -->

# AI Doc Lifecycle

AI artifacts rot faster than general software docs because the models, datasets, and adversaries they describe all move. Applying Doc Lifecycle frontmatter makes rot visible and fixable instead of silent and accumulating.

## Why AI artifacts need tighter cadences than software docs

| Artifact | Decay trigger | Suggested cadence |
|----------|---------------|-------------------|
| Prompts | Model update, capability drift | Quarterly + on every model bump |
| Evals | Dataset drift, capability shift | On every model bump |
| Model cards | Performance claims stale | Quarterly |
| Runbooks | API changes, infra migration | Quarterly |
| Guardrails | Adversary evolution | Monthly |
| Agent manifests | Tool set, model, or prompt changes | On every material change |
| ADRs | Superseded by new ADR, not stale | Never (immutable) |
| Retention / privacy policies | Regulatory change | Annually + on change |

Cadences are defaults. Tune by how fast the domain moves (e.g. guardrails for an external-facing customer agent need monthly review at minimum).

## Frontmatter schema

Every non-immutable governance artifact carries:

```markdown
---
Last reviewed: YYYY-MM-DD
Review cadence: quarterly | monthly | annually | on-change | on-model-bump | ad-hoc
Status: active | draft | archived | deprecated | superseded
---
```

Additional fields for AI artifacts, when applicable:

```markdown
Model compatibility: claude-sonnet-4-6 | claude-opus-4-7 | gpt-5 | ...
Owner: {team or person}
Reproducibility pin: {model-version, prompt-version, tools-version, data-snapshot}
```

## Procedure

When invoked:

1. **Identify the artifact type** (prompt, eval, model card, runbook, guardrail, ADR, policy).
2. **Check for frontmatter.** If missing, add per the schema.
3. **Assign cadence** from the table above unless domain-specific context suggests tighter.
4. **Evaluate staleness.** If `Last reviewed` is older than `cadence * 1.5`, flag it. If older than `cadence * 2`, flag urgently.
5. **Recommend next actions.** Concrete: "review by {date}", "retire and replace with ADR-XXXX", "bump cadence to monthly because adversary pressure increased."
6. **Offer to batch-audit** if the request was scoped to one artifact but similar ones exist nearby.

## Staleness check plan

For a whole corpus (one repo, one team's artifacts):

1. Walk the governance roots: prompt library, evals folder, model cards, runbooks, guardrails.
2. Parse frontmatter from each file.
3. Compute days since `Last reviewed` vs. cadence window at 1.5x threshold.
4. Report: compliant count; overdue count with paths; missing-frontmatter count with paths.
5. For AI-specific artifacts, cross-check `Model compatibility` against the currently deployed model version; flag mismatches.

Automate this as a 50-100 line script; run monthly in CI or on a scheduled agent.

## Archival rule

When an artifact is superseded:

1. Update `Status: superseded` on the old file.
2. Move it to `archive/` in the same directory.
3. If the artifact is a prompt, eval, or guardrail still referenced by a live agent, add a redirect note pointing to the replacement.

## When to skip

Skip for truly ephemeral artifacts: a one-off debugging prompt, a throwaway eval. Frontmatter is for governance, not everything.

## Related

- `../architect-adr/` - ADRs are immutable and do not carry review cadence (use `Status: accepted / superseded` only)
- `../../fundamentals.md` > Section IV - full lifecycle rationale
