/infer-completion-criteria

namespace: aiwg
name: infer-completion-criteria
aliases: [agent-loop-infer-completion, al-infer-completion, ralph-infer-completion]
platforms: [all]
description: Infer measurable completion criteria for an agent-loop task from project docs, code, and AIWG standards when the user has not supplied --completion explicitly
commandHint:
  argumentHint: '"<task description>" [--task-type code|test|docs|refactor] [--non-interactive]'
  allowedTools: "Read, Glob, Grep, Bash"
  model: haiku
  category: automation
  modelRole: efficiency
  modelTier: economy

Infer Completion Criteria

Purpose

When a user starts an `agent-loop` task without supplying `--completion`, this skill derives a measurable, verifiable completion criterion from project state. The output must satisfy the `vague-discretion` rule: a concrete shell command or file-inspection check that returns pass/fail unambiguously.

Iteration is only as good as its gate. A loop with a vague gate ("until it's done") runs forever or exits prematurely. This skill is what turns "agent-loop this" into "agent-loop this until `<measurable thing>`."

The canonical name for the iterative-loop addon is **agent-loop**. `ralph` is the legacy name for the executor skill, retained as an alias; `al` is a short form. The detection/routing skill is `agent-loop` (which delegates to this skill when criteria are missing); the executor is `ralph` (canonical name forthcoming). Everywhere this skill says "agent-loop" you can read "ralph" as the legacy equivalent.

When This Skill Runs

This skill is invoked by:

• The `agent-loop` detection-and-routing skill when it parses a user request without explicit completion criteria
• The `ralph` executor skill during Phase 1 initialization when `--completion` is omitted
• The `agent-loop-ext` external-loop launcher during pre-launch resolution when `--completion` is omitted
• Direct invocation via `aiwg discover "infer completion"` → `aiwg show skill infer-completion-criteria` when a user wants to preview the inferred criterion before committing to a loop

This skill does **not** run when `--completion` is explicit. The user's word is authoritative.

Inference Pipeline

The skill is a deterministic walk through five evidence layers, plus one synthesis step. Each layer contributes candidate criteria; the synthesis picks the strongest measurable one and explains the chain of evidence.

Layer 1 — The task verb

Parse the user's task description for an intent verb. Map to a default criterion class:

| Verb / phrase | Criterion class | |---|---| | "fix tests", "make tests pass", "test failure" | Test suite passes (exit 0) | | "add tests", "increase coverage", "test coverage" | Coverage threshold met | | "fix types", "type errors", "migrate to typescript" | Type checker exits 0 | | "fix lint", "clean up warnings", "style" | Linter exits 0 | | "build", "make it compile" | Build command exits 0 | | "refactor", "extract", "rename" | Tests still pass AND build still passes (regression gate) | | "implement <X>", "add feature <X>" | Tests for the new code exist and pass | | "document", "add docs", "JSDoc" | Coverage check on docstrings/JSDoc presence | | "fix bug", "resolve issue #N" | Specific test for that bug passes AND existing suite still green | | "migrate", "upgrade" | Build + test + lint all green (no regression) |

If the verb is ambiguous, the skill falls back to "regression gate" (build + test + lint all green) as the safest default.

Layer 2 — Project conventions in CLAUDE.md / AGENTS.md / AIWG.md

Read the project's context files. AIWG-managed projects often declare commands directly:

# Run tests
npm test

# Type check
npx tsc --noEmit

# Lint markdown
npm exec markdownlint-cli2 "**/*.md"

Extract these as the canonical commands for their respective domains. The Development section of `CLAUDE.md` is the highest-trust source here — it's what the project's maintainers run.

Also scan for explicit completion-criterion conventions. Some projects state "a commit is not finished until CI passes" — that signals the CI command (or equivalent local invocation) is the gate.

Layer 3 — Package manifests and config

Inspect the project's manifest files to discover scripts and tools:

| Manifest | Where to look | |---|---| | `package.json` | `scripts.test`, `scripts.lint`, `scripts.build`, `scripts.coverage`, `scripts.typecheck` | | `Cargo.toml` | implies `cargo test`, `cargo build`, `cargo clippy` | | `pyproject.toml` | `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `scripts.*` | | `go.mod` | implies `go test ./...`, `go vet ./...`, `go build ./...` | | `Gemfile` | implies `bundle exec rspec`, `bundle exec rubocop` | | `pom.xml` / `build.gradle` | `mvn test`, `mvn verify`, `gradle test` | | `.tool-versions` / `mise.toml` | language version pins inform which tool is canonical |

When multiple scripts exist (e.g. `test`, `test:unit`, `test:integration`), prefer the script the project's own docs reference. If the docs don't reference any, prefer the most specific match to the task verb (e.g. for "fix integration test" → `test:integration`).

Layer 4 — CI configuration

CI files encode the team's actual definition of "passes":

| CI system | Scan | |---|---| | GitHub Actions | `.github/workflows/*.yml` — extract `run:` steps from non-deploy jobs | | Gitea Actions | `.gitea/workflows/*.yml` — same | | GitLab CI | `.gitlab-ci.yml` — extract `script:` from test/lint jobs | | CircleCI | `.circleci/config.yml` | | Jenkins | `Jenkinsfile` |

The first non-trivial verification step in the primary workflow is the team's canonical "done" gate. If CI runs `npm test && npm run lint && npm run typecheck` in order, the inferred criterion is "all three exit 0."

Layer 5 — AIWG artifacts

If the project has a `.aiwg/` directory, scan for relevant context:

• `.aiwg/testing/test-strategy.md` — declared verification approach
• `.aiwg/architecture/software-architecture-doc.md` — architectural quality g