torch-internal-review

name	torch.internal.review
description	Validate an internal ask — a definition-of-ready check. Confirms the request is complete, well-formed, internally coherent, and carries the governance signal (named approver + approval status) submission requires, then writes a review file.
user-invocable	true
allowed-tools	Read, Write, Glob, Bash

You validate internal asks. 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, coherent, and pinned to a named approver — enough for the team to act on? You do NOT judge whether the change is a good idea, how hard it is, or whether the working group's design holds up. The team lead and architect own that.

You gate a request only when it is malformed: a missing field, an empty list, a placeholder, a self-contradiction, or a past deadline. approval_status does NOT gate submission — it lands in Jira as a label so the named approver can confirm or reject it in-system.

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 (INT-NNN or AIPCC-NNNNN). If empty, default to every INT-*.md file in artifacts/internal-tasks/ with status: Draft or status: Ready.

Persist the ID list:

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

Step 1: Read Each Request

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

python3 scripts/frontmatter.py read artifacts/internal-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 — 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 for the coherence check.

Step 2: Run the Check

Five 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 a working group, subsystem, or upstream PR that disagrees with the frontmatter; the stated internal_kind contradicts the body (e.g., backport with no related_upstream_pr); etc.
3. Deadline sanity. requested_completion is a valid ISO 8601 date (YYYY-MM-DD) and not already in the past. Compare to today (python3 scripts/state.py timestamp).
4. Validation definitions. validation_definitions is non-empty and each entry is concrete — names a suite or an actual gate, not "test it" or "the usual".
5. Named approver. team_lead_approver is set and is not a placeholder. approval_status itself does NOT gate submission — that's tracked in Jira after filing.
6. Backport coherence. When internal_kind: backport, related_upstream_pr must be set (the PR being cherry-picked). Missing it is an automatic fail.

In addition, the review flags but does not block (sets needs_attention: true) when:

• approval_status is anything other than Approved. The default intake state is Pending, so most fresh asks trip this flag — the flag's job is to surface the ticket to the named approver after filing.
• internal_kind: rfc_handoff and design_reference is unset. RFCs sometimes lag the ticket.

Step 3: Write the Review

For each ID, write artifacts/internal-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 definitions**: <ok | empty | vague entries — say which>
**Named approver**: <ok | approver missing or placeholder>
**Backport coherence**: <ok | n/a | related_upstream_pr missing>

**Flagged (non-blocking)**: <none | approval_status pending | design_reference missing on rfc_handoff>

**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/internal-reviews/<ID>-review.md \
    internal_id=<ID> \
    pass=<true|false> \
    recommendation=<submit|revise> \
    needs_attention=<true|false>

• pass = true iff all six checks pass.
• recommendation = submit if pass, else revise.
• needs_attention = true if approval_status != Approved OR an rfc_handoff has no design_reference. Most fresh asks will be Pending and will set this flag — that's the intended signal to the named approver.

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

python3 scripts/frontmatter.py set artifacts/internal-reviews/<ID>-review.md \
    internal_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/internal-tasks/<ID>.md status=Ready

For recommendation == revise, leave status: Draft.

Step 5: Finalize

Rebuild the index once:

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

If --headless is set, output "torch.internal.review step completed." and stop. Otherwise summarize per-ID:

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

$ARGUMENTS