agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/arch-lens-state-lifecycle/SKILL.md

arch-lens-state-lifecycle

Skill1 starsChanged 8 months agoMITView on GitHub

Create State Lifecycle architecture diagram showing field contracts, validation gates, and resume safety. Contract overlay lens answering "How is state corruption prevented?

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

    line 38
  2. Distinctive:

    Look for: State classes, Context objects, state schemas, typed dictionaries

    line 51
  3. Distinctive:

    Look for: immutable fields, readonly, lifecycle annotations, const fields

    line 56
  4. Distinctive:

    Look for: validate_*, gate, check_*, guard, assert, state validators

    line 61
  5. Distinctive:

    Look for: resume, checkpoint, restore, detect state, load checkpoint

    line 66
  6. Distinctive:

    Look for: update methods, setState, mutation functions, state setters

    line 71
  7. Distinctive:

    Look for: contract checking, violation detection, enforcement mechanisms

    line 76
  8. Very specific:

    Write the diagram to: temp/arch-lens-state-lifecycle/arch_diag_state_lifecycle_{YYYY-MM-DD_HHMMSS}.md

    line 131
  9. Distinctive:

    Before creating the diagram, verify:

    line 254

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

State Lifecycle Architecture Lens

Cognitive Mode: Perspective (Quality Overlay) Primary Question: "How is state corruption prevented?" Focus: Field Contracts, Validation Gates, Resume Safety, State Mutation Control

When to Use

  • Need to understand state management architecture
  • Documenting field lifecycle contracts
  • Analyzing resume and checkpoint safety
  • User invokes /arch-lens-state-lifecycle or /make-arch-diag state

Critical Constraints

NEVER:

  • Modify any source code files
  • Show business logic details
  • Focus on data content (focus on mutation rules)

ALWAYS:

  • Focus on STATE MUTATION RULES
  • Show field lifecycle categories
  • Document validation gates
  • Include resume detection strategy
  • BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

State Schema

  • Find state/context definitions
  • Identify typed state fields
  • Look for: State classes, Context objects, state schemas, typed dictionaries

Field Categories

  • Find field mutation patterns
  • Identify immutable vs mutable fields
  • Look for: immutable fields, readonly, lifecycle annotations, const fields

Validation Gates

  • Find state validation code
  • Identify gate patterns
  • Look for: validate_, gate, check_, guard, assert, state validators

Resume Detection

  • Find resume/checkpoint code
  • Identify resume detection strategy
  • Look for: resume, checkpoint, restore, detect state, load checkpoint

State Updates

  • Find state mutation code
  • Identify update patterns
  • Look for: update methods, setState, mutation functions, state setters

Contract Enforcement

  • Find contract validation
  • Identify violation detection
  • Look for: contract checking, violation detection, enforcement mechanisms

Step 2: Categorize Fields

CategoryDescriptionFields
INIT_ONLYSet once, never modify{fields}
INIT_PRESERVEKeep on resume{fields}
MUTABLECan change freely{fields}
APPEND_ONLYCan only grow{fields}
DERIVEDComputed, not stored{fields}

CRITICAL - Analyze Read/Write Direction: For EVERY state field and storage location:

  • Read patterns: Who READS this field? When?
  • Write patterns: Who WRITES this field? When?
  • Read-after-write: Is the written value ever READ back by the system?

Distinguish clearly:

  • State fields (read/write): System both writes AND reads back for decisions
  • Checkpoint storage (read/write): Written during execution, read on resume
  • Audit logs (write-only): System writes but never reads back for logic
  • Debug artifacts (write-only): Written for humans, not read by system

Step 3: Map Validation Flow

Document:

  • Gate order (which runs first)
  • Failure modes
  • Resume vs fresh start differences

Step 4: Create the Diagram

Use flowchart with:

Direction: TB for contract enforcement flow

Subgraphs:

  • Lifecycles (field categories)
  • Validation Gates
  • State Wrapper (mutation mechanism)
  • Resume Detection
  • Phase Jump Routing

Node Styling:

  • detector class: INIT_ONLY fields (red - critical)
  • gap class: INIT_PRESERVE fields (yellow - warning)
  • phase class: MUTABLE fields (purple)
  • handler class: APPEND_ONLY fields (orange)
  • stateNode class: Validation gates
  • output class: State wrapper/accessor
  • cli class: Resume detection tiers

