infer-completion-criteria

What this skill does

# 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:

```bash
# 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 gates
- `.aiwg/security/security-gates.md` — security-related criteria
- `.aiwg/quality/code-review-guide.md` — code quality bars
- `.aiwg/activity.log` — recent operations that may indicate what "done" looked like for similar past tasks
- `.aiwg/working/<related-progress-files>.md` — prior task progress files; mine the "Completion criteria" sections

If the project has a related use case (`.aiwg/requirements/UC-*.md`) whose ID is in the task description, pull that use case's acceptance criteria — those ARE the completion criteria.

### Synthesis step

Combine the layers into a single proposed criterion. The decision logic:

1. If a use case in `.aiwg/requirements/` matches the task, use its acceptance criteria verbatim. Done.
2. Otherwise, take the verb-class default from Layer 1 and instantiate it using the canonical command from Layer 2 (CLAUDE.md) > Layer 4 (CI) > Layer 3 (manifest).
3. If the task is in the "regression gate" class, AND the project's CI runs more than one verification, combine them: `command-A passes AND command-B passes AND command-C passes`.
4. If no canonical command is found in any layer (unusual — typically only on empty-scaffold projects), fall back to:
   - `<file or change exists in git diff against HEAD~1>` — pure structural check
   - And inform the user that a substantive verification command should be added.

### Apply AIWG standards (vague-discretion)

Validate the proposal against the `vague-discretion` rule:

- Criterion must be expressible as a shell command (or shell pipeline) that exits 0 on pass, non-zero on fail.
- Criterion must NOT use the words "good enough", "thorough", "comprehensive", "complete" without a measurable suffix.
- Criterion must NOT be self-referential ("the agent is satisfied" — no).
- Criterion must have an implicit or explicit `max-iterations` cap (ralph's default 10 is the floor; very large refactors may need 20).

If the proposal fails any of these, regenerate. If after two regenerations the proposal still fails, surface the problem to the user with the diagnostic ("could not find a measurable verification command — please supply one explicitly").

## Output Contract

The skill emits a single block of structured output for the calling skill (`agent-loop` router, `ralph` executor, or `agent-loop-ext` launcher) to consume:

```yaml
proposed_completion:
  criterion: "npm test passes AND npx tsc --noEmit exits 0"
  verification_command: "npm test && npx tsc --noEmit"
  rationale:
    - "Task verb 'refactor' triggers regression gate (Layer 1)"
    - "package.js