/ISA

name: ISA
metadata:
  short-description: "Scaffolds, restates, discusses, rates, renders, and maintains the Ideal State Artifact that says what done means and keeps it aligned."
version: 1.7.3
evals:
  manual:
    reason: "artifact quality depends on the project's intent"
    falsifier: "the principal rejects the ISA as an accurate articulation of done"
description: "Owns the Ideal State Artifact (ISA): scaffolds, restates, interviews, discusses, rates, renders, upgrades, and maintains the articulation of a project's ideal state. USE WHEN ISA, ISC, ideal state, ideal state criteria, ideal state ladder, L1 L2 L3, restate, say it back, what do you think I want, are we building the right thing, drift check, project specification, articulating done, fog, not yet specified, discuss, discovery interview, are we aligned, alignment, questionnaire, articulation, refine the ISA, open questions, ask fence, mid-run question, rate this ISA, score this ISA, ISA quality, ISA format, latest ISA template, upgrade ISAs, isa_format stamp, render an ISA, ISA HTML, open an ISA in the browser, ISA page, view an ISA. NOT FOR creating new skills (CreateSkill), visual quality critique (ArtDirection), or climbing a target to a measured improvement (HillClimb)."

ISA — Ideal State Artifact

Create and maintain the document that articulates and verifies a project's ideal state. Direction comes first: nothing in an ISA matters more than making sure we are working on the right thing, in the right direction, toward what the ideal state actually looks like. Every ISA opens with the `## Ideal State` ladder (`### L3 · One sentence`, `### L2 · Summary` with one sentence plus exactly four bullets, `### L1 · Full articulation`), each level written from the summit: the euphoric-surprise version of done for everyone the work touches, never the floor of what must not break, which lives in criteria and anti-criteria (ISAFormat § *What the ladder captures: the summit*). Shape check: `bun LIFEOS/TOOLS/IsaLadder.ts check <isa>`. Drift check, whether the criteria still add up to L3: `bun LIFEOS/TOOLS/IsaLadder.ts drift <isa>`. ISAFormat (`LIFEOS/DOCUMENTATION/ISA/ISAFormat.md`, § *The Ideal State ladder* for the full rules) wins any conflict with this skill or an intent.

**Contents:** Ideal State · Intent Routing · Data & Config · Gotchas · Examples

Ideal State

• Every ISA the skill writes or touches opens with a ladder that passes the shape check, is written from the summit, and agrees with its criteria; anything in the ISA that disagrees with the ladder is resolved before another criterion is climbed.
• L3 and L2 reach the principal through Restate before a new project or a changed direction is built (an extension whose re-derived L3 or L2 changed counts as one), and not otherwise.
• An existing ISA is extended in place, never replaced by a second ISA: the new work takes the next `F<n>` block (or new flat criteria when the ISA is flat) and the next global ISC IDs, no existing ID renumbers, the ladder is re-derived so it covers the new work, and when the re-derived L3 or L2 changed, they reach the principal through Restate before the new work is built.
• Every criterion is atomic, names its falsifier, and carries at least one `## Test Strategy` row in the canonical six-column shape, so Assay resolves the whole table with no dropped row. Each row runs on a lane, `liveness` for asserts on every monitor tick or `integrity` for checks that may judge (or `build`, full runs only), and at a stage, so a criterion's asserts run before its judged rows (ISAFormat § *Verifier classes, lanes, and stages*; the one progressive contract is `skills/Assay/References/Progressive.md`).
• Discuss is the standing alignment loop: whenever the ISA's state says direction is uncertain (`bun LIFEOS/TOOLS/IsaAlign.ts status <isa>` returns `DISCUSS`) or the conversation shows doubt about what done means, a Discuss round runs before the uncertain part is built, sized `quick`, `full` or `deep` to the doubt, and Restate, Refine, Rate and the ambiguity check hand off to it when their single-question shapes stop being enough.
• Every interviewing surface (Discuss, Interview, Questionnaire, Refine, Scaffold's ambiguity check) leaves its raw record in the ISA's append-only `## Articulation Log`, and the settled answers reach the ladder and the sections in the same turn.
• The ISA's history stays auditable: criterion IDs never renumber, and Decisions, Learning and Verification entries keep their canonical shapes.

Intent Routing

Before executing an ISA operation, load its operation bundle:

bun "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/LIFEOS/TOOLS/ContextLoad.ts" ISA load <bundle>

The bundle returns required ISA constraints, operation instructions, and internal references with source hashes. Follow every returned requirement, including conditional reads. Skill-local paths resolve from the skill root; `LIFEOS/` paths resolve from the install root. Do not reread unchanged context still present; after compaction or a source change, reload the relevant bundle.

Set the shell and any code-mode wrapper output budget to 30000 tokens. Treat any truncation warning as a failed load, even when `END CONTEXTLOAD` appears. Use `list` to discover bundles and `search "<query>"` to search the complete guide. A failed search does not prove absence: inspect the index, broaden the query, or load `full`. If routing is uncertain, a bundle is absent, or the loader fails, load or read `References/CompleteGuide.md` in full before acting.

When the verb is ambiguous, default to Scaffold for a new ISA and CheckCompleteness for an audit.

| Intent | Trigger | File | Bundle | |--------|---------|------|--------| | **Scaffold** | "scaffold", "create", "generate", "new ISA from this prompt", "extend <existing ISA> with a new Feature", "extend in place" | `Intents/Scaffold.md` | `scaffold` | | **Restate** | "restate", "say it back", "confirm the direction", "is this wha