create-lifecycle

Create Lifecycle

Documents how resources managed by a feature evolve over time and what causes them to change. Produces a lifecycle document covering states, transitions, invariants, retention policies, and event emissions for each resource that has a meaningful lifecycle.

Without this step, resource state machines are implicit in the code and scattered across API handlers, database constraints, and application logic. When a new state is added or a transition rule changes, there is no single source of truth to consult, so inconsistencies arise between what the API allows, what the database enforces, and what the UI presents.

For features that do not manage resources with a lifecycle (a pure config change, a read-only dashboard, a documentation update), skip this phase and state the skip explicitly.

Prerequisites

• Apply the shared SDLC conventions in skills/sdlc/references/shared.md.
• If no argument is provided, locate the feature directory under .sdlc/features/ whose frontmatter issue field references $ISSUE_NUMBER.
• .sdlc/features/N-<slug>/specification.md (must have passed review with findings verdict approved), or a specification document provided in context or as a file path ($1)
• .sdlc/features/N-<slug>/requirements.md (optional, for cross-referencing functional requirements that drive lifecycle behavior)
• .sdlc/features/N-<slug>/codebase-analysis.md (optional, if existing code was analyzed): reuse existing state machines or enums, and honor any "must not change" constraints on shared resource models

Steps

1. Read the specification, requirements (if present), and codebase analysis (if present).
2. Decide whether the feature manages resources with a meaningful lifecycle. If it does not, emit verdict: skipped (do not write lifecycle.md). The skipped verdict routes the pipeline straight to the next phase, bypassing /review-lifecycle.
3. Identify every resource the feature creates, modifies, or tracks that has a lifecycle (resources that pass through distinct states, have retention policies, or emit events on state changes).
4. For each resource, determine its lifecycle type:
   • State Machine: the resource moves between named states via defined transitions (e.g., order: pending -> paid -> shipped -> delivered).
   • Linear: the resource progresses through a one-way sequence without branching (e.g., a build: queued -> running -> succeeded/failed).
   • CRUD: the resource has no meaningful state beyond created/updated/deleted (document only if retention or expiry applies).
5. For each resource with a state machine or linear lifecycle, draw a state diagram showing all states and transitions.
6. For each state, document its meaning, entry condition, exit condition, and a reference to the specification section that defines the behavior.
7. For each transition, document the trigger (event, API call, timer, condition), the actor (user, system, external), side effects (notifications, cascading updates, event emissions), and guard conditions (preconditions that must hold).
8. Define invariants: conditions that must always hold regardless of state (e.g., "a subscription cannot be active without a valid payment method"). Document how each is enforced and what happens on violation.
9. Specify retention and expiry policies: how long resources persist, what triggers expiry, and what cleanup action is taken (hard delete, archive, anonymize).
10. List events emitted on transitions, including payload, downstream consumers, and cross-references to the specification or telemetry plan.
11. Write the output to .sdlc/features/N-<slug>/lifecycle.md.