/ISA

name: ISA
version: 1.1.2
description: "Owns the Ideal State Artifact — the primitive holding a project or task's articulated ideal state; scaffolds, interviews, grills a half-formed idea into shape via checkpointed discovery, scores completeness, reconciles feature excerpts to master, seeds from a repo, and appends decisions/changelog/verification across a locked seventeen-section order. USE WHEN ISA, ISC, ideal state, ideal state criteria, project specification, hill-climb, articulating done, fog, not yet specified, grill me, discovery interview. NOT FOR creating new skills (use CreateSkill)."

🚨 MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)

**You MUST send this notification BEFORE doing anything else when this skill is invoked.**

1. **Send voice notification**:

   curl -s -X POST http://localhost:31337/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running the WORKFLOWNAME workflow in the ISA skill"}' \
     > /dev/null 2>&1 &

2. **Output text notification**:

   Running the **WorkflowName** workflow in the **ISA** skill to ACTION...

**This is not optional. Execute this curl command immediately upon skill invocation.**

ISA — Ideal State Artifact

What It Does

The ISA is the single document that articulates "done" for any thing whose ideal state we are pursuing — a project, an application, a library, infrastructure, a work session, an art piece, a strategic decision. It serves five identities at once: ideal state articulation, test harness, build verification, done condition, system of record. This skill owns the canonical template, the workflows that generate and refine ISAs, and the example library.

Every ISA shares one meta-ideal-state above its specific one: **euphoric surprise in the human using the system**. The specific ideal state varies with the work; the universal one never does. `## Vision` is where that general target takes specific shape — what euphoric surprise looks like for this particular work — so every ISA hill-climbs toward two summits at once.

The Problem

Most work starts without a written, testable definition of what finished looks like, so "done" drifts — the goal in your head at the start isn't the goal you settle for at the end, and there's no record of which one was right. Criteria stay vague enough that anything passes, decisions and dead ends get forgotten and re-litigated, and when work spans multiple sessions or multiple agents there's no shared source of truth for what's been verified. The ISA fixes "done" as a hard-to-vary explanation with atomic, probe-able criteria, a stable-ID structure that survives edits, and an audit trail of what was conjectured, refuted, and learned.

How It Works

The ISA is a single document with a locked seventeen-section body. A substance-scaled completeness gate decides which sections are required for a given piece of work, and six workflows generate, deepen, score, and reconcile the artifact across sessions and agents.

---

The Seventeen-Section Body (locked; spec v2.19.0, Algorithm v8.19.0)

Every ISA may have up to seventeen body sections. The substance-scaled completeness gate decides which are required for a given piece of work; sections never appear empty. **Order is fixed**. **Vocabulary (v8):** the criteria section is headed `## Claims` on new ISAs (`## Criteria` / `## ISC Criteria` legacy, still parsed); claim IDs may be `ISC-N` or short-form (`C1`, `A3`); anti-claims may live inline (`Anti:` prefix) or in a dedicated `## Anti-claims` section; the provenance section may be headed `## Verification` or `## Log`.

| # | Section | Purpose | Written At | |---|---------|---------|------------| | 1 | `## Problem` | What is broken or missing right now that makes the ideal state worth pursuing | scoping | | 2 | `## Vision` | What euphoric surprise looks like — experiential intent, 1–5 sentences | scoping | | 3 | `## Out of Scope` | Anti-vision — what is *not* included in this ideal state, declared upfront in prose | scoping | | 4 | `## Language` | **NEW v2.18.0** — the project's ubiquitous language. One block per term: meaning, an `_Avoid_:` line naming the names it displaces, and relationships. Glossary only — no implementation detail, no claims. **A term enters only after it has actually caused a confusion.** Project ISAs; task ISAs inherit by reference | scoping → any point | | 5 | `## Principles` | Substrate-independent truths (Deutsch reach) the work must respect | scoping | | 6 | `## Constraints` | Immovable architectural mandates that bound the solution space | scoping | | 7 | `## Dependencies` | Cross-ISA needs, one machine-readable `requires: <slug> — <contract>` line each — only when the ISA participates in a hierarchy | scoping | | 8 | `## Goal` | The hard-to-vary spine — 1–3 sentences naming verifiable done | scoping | | 9 | `## Claims` | **Feature-less mode** — flat home for atomic claims/ISCs when the work has no distinct features. When it does, omit this and use `## Features` blocks (§12) | scoping → climbing | | 10 | `## Not yet specified` | Fog — in-scope questions too dim to be claims yet, one `- fog:` line each; graduates to ISCs (or dies via Decisions) as pursuit sharpens it; empty at close — only when the work has fog | scoping → any point | | 11 | `## Bridge Criteria` | Cross-ISA integration claims (`Bridge:` prefix) verified across the seam as a distinct verification pass — only when the ISA has siblings | scoping → climbing | | 12 | `## Test Strategy` | Per-ISC verification approach — `isc | type | check | threshold | tool | anchors_to` | scoping | | 13 | `## Features` | **Feature mode (v2.16.0)** — holds the claims as blocks: `### F<n> · <name>` + a one-line `Why:` (its ideal-state) + its ISCs nested underneath. `F0 · Cross-cutting` for spanning claims. Pointer table deleted; ISC IDs stay global/stable. Use this OR flat `## Claims`, never both | scoping → climbing | | 14 | `## Decisions` | Timest