What Is the ISA (Ideal State Artifact) System in LifeOS and Its Twelve Sections?
The ISA (Ideal State Artifact) system in LifeOS is a version-controlled, single-source-of-truth document format that captures the ideal state of any persistent artifact through twelve fixed sections, five simultaneous work identities, and a deterministic lifecycle managed by six canonical workflows.
The ISA system serves as the backbone of danielmiessler/LifeOS, replacing scattered project documentation with a self-healing contract that evolves from initial intent through verification and ongoing learning. Whether you're building an application, writing a book, or managing a one-off task, the ISA (Ideal State Artifact) format ensures completeness at every tier of work.
Core Architecture of the ISA System
Five Simultaneous Identities
The same ISA document operates through five distinct lenses depending on your current phase, as defined in [ISASystem.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/DOCUMENTATION/ISA/ISASystem.md) (lines 143-151):
- Articulation — expresses intent during scoping
- Work breakdown — decomposes tasks during planning
- Contract — becomes the binding agreement during building
- Test harness — drives verification strategy
- System-of-record — stores evolving knowledge during learning
This identity-shifting design means you never rewrite documentation—you simply read the same ISA through the appropriate lens.
Three-Guardrail Taxonomy
Every ISA includes lightweight guardrails that stabilize the solution surface, specified in [ISAFormat.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/DOCUMENTATION/ISA/ISAFormat.md):
- Principles — bind thinking (what must always be true)
- Constraints — bind the solution space (what you're limited by)
- Out of Scope — bind vision (what you're explicitly not doing)
Each guardrail has anti-counterparts (e.g., Anti-criteria) that help clarify boundaries through negation.
The Twelve Sections of Every ISA
The ISA (Ideal State Artifact) format mandates twelve sections in strict order, defined in [canonical-isa.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/skills/ISA/Examples/canonical-isa.md). This structure guarantees completeness regardless of project complexity:
| Order | Section | Purpose |
|---|---|---|
| 1 | Problem | What pain or opportunity justifies this work |
| 2 | Vision | The ideal end-state in concrete terms |
| 3 | Out of Scope | Explicit boundaries to prevent creep |
| 4 | Principles | Immutable rules guiding all decisions |
| 5 | Constraints | Hard limits (time, budget, technology) |
| 6 | Goal | The measurable objective to achieve |
| 7 | Criteria | Formerly "Claims" — the verifiable standards for success |
| 8 | Test Strategy | How you will prove the criteria are met |
| 9 | Features | The work items (or flat Claims for trivial tasks) |
| 10 | Decisions | Record of architectural choices with rationale |
| 11 | Learning | Formerly "Changelog" — accumulated knowledge |
| 12 | Verification | Proof that criteria were satisfied |
Note that Criteria (section 7) replaced "Claims" and Learning (section 11) replaced "Changelog" in recent versions—both changes reflect the system's evolution toward clearer semantic meaning.
Where ISAs Live: The Two Homes
The ISA (Ideal State Artifact) system distinguishes between persistence models, as documented in [ISASystem.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/DOCUMENTATION/ISA/ISASystem.md):
- Project ISA —
<project>/ISA.mdfor long-lived artifacts (applications, libraries, content collections) - Work ISA —
MEMORY/WORK/{slug}/ISA.mdfor one-off tasks that don't warrant permanent project status
This dual-home design prevents cluttering your main projects with ephemeral work while ensuring durable artifacts have a canonical location.
Six Canonical Workflows
The ISA skill implements deterministic lifecycle operations, with specifications in the Workflows/ directory:
These workflows are invoked through the LifeOS Skill interface, parsed by the Algorithm at appropriate phases.
Integration with the LifeOS Algorithm
The ISA system doesn't operate in isolation—it hooks into the LifeOS Algorithm starting at version 6.2.0. The Algorithm calls ISA skills at specific phase transitions:
- OBSERVE phase → Scaffold or Interview workflows
- PLAN phase → Extract feature to ephemeral file
- LEARN phase → Reconcile or Append workflows
This integration makes the ISA (Ideal State Artifact) system not merely documentation but executable infrastructure.
Practical Command Examples
All ISA operations use the Skill("ISA", ...) interface. Below are the most common patterns:
# Scaffold a new ISA from natural language description
Skill("ISA", "scaffold from prompt: Build a personal knowledge-base app")
# Bootstrap ISA from legacy codebase without documentation
Skill("ISA", "seed ~/Projects/legacy-cli")
# Interview to fill gaps in a thin scaffold (max 3 auto-questions)
Skill("ISA", "interview me on ~/Projects/knowledge-base/ISA.md")
# Verify tier-completeness before build authorization
Skill("ISA", "check completeness of ~/Projects/knowledge-base/ISA.md")
# Extract feature for focused implementation work
Skill("ISA", "extract feature Search as ephemeral file from ~/Projects/knowledge-base/ISA.md")
# Merge completed feature back into canonical ISA
Skill("ISA", "reconcile ./_ephemeral/Search/ISA.md → ~/Projects/knowledge-base/ISA.md")
# Append lifecycle entries (Algorithm-triggered or manual)
Skill("ISA", "append decision to ~/Projects/knowledge-base/ISA.md: Adopt SQLite for storage")
Skill("ISA", "append learning to ~/Projects/knowledge-base/ISA.md: Indexed-search model outperformed TF-IDF")
Skill("ISA", "append verification to ~/Projects/knowledge-base/ISA.md: ISC-12 passed via `bunker test`")
Paths are relative to the LifeOS working directory. The Skill calls parse into workflow execution that modifies the underlying ISA files deterministically.
Summary
- The ISA (Ideal State Artifact) is LifeOS's single-source-of-truth format for capturing ideal state
- Twelve fixed sections ensure comprehensive documentation: Problem, Vision, Out of Scope, Principles, Constraints, Goal, Criteria, Test Strategy, Features, Decisions, Learning, and Verification
- Five identities let the same document serve scoping, planning, building, verification, and learning phases
- Two homes—Project ISA for durable artifacts, Work ISA for ephemeral tasks
- Six workflows—Scaffold, Interview, CheckCompleteness, Append, Reconcile, Seed—provide deterministic lifecycle management
- The ISA skill integrates with the LifeOS Algorithm starting at v6.2.0
Frequently Asked Questions
What makes the ISA (Ideal State Artifact) different from a standard PRD or specification document?
The ISA is version-controlled, identity-shifting, and executable. Unlike static documents, the same ISA file transforms from articulation to contract to test harness through five identities. It also enforces structural completeness through twelve mandatory sections and integrates directly with LifeOS workflows rather than sitting idle.
When should I use a Project ISA versus a Work ISA?
Use a Project ISA (<project>/ISA.md) when the artifact has ongoing evolution—applications, libraries, content collections, or anything you'll return to. Use a Work ISA (MEMORY/WORK/{slug}/ISA.md) for one-off tasks like a single data migration or a weekend research spike that won't need long-term maintenance.
How does the Interview workflow know what to ask?
The Interview workflow, defined in [Interview.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/skills/ISA/Workflows/Interview.md), analyzes the existing ISA for empty or thin sections, then generates adaptive questions based on section type. It's capped at three questions to prevent analysis paralysis, prioritizing the highest-uncertainty gaps first.
What happens if I skip the CheckCompleteness workflow before building?
Nothing technically prevents building, but you bypass the tier-completeness gate that the ISA system uses to ensure Problem, Vision, and Goal sections are sufficiently defined. Without this check, you risk building against ambiguous or shifting requirements—the exact problem the ISA (Ideal State Artifact) system was designed to eliminate.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →