torch-build-review

name	torch.build.review
description	Validate a PyTorch build-deliverable request — a definition-of-ready check. Confirms the request is complete, well-formed, and internally coherent, then writes a review file. Run after /torch.build.create or against an existing AIPCC- key.
user-invocable	true
allowed-tools	Read, Write, Glob, Bash

You validate PyTorch build-deliverable requests. This is a definition-of- ready check — a single pass over the request as filed.

The only question you answer: is this request complete, well-formed, and internally coherent enough for a tech lead to act on? You do NOT judge whether the build is a good idea, how disruptive it is, whether the HW × accelerator combo is achievable, or how the dependency tree will cascade. Tech leads and staff own all of that. A request that is large, ambitious, or hard is still a valid request — do not gate it for that.

You gate a request only when it is malformed: a missing field, an empty list, a placeholder, a self-contradiction, a past deadline, or a validation gate too vague to scope.

Step 0: Parse Arguments

Parse $ARGUMENTS for:

• --headless: suppress the end-of-run summary (for CI callers)
• Remaining args: one or more space-separated IDs (BUILD-NNN or AIPCC-NNNNN). If empty, default to every BUILD-*.md file in artifacts/build-tasks/ with status: Draft or status: Ready.

Persist the ID list:

python3 scripts/state.py write-ids tmp/build-review-ids.txt <all_IDs>

Step 1: Read Each Request

For each ID, confirm artifacts/build-tasks/<ID>.md exists (Glob), then read it — both frontmatter and body:

python3 scripts/frontmatter.py read artifacts/build-tasks/<ID>.md

frontmatter.py read validates the frontmatter against the schema as it reads. If it exits non-zero, the request is malformed at the schema level — that is an automatic fail. Record it (Step 3) with the error message and move to the next ID.

If the frontmatter is valid, also Read the file body — you need it for the coherence check.

Step 2: Run the Check

Four checks. All must pass for the request to be ready.

1. Completeness. Every required field is present and meaningful — schema validation in Step 1 already caught missing/mistyped fields, so here catch what it cannot: empty lists, and placeholder values (TBD, ???, TODO, <...>).
2. Internal coherence. The request must not contradict itself:
   • The body names accelerators, architectures, or HW SKUs that are not in the matching frontmatter list (or vice versa).
   • deliverable_kind: sub_version_build but pytorch_version is an X.Y.0 release (a sub-version build patches an existing minor).
   • deliverable_kind: build but pytorch_version is an X.Y.Z patch with Z > 0.
   • The body's stated intent contradicts a frontmatter list (e.g. body says "CPU-only" but accelerator_targets lists a GPU stack).
3. Deadline sanity. requested_completion must be a valid ISO 8601 date (YYYY-MM-DD) and not already in the past. Compare to today (python3 scripts/state.py timestamp). Do not judge whether the lead time is "enough" — that is a tech-lead call.
4. Validation gate. validation_definitions must be concrete — named suites, links, or explicit pass criteria. Vague entries ("run the tests", "make sure it works") are a gap: a tech lead cannot scope the work from them.

Step 3: Write the Review

For each ID, write artifacts/build-reviews/<ID>-review.md.

First Write the findings as the file body — plain markdown, no frontmatter:

### Definition-of-ready check — <ID>

**Completeness**: <ok | list of empty / placeholder fields>
**Internal coherence**: <ok | list of contradictions>
**Deadline**: <ok | past date | malformed date>
**Validation gate**: <concrete | vague — list the entries to make concrete>

**To fix before this can be filed**: <none | numbered list>

Then set the frontmatter (frontmatter.py set on the existing file prepends validated frontmatter and keeps the body):

python3 scripts/frontmatter.py set artifacts/build-reviews/<ID>-review.md \
    build_id=<ID> \
    pass=<true|false> \
    recommendation=<submit|revise> \
    needs_attention=<true|false>

• pass = true iff all four checks pass.
• recommendation = submit if pass, else revise.
• needs_attention = true if the request passes but something is still worth a human glance (e.g. a valid but unusual field). A passing request with needs_attention=true still goes to submit.

If Step 1 found invalid frontmatter, write the review with the schema error instead and skip Steps 2's findings body:

python3 scripts/frontmatter.py set artifacts/build-reviews/<ID>-review.md \
    build_id=<ID> pass=false recommendation=revise needs_attention=true \
    error="frontmatter_invalid: <msg>"

Step 4: Promote to Ready

For each ID where recommendation == submit, flip the task status:

python3 scripts/frontmatter.py set artifacts/build-tasks/<ID>.md status=Ready

For recommendation == revise, leave status: Draft so the requester sees it as not ready.

Step 5: Finalize

Rebuild the index once:

python3 scripts/frontmatter.py rebuild-index --pipeline build

If --headless is set, output the text "torch.build.review step completed." and stop.

Otherwise, summarize per-ID:

• submit → the request is ready for /torch.build.submit.
• revise → list what the requester must fix (from the review file body).

$ARGUMENTS