ISA

Drafts, audits, and merges Ideal State Artifact specification documents with verifiable claims.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/ruban-s/DevOS --skill isa-ruban-s
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ISA
Source: https://github.com/ruban-s/DevOS/tree/main/skills/ISA
Command: npx skills add https://github.com/ruban-s/DevOS --skill isa-ruban-s

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Coding agents declare work done without proof. ISA pins what finished means before any code exists: a single Markdown document carrying a verifiable goal, atomic binary-probe claims (ISCs), a per-claim Test Strategy, and a decision/learning/verification trail, so every claim stays open until a probe actually passes. ## Core Features & Use Cases - Scaffold and Seed: Draft a new ISA from a prompt, or bootstrap a project ISA from an existing repo's README, configs, commits, and test files without inventing fiction. - Grill and Interview: Interrogate half-formed ideas into shape via checkpointed Q&A, or deepen thin sections of an existing ISA with targeted spec-interview questions. - CheckCompleteness gate: Score an ISA against a substance-scaled completeness rubric (trivial/substantial/deepest) covering anti-claims, test-strategy coverage, ID stability, and fog graduation. - Reconcile: Deterministically merge parallel feature-slice files back into the master ISA keyed on stable claim IDs. - Use Case: Before building a CLI feature, scaffold an ISA whose claims each name one runnable probe (bash, bun-test, curl); the close gate blocks completion until every probe passes and fog sections are empty. ## Quick Start Ask the agent to scaffold an ISA from your feature request, for example: scaffold an ISA for adding a --json output flag to my CLI with verifiable claims and a test strategy.

Frequently Asked Questions about ISA

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a verifiable project specification before coding?▼

Scaffold an ISA from your prompt: it preserves your stated goal verbatim, derives Vision, Out of Scope, and Constraints, then decomposes the work into atomic claims where each claim names exactly one binary probe such as a bash command, test, or curl check.

What is an Ideal State Artifact in agentic coding workflows?▼

An Ideal State Artifact is a single Markdown document with seventeen fixed sections that pins what finished means for a task or project. It combines the goal, falsifiable claims, a test strategy table, and decision and learning logs so completion is proven by probes rather than asserted.

How do I bootstrap a spec for an existing repository?▼

Use the Seed workflow on the repo path. It reads the README, package.json, configs, recent commits, and any PRD-shaped files to draft a substantial-grade project ISA, marking it review-required rather than inventing content the sources do not support.

Can parallel agents work on slices of one specification?▼

Yes. Scaffold can extract a feature slice as an ephemeral file containing the relevant claims with stable IDs, and Reconcile later merges checkmarks, verification stubs, decisions, and learning entries back into the master ISA deterministically, aborting on unknown IDs.

When should I use Grill versus Interview?▼

Use Grill when the idea is too unformed to draft a spec; it discovers structure through checkpointed questions and a pre-mortem. Use Interview when an ISA already exists but has thin sections that need deepening with targeted questions.

Why does the completeness check fail my specification?▼

Common hard failures include missing required sections for the work's substance level, zero anti-claims, leaf claims with no Test Strategy probe row, non-empty fog sections at close, claim ID renumbering, or a narrative changelog section, which is banned because git is the change record.