document-lifecycle

name	document-lifecycle
description	Unified document lifecycle management. Defines terminal statuses, unified numbering via .next-id, close procedures, and orphan detection. Load at session start.

Document Lifecycle Skill

Manages document state transitions, unified numbering, and automated closure across all agent-output directories.

---

Core Principle

Every work chain shares a single ID. When Analyst creates analysis 080, the downstream plan, implementation, QA, UAT, and critique all use ID 080. This enables human traceability across the entire lifecycle.

Documents in terminal status belong in closed/ subfolders. Active work stays visible; completed work is archived but accessible.

---

Terminal Statuses

These statuses trigger document closure (move to closed/):

Status	Meaning	Closed By
Committed	Changes committed to git (awaiting release)	DevOps
Released	Successfully pushed/published	DevOps
Abandoned	Explicitly dropped, will not proceed	User (manual)
Deferred	Postponed indefinitely	User (manual)
Superseded	Replaced by a newer document	User (manual)
Resolved	All findings addressed (critiques only)	Critic

---

Unified Numbering Protocol

The .next-id File

Location: agent-output/.next-id

Contents: Single integer (e.g., 081)

Rules:

• Only originating agents (Analyst, Planner when no analysis) read and increment
• Downstream agents inherit the ID from their source document
• Never skip numbers; always use the next available

Document Header Format

Every document in agent-output/ MUST include:

---
ID: 080                    # Global sequence number
Origin: 080                # Chain origin (same as ID for originating docs)
UUID: a3f7c2b1             # 8-char random hex for collision-proofing
Status: Active             # Current lifecycle state
---

ID Assignment Rules

Scenario	Action
Analyst starts new investigation	Read .next-id, increment, use as ID, write back
Planner creates plan from analysis	Inherit ID/Origin from analysis doc
Planner creates plan from user request (no analysis)	Read .next-id, increment, use as ID, write back
Implementer/QA/UAT/Critic work on plan	Inherit ID/Origin from plan doc
Retrospective reviews plan	Inherit ID/Origin from plan doc

---

Close Procedure

When a document reaches terminal status:

1. Update Status field to the terminal status
2. Add changelog entry: | YYYY-MM-DD | [Agent] | Document closed | Status: [status] |
3. Create closed folder if needed: mkdir -p agent-output/<domain>/closed/
4. Move file: mv agent-output/<domain>/NNN-name.md agent-output/<domain>/closed/
5. Log action: "Closed document NNN-name.md (Status: [status])"

Cross-Reference Handling

When referencing a closed document from another document, use relative paths:

• From active doc: ../closed/080-feature.md
• From closed doc to closed doc: ./080-feature.md (same folder)

---

Orphan Detection

Agent Self-Check (Every Session Start)

Before starting work, each agent MUST:

1. Scan their exclusive domain (e.g., agent-output/qa/) excluding closed/
2. Identify any document with terminal Status
3. Move orphaned documents to closed/
4. Log: "Found orphaned document [name] with Status [status], moved to closed/"

Roadmap Periodic Sweep

Roadmap agent performs comprehensive sweep when reviewing roadmap:

1. Scan ALL agent-output/*/ directories (excluding closed/)
2. Flag documents with terminal Status not in closed/
3. Report to user
4. Move to respective closed/ folders

---

Agent Responsibilities

Agent	Role	Closure Trigger
Analyst	Originate IDs	Planner closes when plan created
Planner	Originate or inherit	DevOps closes after commit
Implementer	Inherit	DevOps closes after commit
QA	Inherit	DevOps closes after commit
UAT	Inherit	DevOps closes after commit
Critic	Inherit	Self-closes when findings resolved
DevOps	N/A	Self-closes after release
Retrospective	Inherit	PI closes after processing
PI	N/A	Self-closes own analysis
Architect	N/A	Evergreen docs, no closure
Roadmap	N/A	Orphan sweep responsibility
Security	Inherit	Self-check only

---

Quick Reference

Creating a New Document (Originating)

# Read current ID
NEXT_ID=$(cat agent-output/.next-id)
# Increment for next use
echo $((NEXT_ID + 1)) > agent-output/.next-id
# Use $NEXT_ID as your document ID

Closing a Document

# Update Status in document header to terminal status
# Add changelog entry
mkdir -p agent-output/<domain>/closed/
mv agent-output/<domain>/NNN-name.md agent-output/<domain>/closed/

Self-Check Pattern

Before starting work:
1. List agent-output/<my-domain>/*.md (excluding closed/)
2. For each file, check Status field
3. If Status in [Committed, Released, Abandoned, Deferred, Superseded, Resolved]:
   → Move to closed/