ISA
Articulates the ideal state of a task or project as testable criteria. Invoked at Algorithm OBSERVE for non-trivial work; produces an ISA.md the rest of the run reads from and writes back to. Use when scaffolding or extending an ISA at E3+ OBSERVE, gating `phase: complete` at VERIFY, resolving interdependent design decisions before freezing criteria, or on `/ISA scaffold`, `/ISA check`, `/ISA interview`.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ISA
- type
- skill
- model
- inherit
- description
- Articulates the ideal state of a task or project as testable criteria. Invoked at Algorithm OBSERVE for non-trivial work; produces an ISA.md the rest of the run reads from and writes back to. Use when scaffolding or extending an ISA at E3+ OBSERVE, gating `phase: complete` at VERIFY, resolving interdependent design decisions before freezing criteria, or on `/ISA scaffold`, `/ISA check`, `/ISA interview`.
02 资源文件 3
- 参考文档Workflows/CheckCompleteness.md2.4 KB
- 参考文档Workflows/Interview.md4.8 KB
- 参考文档Workflows/Scaffold.md3.3 KB
03 SKILL.md 正文
ISA — Ideal State Articulation
The ISA is the system of record for a non-trivial Algorithm run. A single document holding:
- The ideal-state articulation (Problem / Vision / Goal)
- The test surface (Criteria — atomic ISCs)
- The verification trail (tool-probe evidence per ISC)
- The done condition (every ISC
[x]with evidence) - The persistence trail (Decisions + Changelog)
Created at OBSERVE, refined through pursuit, verified at VERIFY.
Tiers (per ALGORITHM/v1.2.0.md)
- E2 — inline criteria checklist in the reply; no ISA document.
- E3/E4 — ISA document required. Two homes: project ISA at
<project>/ISA.md(long-lived) or task ISA atdocs/tasks/<task-id>/ISA.md(per-task; auto-created byforge task add --isa). Prefer extending the project ISA for project tasks; task ISA for ad-hoc work.
Index
| File or section | Read when… |
|---|---|
Workflows/Scaffold.md |
Algorithm OBSERVE, E3+, or /ISA scaffold "..." — create or extend the relevant ISA |
Workflows/CheckCompleteness.md |
Algorithm VERIFY, or /ISA check <path> — gate phase: complete |
Workflows/Interview.md |
OBSERVE at E3/E4 with unresolved interdependent design decisions, or /ISA interview <path> — dependency-ordered design interview (optional, skippable) |
_shared/model-routing.md |
Interview step 3 — dispatching a fact lookup instead of asking the user |
| 12-section structure · ISC quality gates · Operating rules (below) | Every workflow |
A plain forge task add carries no ISA — track + nudge, never enforce. task lock prints a non-blocking reminder; the consistency checker reports advisory task-without-isa findings. Attaching one stays your choice.
The 12-section structure (locked order)
| # | Section | Role |
|---|---|---|
| 1 | Problem | What's broken / missing / wanted — concrete, evidence-backed |
| 2 | Vision | The world once this is done |
| 3 | Out of Scope | Explicit cuts for this run |
| 4 | Principles | Inviolable rules framing every decision |
| 5 | Constraints | Inherited boundaries; references Tier 2 docs |
| 6 | Goal | One paragraph — the deliverable in concrete terms |
| 7 | Criteria | Atomic ISCs, each one nameable tool probe |
| 8 | Test Strategy | Per-ISC: type / check / threshold / tool |
| 9 | Features | Phased breakdown linking ISCs to delivery units |
| 10 | Decisions | Timestamped — chosen, why, rejected |
| 11 | Changelog | Conjecture/refutation pairs — how understanding evolved |
| 12 | Verification | Tool-probe evidence per [x] ISC — closes the loop |
ISC quality gates
Criterion count is judgment, not a quota — enough that every deliverable, risk, and regression path has a probe; no more. Gate each criterion with the splitting test:
- Granularity — a single nameable tool probe (Read / Grep / Bash / curl / …)
- Atomic — one verifiable end-state; compound "and"/"with" → split
- Independent failure — A can pass while B fails → split
- Scope words — "all", "every", "complete" → enumerate
- Domain boundary — one ISC per UI / API / data boundary
Required regardless of size: ≥1 Anti: ISC — what must NOT happen, making regression-prevention and out-of-scope probe-able. (Experiential goals also carry ≥1 Antecedent: ISC — the gate the user ultimately judges by.)
Operating rules
- ISC IDs are stable — never renumber. Splits become
ISC-N.M; drops become tombstones with a note. [x]requires evidence in## Verification— never just "tests pass" or "looks fine".- Tier 2 docs win on conflict —
.claude/reference/02-architecture-and-tech-stack.mdis authoritative over## Constraintsuntil reconciled via ADR. phase: completeis gated — CheckCompleteness must pass first.
See also
.claude/ALGORITHM/v1.2.0.md— phase doctrine that drives ISA usage (LATEST).claude/reference/06-architecture-decisions.md— where significant Decisions land long-term as ADRs.claude/scripts/forge/forge.py task add --isa "..."— auto-creates the task ISA
Project-specific overrides: if SKILL.local.md exists in this directory, read it — it is consumer-owned, survives framework refresh, and wins on conflict. A sidecar that relaxes a gate defined above must state how to prove the gate is wrong in that case. Doctrine: rules/framework-vs-project-root.md.
04 同仓库更多 Skills
wizard
Generates an interactive bash wizard that walks a human through steps only they can perform — opens each URL, says what to click and copy, captures values (hidden entry for secrets), writes .env and GitHub secrets, confirms before irreversible actions. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
vet-idea
Vets an idea, decision, or plan BEFORE it is built. Runs a single model through five fixed adversarial advisor roles, a peer-review pass, and a chairman synthesis that emits a halt-capable GO / NO-GO / RECONSIDER verdict. Advisory and non-mutating — outputs a report, never writes task state. Use when an idea, feature, or costly hard-to-reverse decision is of uncertain worth and the question is whether to build it at all. NOT FOR settled work (bug fixes, approved features) or for shaping how to build it (the ISA Interview workflow).
triage-incident
Production incident triage — from "something is broken for users" to fixed, verified, and learned-from. Pulls the error signal (Sentry/logs/user report), reproduces before touching code, routes the fix through /fix-bug's prod fast path, and closes with a postmortem entry. Use when something is broken for users in production — an outage, data corruption, a Sentry spike, or a crash-rate alert. NOT FOR bugs found in development (use /fix-bug directly) or CI failures (use /diagnose-ci).
setup-review-bot
Configures a repo's AI code reviewers — the post-PR mention bot and the pre-push local reviewer — and writes the AGENTS.md the reviewers read. Interviews the user for what the reviewer should weight, then sets git config forge.reviewBot / forge.localReview and populates AGENTS.md at the project root. Use when a repo has no reviewer configured, when review findings are consistently off-target, or when onboarding a new project.
security-review
Portable security review for a feature, endpoint, or change before it ships. Orchestrates the existing OWASP review (@security-boss) and secrets scan (security_secrets validator), then adds the pass they miss — an explicit business-logic-flaw walkthrough (IDOR, race/TOCTOU, state-machine bypass, privilege escalation, price/quantity tampering). Advisory and non-mutating — produces a findings report; real findings are filed as tasks. Use when a change touching money, access control, or multi-step state is about to ship, or when the auth looks fine but the flow could be abused. NOT FOR SAST or dependency-CVE scanning (consumer CI owns those).
run-epic
Autonomously drains every open task in a single epic. Pulls ready tasks via the forge CLI, executes the work in-context using the matching discipline (fix-bug / new-feature / refactor), files newly-discovered work as follow-up tasks without stopping to ask, opens a PR per completed task via /create-pr, and repeats until the epic has zero ready/in-progress/pending tasks. Use when the user says `/run-epic E##`, "run epic autonomously", "finish all remaining tasks for epic X", or "drive epic X to completion".