Step 5: Write Output

Write the diagram to: temp/arch-lens-state-lifecycle/arch_diag_state_lifecycle_{YYYY-MM-DD_HHMMSS}.md


Output Template

# State Lifecycle Diagram: {System Name}

**Lens:** State Lifecycle (Contract Overlay)
**Question:** How is state corruption prevented?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Field Lifecycle Categories

| Category | Description | Example Fields |
|----------|-------------|----------------|
| INIT_ONLY | Never modify after init | {fields} |
| INIT_PRESERVE | Keep on resume | {fields} |
| MUTABLE | Free to change | {fields} |
| APPEND_ONLY | Can only grow | {fields} |

## State Lifecycle Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;

    subgraph Lifecycles ["FIELD LIFECYCLE CATEGORIES"]
        direction TB
        INIT_ONLY["INIT_ONLY<br/>━━━━━━━━━━<br/>id, request_id<br/>NEVER modify"]
        INIT_PRESERVE["INIT_PRESERVE<br/>━━━━━━━━━━<br/>is_resuming<br/>Keep on resume"]
        MUTABLE["MUTABLE<br/>━━━━━━━━━━<br/>current_state<br/>Freely change"]
        APPEND_ONLY["APPEND_ONLY<br/>━━━━━━━━━━<br/>errors, history<br/>Only grow"]
    end

    subgraph Gates ["VALIDATION GATES"]
        direction TB
        GATE1["validate_required<br/>━━━━━━━━━━<br/>FAIL-FAST"]
        GATE2["validate_lifecycle<br/>━━━━━━━━━━<br/>Contract check"]
        GATE3["resume_safety<br/>━━━━━━━━━━<br/>Preserve check"]
    end

    subgraph Wrapper ["STATE WRAPPER"]
        direction TB
        ACCESSOR["StateAccessor<br/>━━━━━━━━━━<br/>Tracks mutations"]
        MERGE["Merge Updates<br/>━━━━━━━━━━<br/>Auto-include"]
    end

    subgraph Resume ["RESUME DETECTION"]
        direction TB
        TIER1["Tier 1: Explicit<br/>━━━━━━━━━━<br/>flag=true"]
        TIER2["Tier 2: Heuristic<br/>━━━━━━━━━━<br/>State exists"]
        TIER3["Tier 3: Fresh<br/>━━━━━━━━━━<br/>No indicators"]
    end

    %% FLOW %%
    INIT_ONLY --> GATE1
    INIT_PRESERVE --> GATE2
    MUTABLE --> GATE2
    APPEND_ONLY --> GATE2

    GATE1 --> GATE2
    GATE2 --> GATE3
    GATE3 --> ACCESSOR
    ACCESSOR --> MERGE

    MERGE --> TIER1
    TIER1 --> TIER2
    TIER2 --> TIER3

    %% CLASS ASSIGNMENTS %%
    class INIT_ONLY detector;
    class INIT_PRESERVE gap;
    class MUTABLE phase;
    class APPEND_ONLY handler;
    class GATE1,GATE2,GATE3 stateNode;
    class ACCESSOR,MERGE output;
    class TIER1,TIER2,TIER3 cli;

Color Legend:

ColorCategoryDescription
RedINIT_ONLYNever modify (critical)
YellowINIT_PRESERVEPreserved on resume
PurpleMUTABLEFreely modifiable
OrangeAPPEND_ONLYCan only grow
TealGatesValidation gates
Dark TealWrapperState mutation mechanism
Dark BlueDetectionResume detection tiers

State Lifecycle Contract Rules

LifecycleFresh StartResumeViolation Detection
INIT_ONLYCannot modifyCannot modify{detection}
INIT_PRESERVECan modifyCannot modify{detection}
MUTABLECan modifyCan modifyNever fails
APPEND_ONLYCan appendCan append{detection}

Resume Detection Strategy

TierCheckResult
1Explicit flag{what happens}
2Heuristic{what happens}
3Fresh start{what happens}

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table

---

## Related Skills

- `/make-arch-diag` - Parent skill for lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/arch-lens-process-flow` - For state machine view
- `/arch-lens-error-resilience` - For validation failure handling

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.